QtAwesome - Font Awesome for Qt Applications

QtAwesome is a library to add Font Awesome icons to your Qt application.

Table of Contents

• Latest Release 7
• Installation Free Version
• Installation Pro version
• Installation Pro Plus version
• Basic Usage
• Examples
• Example Custom Painter
• Default options
• Known Issues And Workarounds
• Thanks
• Contact
• 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

Having troubles with this new release?

• The main branch contains the latest Font Awesome 7 version.
• The fontawesome-6 branch contains the Font Awesome 6 version
• The fontawesome-5 branch contains the Font Awesome 5 version.
• You can find the previous master branch in the 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:

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.

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.

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.

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.

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.

// 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:

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

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:

awesome->setDefaultOption("color-disabled", QColor(0, 255, 0));

It also possible to render a label directly with this font

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".

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<int>(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:

awesome->icon("duplicate")

Default options

The following options are the defaults in the QtAwesome class.

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

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:

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.

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:

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: [#10]

A workaround for this problem is converting it to a Pixmap icon:

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

Contact

• email: [email protected]
• mastedon: https://ruby.social/@rick
• twitter: https://twitter.com/gamecreature
• website: https://gamecreatures.com
• github: https://github.com/gamecreature/QtAwesome

License

MIT License. Copyright 2013-2025 - Ribit Software by Blommers IT. https://blommersit.nl/

The Font Awesome font is licensed under the SIL Open Font License - https://scripts.sil.org/OFL The Font Awesome pictograms are licensed under the CC BY 3.0 License - https://creativecommons.org/licenses/by/3.0/ "Font Awesome by Dave Gandy - https://github.com/FortAwesome/Font-Awesome"