ref #35, QML QuickImageProvider Support.

CHANGES.md

@@ -1,5 +1,6 @@
 # Changes
 
+- (2025-11-21) #35, QML QuickImageProvider Support. (contribution by @Ivorforce)
 - (2025-08-28) #67, Update to Font Awesome 7, added Pro+ icon support
 - (2025-07-15) #66, Style name parsing (stringToStyleEnum) not working properly (contribution by @samapico)
 - (2025-05-08) #65, Support for Qt 6.9. Fix the CMakelist example

CMakeLists.txt

@@ -41,6 +41,7 @@ project(QtAwesome VERSION ${QTAWESOME_VERSION} DESCRIPTION "Add Font Awesome ico
 
 find_package(QT NAMES Qt6 Qt5 REQUIRED COMPONENTS Core)
 find_package(Qt${QT_VERSION_MAJOR} REQUIRED COMPONENTS Core Widgets)
+find_package(Qt${QT_VERSION_MAJOR} COMPONENTS Quick Qml)
 
 set(CMAKE_AUTOUIC ON)
 set(CMAKE_AUTOMOC ON)
@@ -62,6 +63,14 @@ add_library(QtAwesome
 	${QtAwesome_HEADERS}
 )
 
+if(Qt6Quick_FOUND)
+  list(APPEND QtAwesome_HEADERS QtAwesome/QtAwesomeQuickImageProvider.h)
+  target_link_libraries(QtAwesome PUBLIC
+    Qt${QT_VERSION_MAJOR}::Quick
+    Qt${QT_VERSION_MAJOR}::Qml
+  )
+endif()
+
 include(GNUInstallDirs)
 
 target_include_directories(QtAwesome

QtAwesome/QtAwesome.cpp

@@ -17,6 +17,7 @@
 #include <QFontDatabase>
 #include <QFontMetrics>
 #include <QString>
+#include <QUrlQuery>
 
 
 #if (QT_VERSION >= QT_VERSION_CHECK(6, 5, 0))
@@ -587,6 +588,59 @@ QString QtAwesome::fontName(int style) const
     return _fontDetails[style].fontFamily();
 }
 
+/// \brief Requests a pixmap which can drictly be used by QQuickImageProvider
+///
+/// \param An identifier in the format "regular/name?option1=x&option2=y
+QPixmap QtAwesome::requestPixmap(const QString &id, QSize *size, const QSize &requestedSize)
+{
+    QString baseId = id;
+    QVariantMap options;
+
+    int queryStart = id.indexOf('?');
+    if (queryStart != -1) {
+        baseId = id.left(queryStart);
+        QString queryString = id.mid(queryStart + 1);
+
+        QUrlQuery query(queryString);
+        for (const auto &item : query.queryItems()) {
+            options.insert(item.first, item.second);
+        }
+        transformStringVariantOptions(options);
+    }
+
+    int nameStart = baseId.indexOf("/");
+    if (nameStart != -1) {
+      baseId = "fa-" + baseId.left(nameStart) + " fa-" + baseId.mid(nameStart + 1);
+    } else {
+      baseId = "fa-solid fa-" + baseId;
+    }
+
+    QIcon icn = icon(baseId, options);
+    QSize actualSize = requestedSize.isValid() ? requestedSize : QSize(128, 128);
+    if (size) {
+      *size = actualSize;
+    }
+
+    return icn.pixmap(actualSize);
+}
+
+
+/// \Brief Transforms a String based hash map to the correct objec types.
+///        All color types which aren't colors are converted to QColor objects and Interpreted
+///        as HEX codes (# is optional)
+void QtAwesome::transformStringVariantOptions(QVariantMap& options)
+{
+    for (auto i = options.cbegin(), end = options.cend(); i != end; ++i) {
+        QString key = i.key();
+        if (key.contains("color") && i.value().userType() == QMetaType::QString) {
+            QString value = i.value().value<QString>();
+            QColor colorValue = QColor(value[0] == '#' ? QColor(value) : QColor(QString("#%1").arg(value)));
+            options[key] = colorValue;
+        }
+    }
+}
+
+
 int QtAwesome::stringToStyleEnum(const QString style) const
 {
     if (style == "fa-solid") return fa::fa_solid;

QtAwesome/QtAwesome.h

@@ -216,6 +216,10 @@ public:
     /// Returns the font-name that is used as icon-map
     QString fontName(int style) const;
 
+    // Requests a pixmap which can be used by QQuickImageProvider
+    QPixmap requestPixmap(const QString &id, QSize *size, const QSize &requestedSize);
+    void transformStringVariantOptions(QVariantMap& options);
+
 protected:
     int stringToStyleEnum(const QString style) const;
     const QString styleEnumToString(int style) const;

QtAwesome/QtAwesomeQuickImageProvider.h

@@ -0,0 +1,20 @@
+#pragma once
+
+#include <QQuickImageProvider>
+#include "QtAwesome.h"
+
+class QtAwesomeQuickImageProvider : public QQuickImageProvider
+{
+public:
+    QtAwesomeQuickImageProvider(fa::QtAwesome* awesome)
+      : QQuickImageProvider(QQuickImageProvider::ImageType::Pixmap)
+      , _awesomeRef(awesome)
+    {}
+
+    virtual QPixmap requestPixmap(const QString &id, QSize *size, const QSize &requestedSize) {
+      return _awesomeRef->requestPixmap(id, size, requestedSize);
+    }
+
+private:
+    fa::QtAwesome* _awesomeRef;
+};

QtAwesomeSampleQml/CMakeLists.txt

@@ -0,0 +1,30 @@
+cmake_minimum_required(VERSION 3.16)
+project(QtAwesomeSampleQml)
+
+find_package(QT NAMES Qt6 Qt5 REQUIRED COMPONENTS Core)
+find_package(Qt${QT_VERSION_MAJOR} REQUIRED COMPONENTS Core Gui Qml Quick)
+
+set(CMAKE_CXX_STANDARD 17)
+set(CMAKE_CXX_FLAGS "")
+
+set(CMAKE_AUTOUIC ON)
+set(CMAKE_AUTOMOC ON)
+set(CMAKE_AUTORCC ON)
+
+add_subdirectory(../ QtAwesome)
+
+#qt6_add_resources(QT_RESOURCES qml.qrc)
+add_library(
+	main.qrc
+)
+
+add_executable(QtAwesomeSampleQml
+  main.cpp
+  main.qrc
+)
+
+target_link_libraries(QtAwesomeSampleQml
+  PUBLIC QtAwesome
+  PRIVATE Qt::Qml Qt::Quick
+)
+

QtAwesomeSampleQml/LICENSE.md

@@ -0,0 +1,36 @@
+MIT License
+===========
+
+Copyright 2013-2025 [Rick Blommers](mailto:rick@blommersit.nl). All Rights Reserved.
+Author [Rick Blommers](mailto:rick@blommersit.nl)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated
+documentation files (the "Software"), to deal in the Software without restriction, including without limitation
+the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software,
+and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO
+THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS
+OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+Font Awesome License
+====================
+
+[https://github.com/FortAwesome/Font-Awesome](https://github.com/FortAwesome/Font-Awesome)
+
+Font Awesome Free is free, open source, and GPL friendly. You can use it for commercial projects,
+open source projects, or really almost whatever you want.
+
+- Icons — CC BY 4.0 License
+In the Font Awesome Free download, the CC BY 4.0 license applies to all icons packaged as .svg and .js files types.
+- Fonts — SIL OFL 1.1 License
+In the Font Awesome Free download, the SIL OLF license applies to all icons packaged as web and desktop font files.
+- Code — MIT License
+In the Font Awesome Free download, the MIT license applies to all non-font and non-icon files.
+Attribution is required by MIT, SIL OLF, and CC BY licenses. Downloaded Font Awesome Free files already contain embedded comments with sufficient attribution, so you shouldn't need to do anything additional when using these files normally.
+
+We've kept attribution comments terse, so we ask that you do not actively work to remove them from files,
+especially code. They're a great way for folks to learn about Font Awesome.

QtAwesomeSampleQml/README.md

@@ -0,0 +1,15 @@
+# QML Sample
+
+A simple qml sample for using QtAwesome with QML.
+I've never used qml before, so please let me know if things can be improved.
+
+Sample building with cmake:
+
+```sh
+cd QtAwesomeSampleQml
+mkdir build
+cd build
+
+cmake .. -DCMAKE_PREFIX_PATH="~/Qt/6.10.1/macos/lib/cmake/"
+cmake --build .
+```

QtAwesomeSampleQml/main.cpp

@@ -0,0 +1,31 @@
+/**
+ * MIT Licensed
+ *
+ * Copyright 2011-2025 - Ribit Software by Blommers IT. All Rights Reserved.
+ * Author Rick Blommers
+ */
+
+#include "QtAwesome.h"
+
+#include <QApplication>
+#include <QQmlApplicationEngine>
+
+#include "QtAwesome.h"
+#include "QtAwesomeQuickImageProvider.h"
+
+int main(int argc, char** argv)
+{
+    QApplication app(argc, argv);
+
+    fa::QtAwesome* awesome = new fa::QtAwesome(qApp);
+    awesome->initFontAwesome();
+
+    QQmlApplicationEngine engine;
+    engine.addImageProvider("fa", new QtAwesomeQuickImageProvider(awesome));
+    engine.load(QUrl(QStringLiteral("qrc:/main.qml")));
+
+    int result = app.exec();
+    delete awesome;
+    return result;
+}
+

QtAwesomeSampleQml/main.qml

@@ -0,0 +1,32 @@
+import QtQuick 6.0
+import QtQuick.Controls 6.0
+import QtQuick.Layouts 6.0
+
+ApplicationWindow
+{
+    visible: true
+    width: 640
+    height: 480
+    title: qsTr("QtAwesome Sample")
+
+    RowLayout {
+        spacing: 10
+
+        Image {
+            width: 64
+            height: 64
+            source: "image://fa/regular/thumbs-up"
+        }
+        Image {
+            width: 64
+            height: 64
+            source: mouseArea.containsMouse ? "image://fa/solid/user-tie?color=FF00AA" : "image://fa/solid/user?color=22FF44"
+            MouseArea {
+                id: mouseArea
+                anchors.fill: parent
+                hoverEnabled: true
+            }
+        }
+    }
+}
+

QtAwesomeSampleQml/main.qrc

@@ -0,0 +1,5 @@
+<RCC>
+    <qresource prefix="/">
+        <file>main.qml</file>
+    </qresource>
+</RCC>

README.md

@@ -82,6 +82,9 @@ awesome->initFontAwesome();     // This line is important as it loads the font a
 - 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.
@@ -247,6 +250,38 @@ So the list of items used is:
 - 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.