# QtAwesome - Font Awesome for Qt Applications QtAwesome is a library to add [Font Awesome](https://fontawesome.com) icons to your [Qt application](http://qt-project.org/). ## Table of Contents - [Latest Release 7](#latest-release-7) - [Installation Free Version](#installation-free-version) - [Installation Pro version](#installation-pro-version) - [Installation Pro Plus version](#installation-pro-plus-version) - [Basic Usage](#basic-usage) - [Examples](#examples) - [Example Custom Painter](#example-custom-painter) - [Default options](#default-options) - [Known Issues And Workarounds](#known-issues-and-workarounds) - [Thanks](#thanks) - [Contact](#contact) - [License](#license) ## Latest Release 7 Updated to Font Awesome 7 When using Pro+, the extra styles Chisel, Etch, Jelly, Notdog, Slab, Thumbprint and Whiteboard are available. [View changelog](CHANGES.md) Having troubles with this new release? - The [main](https://github.com/gamecreature/QtAwesome/) branch contains the latest Font Awesome 7 version. - The [fontawesome-6](https://github.com/gamecreature/QtAwesome/tree/fontawesome-6) branch contains the Font Awesome 6 version - The [fontawesome-5](https://github.com/gamecreature/QtAwesome/tree/fontawesome-5) branch contains the Font Awesome 5 version. - You can find the previous `master` branch in the [fontawesome-4](https://github.com/gamecreature/QtAwesome/tree/fontawesome-4) branch. (`master` is dropped in favour of `main`) - Open a github issue if you've found a bug or have a suggestion ## Installation Free Version You can include QtAweome to your project by copying the QtAwesome directory to your project tree and add the following `include()` to your Qt project file: ```sh CONFIG+=fontAwesomeFree include(QtAwesome/QtAwesome.pri) ``` Now you are good to go! The free fonts are included in this project. ## Installation Pro version To activate the pro version, `fontAwesomePro` config should be defined. ```sh CONFIG+=fontAwesomePro include(QtAwesome/QtAwesome.pri) ``` And the pro font files need to be copied to the `QtAwesome/fonts/pro` folder. ## Installation Pro Plus version To activate the pro+ version, `fontAwesomePro` config should be defined. ```sh CONFIG+=fontAwesomePro include(QtAwesome/QtAwesome.pri) ``` Using the fontAwesomePro config, implies the definition of FONT_AWESOME_PRO, and FONT_AWESOME_PRO_PLUS) Place the pro+ font files to the `QtAwesome/fonts/pro` folder. ## Basic Usage Create a single QtAwesome object for your whole application. ```c++ fa::QtAwesome* awesome = new fa::QtAwesome(qApp) awesome->initFontAwesome(); // This line is important as it loads the font and initializes the named icon map ``` - Add an accessor to this object (i.e. a global function, member of your application object, or whatever you like). - Use an icon name from the [Font Awesome Library](https://fontawesome.com/icons). For QML Usage please look at the embedded QtAwesomeSampleQml project. And the QML documentation in the readme. ## Examples Next the icons can be accessed via the `awesome->icon` method. ```c++ // The most performant operation the get an icon QPushButton* btn = new QPushButton(awesome->icon(fa::fa_solid, fa::fa_wine_glass), "Cheers!"); // You can also use 'string' names to access the icons. QPushButton* btn = new QPushButton(awesome->icon("fa-solid fa-coffee" ), "Black please!"); // The string items passed to the icon method can be used without the 'fa-' prefix QPushButton* btn = new QPushButton(awesome->icon("solid coffee" ), "Black please!"); // The style is also optional and will fallback to the 'solid' style QPushButton* btn = new QPushButton(awesome->icon("coffee" ), "Black please!"); ``` For shorter syntax (more Font Awesome like) is possible to bring the fa namespace into the current scope: ```c++ using namespace fa; QPushButton* btn = new QPushButton(awesome->icon(fa_solid, fa_wine_glass), "Cheers!"); ``` It is possible to create some extra options for the icons. The available options can be found in the [Default options list](#default-options) ```c++ QVariantMap options; options.insert("color" , QColor(255, 0 ,0)); QPushButton* musicButton = new QPushButton(awesome->icon(fa::fa_solid, fa::music, options), "Music"); ``` The defaults option can also be adjusted via the `setDefaultOption` method. For example having green disabled icons, it is possible to call: ```c++ awesome->setDefaultOption("color-disabled", QColor(0, 255, 0)); ``` It also possible to render a label directly with this font ```c++ QLabel* label = new QLabel(QChar(fa::fa_github)); label->setFont(awesome->font(fa::fa_brands, 16)); ``` ## Example Custom Painter This example registers a custom painter for supporting an custom icon named 'duplicate' It simply draws 2 "plus marks". ```c++ class DuplicateIconPainter : public QtAwesomeIconPainter { public: virtual void paint(QtAwesome* awesome, QPainter* painter, const QRect& rectIn, QIcon::Mode mode, QIcon::State state, const QVariantMap& options) { int drawSize = qRound(rectIn.height() * 0.5); int offset = rectIn.height() / 4; QChar chr = QChar(static_cast(fa::plus)); int st = fa::fa_solid; painter->setFont(st, awesome->font(drawSize)); painter->setPen(QColor(100,100,100)); painter->drawText(QRect(QPoint(offset * 2, offset * 2), QSize(drawSize, drawSize)), chr , QTextOption(Qt::AlignCenter|Qt::AlignVCenter)); painter->setPen(QColor(50,50,50)); painter->drawText(QRect(QPoint(rectIn.width() - drawSize-offset, rectIn.height() - drawSize - offset), QSize(drawSize, drawSize) ), chr , QTextOption(Qt::AlignCenter | Qt::AlignVCenter)); } }; awesome->give("duplicate", new DuplicateIconPainter()); ``` After this, this icon can be used with the given string name: ```c++ awesome->icon("duplicate") ``` ## Default options The following options are the defaults in the QtAwesome class. ```c++ setDefaultOption("color", QApplication::palette().color(QPalette::Normal, QPalette::Text)); setDefaultOption("color-disabled", QApplication::palette().color(QPalette::Disabled, QPalette::Text)); setDefaultOption("color-active", QApplication::palette().color(QPalette::Active, QPalette::Text)); setDefaultOption("color-selected", QApplication::palette().color(QPalette::Active, QPalette::Text)); setDefaultOption("text", QString()); // internal option setDefaultOption("text-disabled", QString()); setDefaultOption("text-active", QString()); setDefaultOption("text-selected", QString()); setDefaultOption("scale-factor", 0.9); ``` Extra items for the pro version ```c++ setDefaultOption("duotone-color", QApplication::palette().color(QPalette::Normal, QPalette::BrightText)); setDefaultOption("duotone-color-disabled", QApplication::palette().color(QPalette::Disabled, QPalette::BrightText)); setDefaultOption("duotone-color-active", QApplication::palette().color(QPalette::Active, QPalette::BrightText)); setDefaultOption("duotone-color-selected", QApplication::palette().color(QPalette::Active, QPalette::BrightText)); ``` When creating an icon, it first populates the options map with the default options from the QtAwesome object. After that the options are expanded/overwritten by the options supplied to the icon. It is possible to use another glyph per icon-state. For example to make an icon-unlock symbol switch to locked when selected, you could supply the following option: ```c++ options.insert("text-selected", QString(fa::fa_lock)); ``` Color and text options have the following structure: `keyname-iconmode-iconstate` When iconmode normal is empty\ And iconstate on is blank So the list of items used is: - color - color-disabled - color-active - color-selected - color-off - color-disabled-off - color-active-off - color-selected-off - duotone-color (pro) - duotone-color-disabled (pro) - duotone-color-active (pro) - duotone-color-selected (pro) - duotone-color-off (pro) - duotone-color-disabled-off (pro) - duotone-color-active-off (pro) - duotone-color-selected-off (pro) - text - text-disabled - text-active - text-selected - text-off - text-disabled-off - text-active-off - text-selected-off - style - style-disabled - style-active - style-selected - style-off - style-disabled-off - style-active-off - style-selected-off ## QML Usage For QML usage you can register the `QtAwesomeQuickImageProvider`. ```c++ fa::QtAwesome* awesome = new fa::QtAwesome(qApp); awesome->initFontAwesome(); QQmlApplicationEngine engine; engine.addImageProvider("fa", new QtAwesomeQuickImageProvider(awesome)); ``` After doing this it possible to access the icons via the following URL format: `image://fa/type/name?options` Some examples URLs - image://fa/solid/user - image://fa/regular/thumbs-up - image://fa/solid/beer?color=FFFF77 QML Example: ```qml Image { anchors.fill: parent source: "image://fa/regular/thumbs-up" } ``` ## Known Issues And Workarounds On Mac OS X, placing an qtAwesome icon in QMainWindow menu, doesn't work directly. See the following issue: [https://github.com/gamecreature/QtAwesome/issues/10] A workaround for this problem is converting it to a Pixmap icon: ```c++ QAction* menuAction = new QAction("test"); menuAction->setIcon(awesome->icon(fa::fa_heart).pixmap(32,32)); ``` ## Thanks Thanks go to the contributors of this project! Many thanks go to Dave Gandy and the other Font Awesome contributors!! [https://github.com/FortAwesome/Font-Awesome](https://github.com/FortAwesome/Font-Awesome) And of course to the Qt team/contributors for supplying this great cross-platform c++ library. Contributions are welcome! Feel free to fork and send a pull request through Github. *Contribution list made with [contrib.rocks](https://contrib.rocks).* ## Contact - email: - mastedon: [https://ruby.social/@rick](https://ruby.social/@rick) - twitter: [https://twitter.com/gamecreature](https://twitter.com/gamecreature) - website: [https://gamecreatures.com](https://gamecreatures.com) - github: [https://github.com/gamecreature/QtAwesome](https://github.com/gamecreature/QtAwesome) ## License MIT License. Copyright 2013-2025 - Ribit Software by Blommers IT. [https://blommersit.nl/](https://blommersit.nl) The Font Awesome font is licensed under the SIL Open Font License - [https://scripts.sil.org/OFL](http://scripts.sil.org/OFL) The Font Awesome pictograms are licensed under the CC BY 3.0 License - [https://creativecommons.org/licenses/by/3.0/](http://creativecommons.org/licenses/by/3.0/) "Font Awesome by Dave Gandy - "