Metadata-Version: 2.4
Name: ctkfontawesome
Version: 0.5.0
Summary: Use any of the 2k+ free FontAwesome icons in your tkinter application.
License-Expression: MIT
License-File: LICENSE
Keywords: svg,fontawesome,icons,tkinter,ttk
Author: Clive Bostock
Author-email: cbostock20@gmail.com
Requires-Python: >=3.8
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Provides-Extra: images
Requires-Dist: CairoSVG (>=2.7.0) ; extra == "images"
Requires-Dist: Pillow (>=9.0.0) ; extra == "images"
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* [FontAwesome 6.5 icons](https://fontawesome.com/v6/icons?o=r&m=free).
The **fill color** and **size** are customized to your specifications and then converted
to an object via an optional image backend based on CairoSVG and Pillow that can be used anywhere you would use a `tkinter.PhotoImage` object.

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

## Installation

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

This installs the icon database and SVG lookup helpers without any native or compiled dependencies.

If you also want `icon_to_image()` or `icon_to_ctkimage()`, install the optional image dependencies:

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

This installs CairoSVG, Pillow, and CustomTkinter for SVG rasterization and image support.

## Icon Browser

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

```shell
ctkfontawesome-browser
```

The browser itself is included in the base install, but live image previews
require the optional image dependencies:

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

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

## Development

This repository now supports a Poetry-based development workflow.

```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 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
```

## Usage

```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()
```

## CustomTkinter Usage

```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()
```

## Usage Without Image Dependencies

```python
from ctkfontawesome import icon_to_svg

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

![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 color of the svg path.                                       | 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 dependencies.

## 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)

