Metadata-Version: 2.4
Name: ctkfontawesome
Version: 0.8.0
Summary: Use any of the 2k+ free FontAwesome icons in your CustomTkinter / Tkinter applications.
License-Expression: MIT
License-File: LICENSE
Keywords: fontawesome,icons,customtkinter,tkinter,svg,browser
Author: Clive Bostock
Author-email: cbostock20@gmail.com
Requires-Python: >=3.8
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Provides-Extra: cairosvg
Provides-Extra: images
Requires-Dist: CairoSVG (>=2.7.0) ; extra == "cairosvg"
Requires-Dist: Pillow (>=9.0.0)
Requires-Dist: customtkinter (>=5.2.0) ; extra == "images"
Project-URL: Homepage, https://github.com/avalon60/CTkFontAwesome
Project-URL: Issues, https://github.com/avalon60/CTkFontAwesome/issues
Project-URL: Repository, https://github.com/avalon60/CTkFontAwesome
Description-Content-Type: text/markdown

[![GitHub issues](https://img.shields.io/github/issues/avalon60/CTkFontAwesome.svg)](https://github.com/avalon60/CTkFontAwesome/issues)
[![License](https://img.shields.io/github/license/avalon60/CTkFontAwesome.svg)](https://github.com/avalon60/CTkFontAwesome/blob/main/LICENSE)

# CTkFontAwesome

> Requires Python **3.8+**

CTkFontAwesome is a maintained continuation and repackaging of the original
TkFontAwesome project by Israel Dryer.

A library that enables you to use [FontAwesome icons](https://fontawesome.com/v6/icons?o=r&m=free)
in your CustomTkinter / Tkinter application.

You may use any of the 2k+ *free* Font Awesome icons bundled with the package.
The **fill colour** and **size** are customised to your specifications and then rendered
with packaged Font Awesome fonts plus Pillow, so normal image generation works on
Windows, Linux, and macOS without requiring Cairo, GTK, CairoSVG, or `tksvg`.

![example-2](https://raw.githubusercontent.com/avalon60/CTkFontAwesome/main/assets/example-2.png)

## Highlights

- Use 2k+ bundled free Font Awesome icons without downloading assets at runtime
- Render icons with bundled Font Awesome fonts and Pillow by default
- Generate `customtkinter.CTkImage` objects for DPI-aware CustomTkinter widgets
- Generate `tkinter.PhotoImage` objects for Tkinter widgets
- Launch an icon browser to search icons, preview them, and copy ready-to-use code
- Access raw SVG XML when you want to manage rendering yourself

## Icon Browser

CTkFontAwesome includes an installable browser for searching the bundled icon set,
previewing icons, and copying ready-to-use CustomTkinter code snippets.

```shell
ctkfontawesome-browser
```

The browser is included in the base install. If you want live CustomTkinter
previews in the browser, install the optional CustomTkinter dependency:

```shell
python -m pip install "ctkfontawesome[images]"
```

![CTkFontAwesome browser](assets/browser.png)

## Installation

```shell
python -m pip install ctkfontawesome
```

This installs Pillow plus the bundled icon metadata and font assets. The
default `icon_to_image()` and `icon_to_pil()` rendering path does not require
any native Cairo or GTK runtime.

If you also want `icon_to_ctkimage()` for CustomTkinter widgets, install the
optional CustomTkinter dependency:

```shell
python -m pip install "ctkfontawesome[images]"
```

If you explicitly want the legacy SVG-to-raster Cairo backend, install CairoSVG
separately:

```shell
python -m pip install "ctkfontawesome[cairosvg]"
```

`tksvg` is not used by this project.

## CustomTkinter Usage

Use `icon_to_ctkimage()` when you want a `customtkinter.CTkImage` for
CustomTkinter widgets.

```python
import customtkinter as ctk
from ctkfontawesome import icon_to_ctkimage

app = ctk.CTk()
icon = icon_to_ctkimage("eye", fill="#1D9F75", scale_to_width=28)

button = ctk.CTkButton(app, text="Preview", image=icon, compound="left")
button.pack(padx=20, pady=20)

app.mainloop()
```

## Tkinter Usage

Use `icon_to_image()` when you want a `tkinter.PhotoImage` for standard Tkinter
widgets.

```python
import tkinter as tk
from ctkfontawesome import icon_to_image

root = tk.Tk()
fb = icon_to_image("facebook", fill="#4267B2", scale_to_width=64)
send = icon_to_image("paper-plane", fill="#1D9F75", scale_to_width=64)

tk.Label(root, image=fb).pack(padx=10, pady=10)
tk.Button(root, image=send).pack(padx=10, pady=10)

root.mainloop()
```

## Usage Without CairoSVG

If you only need the bundled icon data, use `icon_to_svg()`. CairoSVG is only
required when you explicitly choose the legacy SVG backend.

```python
from ctkfontawesome import icon_to_svg

svg = icon_to_svg("facebook")
print(svg[:80])
```

## Development

```shell
poetry install
```

To install the optional image backend in the Poetry environment:

```shell
poetry install --extras images
```

To run the icon browser during development:

```shell
poetry run ctkfontawesome-browser
```

To run the automated test suite:

```shell
poetry run pytest -q
```

If you are using the project virtualenv directly instead of Poetry:

```shell
.venv/bin/python -m pytest -q
```

To refresh the bundled free Font Awesome assets from the upstream npm package,
use the repo-level maintainer helper:

```shell
./utils/get_new_fa_icons.sh --python .venv/bin/python
```

This maintainer command installs `@fortawesome/fontawesome-free` into a
temporary directory, then refreshes:

- [`ctkfontawesome/svgs.py`](ctkfontawesome/svgs.py)
- packaged metadata under `ctkfontawesome/assets/metadata/`
- packaged font files under `ctkfontawesome/assets/fonts/`

The helper also runs the generated-data smoke test after refreshing those
assets.

Requirements for the update workflow:

- `npm` must be available on `PATH`
- the selected Python must have `fonttools` and `brotli` installed

Example preparation:

```shell
.venv/bin/python -m pip install fonttools brotli
```

Recommended update workflow:

1. Refresh the checked-in bundled assets:

   ```shell
   ./utils/get_new_fa_icons.sh --python .venv/bin/python
   ```

2. Run the automated test suite:

   ```shell
   .venv/bin/python -m pytest -q
   ```

If you want to inspect a candidate `svgs.py` file without touching the checked-in
module, the lower-level Python helper is still available:

```shell
.venv/bin/python development/update_fontawesome.py --output /tmp/svgs_new.py
.venv/bin/python development/smoke_test_fontawesome_update.py /tmp/svgs_new.py
```

The smoke test validates the generated module shape, checks a known icon is
present, and compares counts with the current checked-in data. The repo-level
wrapper runs the default smoke test automatically when refreshing the checked-in
assets.

To compare a generated file against the current checked-in data:

```shell
.venv/bin/python development/smoke_test_fontawesome_update.py /tmp/svgs_new.py --compare-to ctkfontawesome/svgs.py
```

To bump the package version and create a git commit and tag:

```shell
poetry run bump2version patch
```

Use `minor` or `major` instead of `patch` when appropriate. The bump updates
both `pyproject.toml` and `ctkfontawesome/__init__.py`.

Once installed, you can launch the browser with:

```shell
ctkfontawesome-browser
```

![example-1](https://raw.githubusercontent.com/avalon60/CTkFontAwesome/main/assets/example-1.png)

## API: `icon_to_image()`

```python
(
    name=None,
    fill=None,
    scale_to_width=None,
    scale_to_height=None,
    scale=1
)
```

### Parameters

| Name              | Type  | Description                                                           | Default   |
|-------------------|-------|-----------------------------------------------------------------------|-----------|
| name              | str   | The name of the FontAwesome icon.                                     | None      |
| fill              | str   | The fill colour of the rendered icon.                                 | None      |
| scale_to_width    | int   | Adjust image width to this size (in pixels); maintains aspect ratio.  | None      |
| scale_to_height   | int   | Adjust image height to this size (in pixels); maintains aspect ratio. | None      |
| scale             | float | Scale the image width and height by this factor.                      | 1         |

## API: `icon_to_ctkimage()`

Same parameters as `icon_to_image()`, but returns a `customtkinter.CTkImage`
for DPI-aware use in CustomTkinter widgets. This API requires the
`ctkfontawesome[images]` optional dependency for CustomTkinter.

`icon_to_ctkimage()` also accepts an optional `dark_fill` argument so light and
dark theme variants can use different colours.

## API: Explicit CairoSVG backend

The default backend is Pillow plus packaged Font Awesome fonts. If you need the
legacy SVG route for a specific use case, pass `backend="cairosvg"` to
`icon_to_pil()`, `icon_to_image()`, or `icon_to_ctkimage()` after installing
`ctkfontawesome[cairosvg]`.

## API: `icon_to_svg()`

Returns the raw SVG XML string for the requested icon name.

## License

The [CC BY 4.0](https://fontawesome.com/license/free) license applies to all FontAwesome *free* icons used in the library.
The MIT License applies to all other work.

---

**Maintainer**: Clive Bostock
Original project concept and implementation by [Israel Dryer](https://github.com/israel-dryer)
📦 Available on [PyPI](https://pypi.org/project/ctkfontawesome/) | 🐙 [GitHub](https://github.com/avalon60/CTkFontAwesome)

