QtAwesome Documentation

repository·master·Indexed 21 days ago

A library for using iconic fonts such as Font Awesome, Material Design Icons, Phosphor, Elusive Icons, Remix Icon, and Microsoft Codicons within PyQt and PySide applications. It provides a high-level API for creating, styling, stacking, and animating icons, including a built-in icon browser (qta-browser) and various animation classes like qta.Spin, qta.Pulse, and qta.Breathe.

Tokens: 7.4K
Snippets: 20
Records: 23
Agent score: 73%

What's inside QtAwesome

Introduction to QtAwesome
master
QtAwesome is a library that enables the use of iconic fonts (such as Font Awesome, Elusive Icons, Material Design Icons, etc.) within PyQt and PySide applications. It is a Python port of the original C++ QtAwesome library.
https://github.com/spyder-ide/qtawesome/blob/master/docs/source/introduction.rst
Identify icons using prefixes and names
master
QtAwesome identifies icons using a specific naming convention: a prefix followed by a period (.), and then the icon name.
Example format: prefix.icon_name
https://github.com/spyder-ide/qtawesome/blob/master/docs/source/usage.rst
How to identify icons using prefixes
master
QtAwesome identifies icons using a prefix and an icon name, separated by a period (.). For example, fa6s.flag uses the FontAwesome 6 Solid prefix and the flag icon name.
Available Prefixes:
- FontAwesome 6.x:
  fa6: Regular style
  fa6s: Solid style
  fa6b: Brands
- FontAwesome 5.x:
  fa5: Regular style
  fa5s: Solid style
  fa5b: Brands
- Elusive Icons: ei
- Material Design Icons:
  mdi6: Version 6.9.96
  mdi: Version 5.9.55
- Phosphor: ph
- Remix Icon: ri
- Microsoft Codicons: msc
```
import qtawesome as qta

# Example: FontAwesome 6 Solid flag
icon = qta.icon('fa6s.flag')

# Example: Material Design Icon
mdi_icon = qta.icon('mdi6.access-point-network')
```
https://github.com/spyder-ide/qtawesome/blob/master/README.md

Update Remix Icon

master

To update Remix Icon, follow these steps:

Download the .ttf font from the official source.
Regenerate the JSON charmap using the remixicon.css file from the official source.
Update the version number, icon counts, and URLs in README.md and qtawesome/docs/source/usage.rst.

Use the following automation script to download the TTF, generate the charmap, and print the MD5 hash for __init__.py.

import re
import json
import urllib.request
import hashlib

VERSION = '2.5.0'  # Update version as required
TTF_URL = 'https://raw.githubusercontent.com/Remix-Design/RemixIcon/master/fonts/remixicon.ttf'
CSS_URL = 'https://raw.githubusercontent.com/Remix-Design/RemixIcon/master/fonts/remixicon.css'
FONT_FILENAME = 'remixicon-{version}.ttf'.format(version=VERSION)
FONT_CHARMAP_FILENAME = "remixicon-charmap-{version}.json".format(version=VERSION)

with open(FONT_FILENAME, 'wb') as fp:
    req = urllib.request.urlopen(TTF_URL)
    if req.status != 200:
        raise Exception('Failed to download TTF')
    fp.write(req.read())
    req.close()

hasher = hashlib.md5()
with open(FONT_FILENAME, 'rb') as f:
    content = f.read()
    hasher.update(content)

ttf_calculated_hash_code = hasher.hexdigest()
print('MD5 :', ttf_calculated_hash_code)

req = urllib.request.urlopen(CSS_URL)
if req.status != 200:
    raise Exception('Failed to download CSS Charmap')

rawcss = req.read().decode()
req.close()

charmap = {}
pattern = '^\.ri-(.+):before {\s*content: "(.+)";\s*}$'
data = re.findall(pattern, rawcss, re.MULTILINE)
for name, key in data:
    key = key.replace('\\', '0x')
    name = name.lower()
    charmap[name] = key

with open(FONT_CHARMAP_FILENAME, 'w') as fp:
    json.dump(charmap, fp, indent=4, sort_keys=True)

Update FontAwesome icons
master
To update FontAwesome icons in the repository, follow these steps:
1. Check for the latest released version on the FontAwesome releases page.
2. Update the font version in __init__.py.
3. Remove outdated files in the fonts directory.
4. Execute the update script using setup.py:
  python setup.py update_fa6 --fa-version X.X.X
5. Update the FontAwesome version number, icon counts, and URLs in README.md and qtawesome/docs/source/usage.rst.
```
python setup.py update_fa6 --fa-version X.X.X
```
https://github.com/spyder-ide/qtawesome/blob/master/UPDATE.md

Update Phosphor icons

master

To update Phosphor icons, follow these steps:

Download the .ttf font from the official source.
Regenerate the JSON charmap using the phosphor.css file from the official source.
Update the version number, icon counts, and URLs in README.md and qtawesome/docs/source/usage.rst.

Use the following automation script to download the TTF, generate the charmap, and print the MD5 hash for __init__.py.

import re
import json
import urllib.request
import hashlib

VERSION = '1.3.0'  # Update version as required
TTF_URL = 'https://raw.githubusercontent.com/phosphor-icons/phosphor-icons/master/src/font/phosphor.ttf'
CSS_URL = 'https://raw.githubusercontent.com/phosphor-icons/phosphor-icons/master/src/css/phosphor.css'
FONT_FILENAME = 'phosphor-{version}.ttf'.format(version=VERSION)
FONT_CHARMAP_FILENAME = "phosphor-charmap-{version}.json".format(version=VERSION)

with open(FONT_FILENAME, 'wb') as fp:
    req = urllib.request.urlopen(TTF_URL)
    if req.status != 200:
        raise Exception('Failed to download TTF')
    fp.write(req.read())
    req.close()

hasher = hashlib.md5()
with open(FONT_FILENAME, 'rb') as f:
    content = f.read()
    hasher.update(content)

ttf_calculated_hash_code = hasher.hexdigest()
print('MD5 :', ttf_calculated_hash_code)

req = urllib.request.urlopen(CSS_URL)
if req.status != 200:
    raise Exception('Failed to download CSS Charmap')

rawcss = req.read().decode()
req.close()

charmap = {}
pattern = '^\.ph-(.+):before {\s*content: "(.+)";\s*}$'
data = re.findall(pattern, rawcss, re.MULTILINE)
for name, key in data:
    key = key.replace('\\', '0x')
    name = name.lower()
    charmap[name] = key

with open(FONT_CHARMAP_FILENAME, 'w') as fp:
    json.dump(charmap, fp, indent=4, sort_keys=True)

Update Microsoft's Codicons
master
To update Codicons, follow these steps:
1. Check for the latest released version on the VS Code Codicons releases page.
2. Update the font version in __init__.py.
3. Remove outdated files in the fonts directory.
4. Execute the update script using setup.py:
  python setup.py update_msc --msc-version X.X.X
5. Update the Codicons version number, icon counts, and URLs in README.md and qtawesome/docs/source/usage.rst.
```
python setup.py update_msc --msc-version X.X.X
```
https://github.com/spyder-ide/qtawesome/blob/master/UPDATE.md
Launch the QtAwesome Icon Browser
master
QtAwesome includes a built-in graphical browser that allows you to visually browse all available icon sets. You can use the browser to search for specific icons and copy their exact names to use in your code.
To start the browser, run the qta-browser command from your terminal or shell after installing the package.
```
qta-browser
```
https://github.com/spyder-ide/qtawesome/blob/master/docs/source/icon_browser.rst
Update Elusive Icons
master
To update Elusive Icons, follow these steps:
1. Replace the existing .ttf font file with the new version.
2. Regenerate the charmap.json file using the icons.yml file from the upstream repository with the following script:
3. Update the Elusive Icons version number, icon counts, and URLs in README.md and qtawesome/docs/source/usage.rst.
```
import yaml, json

with open('icons.yml', 'r') as file:
    icons = yaml.load(file)['icons']

charmap = {icon['id']: icon['unicode'] for icon in icons}

for icon in icons:
    if 'aliases' in icon:
        for name in icon['aliases']:
            charmap[name] = icon['unicode']

with open('charmap.json', 'w') as file:
    json.dump(charmap, file, indent=4, sort_keys=True)
```
https://github.com/spyder-ide/qtawesome/blob/master/UPDATE.md
Install QtAwesome
master
You can install QtAwesome using conda (recommended) or pip.
```
# Using conda
conda install qtawesome

# Using pip
pip install qtawesome
```
https://github.com/spyder-ide/qtawesome/blob/master/README.md

Update Material Design Icons 6.x

master

To update Material Design Icons 6.x, follow these steps:

Download the .ttf font from the official source.
Regenerate the JSON charmap using the materialdesignicons.css file from the official source.
Update the version number, icon counts, and URLs in README.md and qtawesome/docs/source/usage.rst.

You can use the following automation script to download the TTF, generate the charmap, and print the MD5 hash required for __init__.py.

import re
import json
import urllib.request
import hashlib

VERSION = '6.9.96'  # Update version as required
TTF_URL = 'https://raw.githubusercontent.com/Templarian/MaterialDesign-Webfont/master/fonts/materialdesignicons-webfont.ttf'
CSS_URL = 'https://raw.githubusercontent.com/Templarian/MaterialDesign-Webfont/master/css/materialdesignicons.css'
FONT_FILENAME = "materialdesignicons6-webfont-{version}.ttf".format(
    version=VERSION
)
FONT_CHARMAP_FILENAME = (
    "materialdesignicons6-webfont-charmap-{version}.json".format(
        version=VERSION
    )
)


with open(FONT_FILENAME, 'wb') as fp:
    req = urllib.request.urlopen(TTF_URL)
    if req.status != 200:
        raise Exception('Failed to download TTF')
    fp.write(req.read())
    req.close()

hasher = hashlib.md5()
with open(FONT_FILENAME, 'rb') as f:
    content = f.read()
    hasher.update(content)

ttf_calculated_hash_code = hasher.hexdigest()
print('MD5 :', ttf_calculated_hash_code)

req = urllib.request.urlopen(CSS_URL)
if req.status != 200:
    raise Exception('Failed to download CSS Charmap')

rawcss = req.read().decode()
req.close()

charmap = {}
pattern = '^\.mdi-(.+)::before {\s*content: "(.+)";\s*}$'
data = re.findall(pattern, rawcss, re.MULTILINE)
for name, key in data:
    key = key.replace('\\F', '0xf').lower()
    key = key.replace('\\', '0x')
    name = name.lower()
    charmap[name] = key

with open(FONT_CHARMAP_FILENAME, 'w') as fp:
    json.dump(charmap, fp, indent=4, sort_keys=True)

Style icons with colors and states
master
Customize icon appearance using color parameters. You can define colors for different widget states:
- color: The default color.
- active: Color when the icon is in an active state.
- color_active: Color when the icon is active.
- color_off: Color when the icon is 'off' (for togglable widgets).
- color_off_active: Color when the icon is 'off' and active.
- color_on: Color when the icon is 'on'.
- color_on_active: Color when the icon is 'on' and active.
Alpha/Opacity: To set transparency, pass a tuple containing the color and an alpha value (integer between 0 and 255).
Toggling: For checkable widgets, use selected to define the icon used when the widget is checked.
```
# Basic styling
styling_icon = qta.icon('fa5s.music', active='fa5s.balance-scale', color='blue', color_active='orange')

# Setting alpha (0-255)
icon_with_alpha = qta.icon('mdi.heart', color=('red', 120))

# Toggling state styling
toggle_icon = qta.icon('fa5s.home', selected='fa5s.balance-scale', 
                      color_off='black', color_off_active='blue', 
                      color_on='orange', color_on_active='yellow')
```
https://github.com/spyder-ide/qtawesome/blob/master/docs/source/usage.rst

QtAwesome Documentation

What's inside QtAwesome

Available Prefixes: