Allow built-in translations and icons

- Allow to built-in qm files for translations using the Qt resource system - Allow to built-in required icons from specified icon themes using the Qt resource system - Provide bash script to determine required icons
2016-07-16 23:12:02 +02:00 · 2016-07-16 23:12:02 +02:00 · 5a0eba3726
parent c66d1513f9
commit 5a0eba3726
10 changed files with 253 additions and 65 deletions
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@ -82,6 +82,20 @@ set(DOC_FILES
    README.md
 )

+set(REQUIRED_ICONS
+    window-close
+    document-open
+    document-open-recent
+    dialog-ok
+    dialog-cancel
+    edit-clear
+    dialog-ok-apply
+    system-file-manager
+    system-run
+    go-next
+    qtcreator
+)
+
 # meta data
 set(META_PROJECT_NAME qtutilities)
 set(META_PROJECT_VARNAME QT_UTILITIES)
@ -89,9 +103,9 @@ set(META_APP_NAME "Qt Utilities")
 set(META_APP_AUTHOR "Martchus")
 set(META_APP_URL "https://github.com/${META_APP_AUTHOR}/${META_PROJECT_NAME}")
 set(META_APP_DESCRIPTION "Common Qt related C++ classes and routines used by my applications such as dialogs, widgets and models.")
-set(META_VERSION_MAJOR 4)
+set(META_VERSION_MAJOR 5)
 set(META_VERSION_MINOR 0)
-set(META_VERSION_PATCH 1)
+set(META_VERSION_PATCH 0)
 set(META_APP_VERSION ${META_VERSION_MAJOR}.${META_VERSION_MINOR}.${META_VERSION_PATCH})

 # required to include CMake modules from own project directory
--- a/cmake/modules/JsProviderConfig.cmake
+++ b/cmake/modules/JsProviderConfig.cmake
@ -6,12 +6,14 @@ if(${JS_PROVIDER} STREQUAL "auto")
    if(Qt5Script_FOUND)
        set(JS_PROVIDER Qt5::Script)
        set(JS_DEFINITION "-D${META_PROJECT_VARNAME_UPPER}_USE_SCRIPT")
+        list(APPEND ADDITIONAL_QT_REPOS "script")
        message(STATUS "No JavaScript provider explicitly specified, defaulting to Qt Script.")
    else()
        find_package(Qt5Qml)
        if(Qt5Qml_FOUND)
            set(JS_PROVIDER Qt5::Qml)
            set(JS_DEFINITION "-D${META_PROJECT_VARNAME_UPPER}_USE_JSENGINE")
+            list(APPEND ADDITIONAL_QT_REPOS "declarative")
            message(STATUS "No JavaScript provider explicitly specified, defaulting to Qt QML.")
        else()
            set(JS_PROVIDER "")
@ -24,11 +26,13 @@ else()
        find_package(Qt5Script REQUIRED)
        set(JS_PROVIDER Qt5::Script)
        set(JS_DEFINITION "-D${META_PROJECT_VARNAME_UPPER}_USE_SCRIPT")
+        list(APPEND ADDITIONAL_QT_REPOS "script")
        message(STATUS "Using Qt Script as JavaScript provider.")
    elseif(${JS_PROVIDER} STREQUAL "qml")
        find_package(Qt5Qml REQUIRED)
        set(JS_PROVIDER Qt5::Qml)
        set(JS_DEFINITION "-D${META_PROJECT_VARNAME_UPPER}_USE_JSENGINE")
+        list(APPEND ADDITIONAL_QT_REPOS "declarative")
        message(STATUS "Using Qt QML as JavaScript provider.")
    elseif(${JS_PROVIDER} STREQUAL "none")
        set(JS_PROVIDER "")
--- a/cmake/modules/QtConfig.cmake
+++ b/cmake/modules/QtConfig.cmake
@ -5,8 +5,14 @@
 # add the Core module as it is always required
 # also add additional Qt/KF modules which must have been specified before if required
 # the Gui/Widgets/Quick modules should be added by including QtGuiAppConfig
+set(QT_REPOS base ${ADDITIONAL_QT_REPOS})
 set(QT_MODULES Core ${ADDITIONAL_QT_MODULES})
 set(KF_MODULES ${ADDITIONAL_KF_MODULES})
+list(REMOVE_DUPLICATES QT_REPOS)
+list(REMOVE_DUPLICATES QT_MODULES)
+if(KF_MODULES)
+    list(REMOVE_DUPLICATES KF_MODULES)
+endif()

 # enable lrelease and add install target for localization
 if(TS_FILES)
@ -37,6 +43,38 @@ if(TS_FILES)
            COMMAND "${CMAKE_COMMAND}" -DCMAKE_INSTALL_COMPONENT=localization -P "${CMAKE_BINARY_DIR}/cmake_install.cmake"
        )
    endif()
+
+    # built-in translations
+    option(BUILTIN_TRANSLATIONS "enables/disables built-in translations" OFF)
+    if(BUILTIN_TRANSLATIONS)
+        # find Qt translations
+        set(QT_TRANSLATION_SEARCH_PATHS)
+        if(CMAKE_FIND_ROOT_PATH)
+            list(APPEND QT_TRANSLATION_SEARCH_PATHS "${CMAKE_FIND_ROOT_PATH}/share/qt/translations")
+        endif()
+        list(APPEND QT_TRANSLATION_SEARCH_PATHS "${CMAKE_INSTALL_PREFIX}/share/qt/translations")
+        list(APPEND QT_TRANSLATION_SEARCH_PATHS "/usr/share/qt/translations")
+        foreach(QT_TRANSLATION_PATH ${QT_TRANSLATION_SEARCH_PATHS})
+            if(IS_DIRECTORY "${QT_TRANSLATION_PATH}")
+                foreach(QT_REPO ${QT_REPOS})
+                    file(GLOB QT_QM_FILES "${QT_TRANSLATION_PATH}/qt${QT_REPO}_*.qm")
+                    file(COPY ${QT_QM_FILES} DESTINATION "${CMAKE_CURRENT_BINARY_DIR}")
+                    list(APPEND QM_FILES ${QT_QM_FILES})
+                endforeach()
+                break()
+            endif()
+        endforeach()
+
+        # write a qrc file for the qm files and add it to the resource files
+        set(TRANSLATIONS_QRC_FILE "${CMAKE_CURRENT_BINARY_DIR}/translations.qrc")
+        file(WRITE "${TRANSLATIONS_QRC_FILE}" "<RCC><qresource prefix=\"/translations\">")
+        foreach(QM_FILE ${QM_FILES})
+            get_filename_component(QM_FILE_NAME "${QM_FILE}" NAME)
+            file(APPEND "${TRANSLATIONS_QRC_FILE}" "<file>${QM_FILE_NAME}</file>")
+        endforeach()
+        file(APPEND "${TRANSLATIONS_QRC_FILE}" "</qresource></RCC>")
+        list(APPEND RES_FILES "${TRANSLATIONS_QRC_FILE}")
+    endif()
 endif()

 # check whether D-Bus interfaces need to be processed
@ -62,13 +100,65 @@ if(DBUS_FILES)
    qt5_add_dbus_interfaces(SRC_FILES ${DBUS_FILES})
 endif()

-# built-in translations
-option(BUILTIN_TRANSLATIONS "enables/disables built-in translations" OFF)
-# TODO
-
-# built-in icons
-option(BUILTIN_ICONS "enables/disables built-in icons" OFF)
-# TODO
+# add icons to be built-in
+if(REQUIRED_ICONS)
+    set(BUILTIN_ICON_THEMES "" CACHE STRING "specifies icon themes to be built-in")
+    if(BUILTIN_ICON_THEMES)
+        set(ICON_THEME_FILES)
+        set(ICON_SEARCH_PATHS)
+        if(CMAKE_FIND_ROOT_PATH)
+            list(APPEND ICON_SEARCH_PATHS "${CMAKE_FIND_ROOT_PATH}/share/icons")
+        endif()
+        list(APPEND ICON_SEARCH_PATHS "${CMAKE_INSTALL_PREFIX}/share/icons")
+        list(APPEND ICON_SEARCH_PATHS "/usr/share/icons")
+        set(BUILDIN_ICONS_DIR "${CMAKE_CURRENT_BINARY_DIR}/icons")
+        set(DEFAULT_THEME_INDEX_FILE "${BUILDIN_ICONS_DIR}/default/index.theme")
+        file(REMOVE_RECURSE "${BUILDIN_ICONS_DIR}")
+        file(MAKE_DIRECTORY "${BUILDIN_ICONS_DIR}")
+        foreach(ICON_THEME ${BUILTIN_ICON_THEMES})
+            foreach(ICON_SEARCH_PATH ${ICON_SEARCH_PATHS})
+                set(ICON_THEME_PATH "${ICON_SEARCH_PATH}/${ICON_THEME}")
+                if(IS_DIRECTORY "${ICON_THEME_PATH}")
+                    file(GLOB GLOBBED_ICON_THEME_INDEX_FILES LIST_DIRECTORIES false "${ICON_THEME_PATH}/index.theme" "${ICON_THEME_PATH}/icon-theme.cache")
+                    if(NOT EXISTS "${DEFAULT_THEME_INDEX_FILE}")
+                        file(MAKE_DIRECTORY "${BUILDIN_ICONS_DIR}/default")
+                        file(WRITE "${DEFAULT_THEME_INDEX_FILE}" "[Icon Theme]\nInherits=${ICON_THEME}")
+                        list(APPEND ICON_THEME_FILES "<file>default/index.theme</file>")
+                    endif()
+                    set(GLOB_PATTERNS)
+                    foreach(REQUIRED_ICON ${REQUIRED_ICONS})
+                        list(APPEND GLOB_PATTERNS
+                            "${ICON_THEME_PATH}/${REQUIRED_ICON}"
+                            "${ICON_THEME_PATH}/${REQUIRED_ICON}.*"
+                            "${ICON_THEME_PATH}/*/${REQUIRED_ICON}"
+                            "${ICON_THEME_PATH}/*/${REQUIRED_ICON}.*"
+                        )
+                    endforeach()
+                    file(GLOB_RECURSE GLOBBED_ICON_THEME_FILES LIST_DIRECTORIES false ${GLOB_PATTERNS})
+                    foreach(ICON_THEME_FILE ${GLOBBED_ICON_THEME_INDEX_FILES} ${GLOBBED_ICON_THEME_FILES})
+                        if(IS_SYMLINK "${ICON_THEME_FILE}")
+                            string(REGEX REPLACE "^${ICON_SEARCH_PATH}/" "" ICON_THEME_FILE_RELATIVE_PATH "${ICON_THEME_FILE}")
+                            set(ICON_THEME_FILE_ALIAS " alias=\"${ICON_THEME_FILE_RELATIVE_PATH}\"")
+                            get_filename_component(ICON_THEME_FILE "${ICON_THEME_FILE}" REALPATH)
+                        else()
+                            set(ICON_THEME_FILE_ALIAS "")
+                        endif()
+                        string(REGEX REPLACE "^${ICON_SEARCH_PATH}/" "" ICON_THEME_FILE_RELATIVE_PATH "${ICON_THEME_FILE}")
+                        get_filename_component(ICON_THEME_FILE_DIR "${ICON_THEME_FILE_RELATIVE_PATH}" DIRECTORY)
+                        file(MAKE_DIRECTORY "${BUILDIN_ICONS_DIR}/${ICON_THEME_FILE_DIR}")
+                        file(COPY "${ICON_THEME_FILE}" DESTINATION "${BUILDIN_ICONS_DIR}/${ICON_THEME_FILE_DIR}")
+                        list(APPEND ICON_THEME_FILES "<file${ICON_THEME_FILE_ALIAS}>${ICON_THEME_FILE_RELATIVE_PATH}</file>")
+                    endforeach()
+                    break()
+                endif()
+            endforeach()
+        endforeach()
+        set(BUILTIN_ICON_THEMES_QRC_FILE "${CMAKE_CURRENT_BINARY_DIR}/icons/builtinicons.qrc")
+        string(CONCAT BUILTIN_ICON_THEMES_QRC_FILE_CONTENT "<RCC><qresource prefix=\"/icons\">" ${ICON_THEME_FILES} "</qresource></RCC>")
+        file(WRITE "${BUILTIN_ICON_THEMES_QRC_FILE}" "${BUILTIN_ICON_THEMES_QRC_FILE_CONTENT}")
+        list(APPEND RES_FILES "${BUILTIN_ICON_THEMES_QRC_FILE}")
+    endif()
+endif()

 # enable moc, uic and rcc
 set(CMAKE_AUTOMOC ON)
--- a/cmake/modules/QtGuiConfig.cmake
+++ b/cmake/modules/QtGuiConfig.cmake
@ -29,6 +29,7 @@ if(QUICK_GUI)
    list(APPEND ADDITIONAL_HEADER_FILES ${QML_HEADER_FILES})
    if(QML_FILES)
        list(APPEND ADDITIONAL_QT_MODULES Quick)
+        list(APPEND ADDITIONAL_QT_REPOS "declarative")
        message(STATUS "Building with Qt Quick GUI.")
    else()
        message(STATUS "Qt Quick GUI is not available.")
--- a/cmake/modules/WebViewProviderConfig.cmake
+++ b/cmake/modules/WebViewProviderConfig.cmake
@ -12,6 +12,7 @@ if(${WEBVIEW_PROVIDER} STREQUAL "auto")
        if(Qt5WebEngineWidgets_FOUND)
            set(WEBVIEW_PROVIDER Qt5::WebEngineWidgets)
            set(WEBVIEW_DEFINITION "-D${META_PROJECT_VARNAME_UPPER}_USE_WEBENGINE")
+            list(APPEND ADDITIONAL_QT_REPOS "webengine")
            message(STATUS "No web view provider explicitly specified, defaulting to Qt WebEngine.")
        else()
            set(WEBVIEW_PROVIDER "")
@ -29,6 +30,7 @@ else()
        find_package(Qt5WebEngineWidgets REQUIRED)
        set(WEBVIEW_PROVIDER Qt5::WebEngineWidgets)
        set(WEBVIEW_DEFINITION "-D${META_PROJECT_VARNAME_UPPER}_USE_WEBENGINE")
+        list(APPEND ADDITIONAL_QT_REPOS "webengine")
        message(STATUS "Using Qt WebEngine as web view provider.")
    elseif(${WEBVIEW_PROVIDER} STREQUAL "none")
        set(WEBVIEW_DEFINITION "-D${META_PROJECT_VARNAME_UPPER}_NO_WEBVIEW")
--- a/paletteeditor/colorbutton.cpp
+++ b/paletteeditor/colorbutton.cpp
@ -9,6 +9,10 @@

 namespace Widgets {

+/*!
+ * \cond
+ */
+
 class ColorButtonPrivate
 {
    ColorButton *q_ptr;
@ -75,7 +79,9 @@ QPixmap ColorButtonPrivate::generatePixmap() const
    return pix;
 }

-///////////////
+/*!
+ * \endcond
+ */

 ColorButton::ColorButton(QWidget *parent)
    : QToolButton(parent), d_ptr(new ColorButtonPrivate)
--- a/resources/qtconfigarguments.cpp
+++ b/resources/qtconfigarguments.cpp
@ -89,9 +89,6 @@ void QtConfigArguments::applySettings() const
 # endif
 #endif
    }
-#ifdef Q_OS_WIN32
-    bool searchPathsPresent = false;
-#endif
    if(m_iconThemeArg.isPresent()) {
        auto i = m_iconThemeArg.values().cbegin(), end = m_iconThemeArg.values().end();
        if(i != end) {
@ -101,10 +98,13 @@ void QtConfigArguments::applySettings() const
                for(; i != end; ++i) {
                    searchPaths << QString::fromLocal8Bit(*i);
                }
-                QIcon::setThemeSearchPaths(searchPaths);
 #ifdef Q_OS_WIN32
-                searchPathsPresent = !searchPaths.isEmpty();
+                if(searchPaths.isEmpty()) {
+                    searchPaths << QStringLiteral("../share/icons");
+                }
 #endif
+                searchPaths << QStringLiteral(":/icons");
+                QIcon::setThemeSearchPaths(searchPaths);
            }
            QIcon::setThemeName(QString::fromLocal8Bit(*i));
        }
@ -112,10 +112,9 @@ void QtConfigArguments::applySettings() const
        if(qEnvironmentVariableIsSet("ICON_THEME_SEARCH_PATH")) {
            QString path;
            path.append(qgetenv("ICON_THEME_SEARCH_PATH"));
-            QIcon::setThemeSearchPaths(QStringList() << path);
-#ifdef Q_OS_WIN32
-            searchPathsPresent = true;
-#endif
+            QIcon::setThemeSearchPaths(QStringList() << path << QStringLiteral(":/icons"));
+        } else {
+            QIcon::setThemeSearchPaths(QStringList() << QStringLiteral("../share/icons") << QStringLiteral(":/icons"));
        }
        if(qEnvironmentVariableIsSet("ICON_THEME")) {
            QString themeName;
@ -125,9 +124,6 @@ void QtConfigArguments::applySettings() const
    }
 #ifdef Q_OS_WIN32
    // default configuration under Windows
-    if(!searchPathsPresent) {
-        QIcon::setThemeSearchPaths(QIcon::themeSearchPaths() << QStringLiteral("../share/icons"));
-    }
    if(QIcon::themeName().isEmpty()) {
        QIcon::setThemeName(QStringLiteral("default"));
    }
--- a/resources/resources.cpp
+++ b/resources/resources.cpp
@ -1,5 +1,7 @@
 #include "./resources.h"

+#include "resources/config.h"
+
 #include <QString>
 #include <QLocale>
 #include <QTranslator>
@ -25,9 +27,18 @@

 using namespace std;

+/*!
+ * \cond
+ */
 void qInitResources_qtutilsicons();
 void qCleanupResources_qtutilsicons();
+/*!
+ * \endcond
+ */

+/*!
+ * \brief Functions for using the resources provided by this library.
+ */
 namespace QtUtilitiesResources {

 /*!
@ -48,48 +59,68 @@ void cleanup()

 }

+/*!
+ * \brief Convenience functions to load translations for Qt and the application.
+ */
 namespace TranslationFiles {

-bool hasEnglishTranslator = false;
-
 /*!
 * \brief Loads and installs the appropriate Qt translation file for the current locale.
+ * \remarks
+ *  - Translation files have to be placed in one of the following locations:
+ *    * QLibraryInfo::location(QLibraryInfo::TranslationsPath) (used in UNIX)
+ *    * ../share/qt/translations (used in Windows)
+ *  - Translation files can also be built-in using by setting the CMake variable BUILTIN_TRANSLATIONS.
 */
 void loadQtTranslationFile()
 {
-    QLocale locale;
-    if(locale.language() != QLocale::English) {
-        QTranslator *qtTranslator = new QTranslator;
-        if(qtTranslator->load(QStringLiteral("qt_%1").arg(locale.name()),
-                              QLibraryInfo::location(QLibraryInfo::TranslationsPath))) {
-            QCoreApplication::installTranslator(qtTranslator);
-        } else if(qtTranslator->load(QStringLiteral("qt_%1").arg(locale.name()), QStringLiteral("../share/qt/translations"))) {
-            // used in Windows
-            QCoreApplication::installTranslator(qtTranslator);
-        } else {
-            delete qtTranslator;
-            cout << "Unable to load Qt translation file for the language " << locale.name().toStdString() << "." << endl;
-        }
+    // load translation files for current locale
+    loadQtTranslationFile(QLocale().name());
+}
+
+/*!
+ * \brief Loads and installs the appropriate Qt translation file for the specified locale.
+ * \param localeName Specifies the name of the locale.
+ * \remarks
+ *  - Translation files have to be placed in one of the following locations:
+ *    * QLibraryInfo::location(QLibraryInfo::TranslationsPath) (used in UNIX)
+ *    * ../share/qt/translations (used in Windows)
+ *  - Translation files can also be built-in using by setting the CMake variable BUILTIN_TRANSLATIONS.
+ */
+void loadQtTranslationFile(const QString &localeName)
+{
+    QTranslator *qtTranslator = new QTranslator;
+    const QString fileName(QStringLiteral("qtbase_%1").arg(localeName));
+    if(qtTranslator->load(fileName,
+                          QLibraryInfo::location(QLibraryInfo::TranslationsPath))) {
+        QCoreApplication::installTranslator(qtTranslator);
+    } else if(qtTranslator->load(fileName, QStringLiteral("../share/qt/translations"))) {
+        // used in Windows
+        QCoreApplication::installTranslator(qtTranslator);
+    } else if(qtTranslator->load(fileName, QStringLiteral(":/translations"))) {
+        QCoreApplication::installTranslator(qtTranslator);
+    } else {
+        delete qtTranslator;
+        cerr << "Unable to load Qt translation file for the language " << localeName.toLocal8Bit().data() << "." << endl;
    }
 }

 /*!
 * \brief Loads and installs the appropriate application translation file for the current locale.
 * \param applicationName Specifies the name of the application.
- * \remarks Translation files have to be placed in one of the following
- *          locations:
- *           - ./translations
- *           - /usr/share/$application/translations (used in UNIX)
- *           - ../share/$application/translations (used in Windows)
- *           - ./projects/%1/translations (used during developement with subdirs project)
- *          Translation files must be named using the following scheme:
- *           - $application_$language.qm
+ * \remarks
+ *  - Translation files have to be placed in one of the following locations:
+ *    * ./translations
+ *    * /usr/share/$application/translations (used in UNIX)
+ *    * ../share/$application/translations (used in Windows)
+ *  - Translation files must be named using the following scheme:
+ *    * $application_$language.qm
+ *  - Translation files can also be built-in using by setting the CMake variable BUILTIN_TRANSLATIONS.
 */
 void loadApplicationTranslationFile(const QString &applicationName)
 {
    // load English translation files as fallback
    loadApplicationTranslationFile(applicationName, QStringLiteral("en_US"));
-    hasEnglishTranslator = true;
    // load translation files for current locale
    loadApplicationTranslationFile(applicationName, QLocale().name());
 }
@ -98,46 +129,46 @@ void loadApplicationTranslationFile(const QString &applicationName)
 * \brief Loads and installs the appropriate application translation file for the specified locale.
 * \param applicationName Specifies the name of the application.
 * \param localeName Specifies the name of the locale.
- * \remarks Translation files have to be placed in one of the following
- *          locations:
- *           - ./translations
- *           - /usr/share/$application/translations (used in UNIX)
- *           - ../share/$application/translations (used in Windows)
- *           - ./projects/%1/translations (used during developement with subdirs project)
- *          Translation files must be named using the following scheme:
- *           - $application_$language.qm
+ * \remarks
+ *  - Translation files have to be placed in one of the following locations:
+ *    * ./translations
+ *    * /usr/share/$application/translations (used in UNIX)
+ *    * ../share/$application/translations (used in Windows)
+ *  - Translation files must be named using the following scheme:
+ *    * $application_$language.qm
+ *  - Translation files can also be built-in using by setting the CMake variable BUILTIN_TRANSLATIONS.
 */
 void loadApplicationTranslationFile(const QString &applicationName, const QString &localeName)
 {
    QTranslator *appTranslator = new QTranslator;
-    QString fileName = QStringLiteral("%1_%2").arg(applicationName, localeName);
+    const QString fileName(QStringLiteral("%1_%2").arg(applicationName, localeName));
    if(appTranslator->load(fileName, QStringLiteral("."))) {
        QCoreApplication::installTranslator(appTranslator);
    } else if(appTranslator->load(fileName, QStringLiteral("./translations"))) {
        QCoreApplication::installTranslator(appTranslator);
-    } else if(appTranslator->load(fileName, QStringLiteral("/usr/share/%1/translations").arg(applicationName))) {
+    } else if(appTranslator->load(fileName, QStringLiteral(APP_INSTALL_PREFIX "/share/%1/translations").arg(applicationName))) {
        QCoreApplication::installTranslator(appTranslator);
    } else if(appTranslator->load(fileName, QStringLiteral("../share/%1/translations").arg(applicationName))) {
        QCoreApplication::installTranslator(appTranslator);
+    } else if(appTranslator->load(fileName, QStringLiteral(":/translations"))) {
+        QCoreApplication::installTranslator(appTranslator);
    } else {
        delete appTranslator;
-        if(localeName != QStringLiteral("en_US")) {
-            cout << "Unable to load application translation file for the language \"" << localeName.toStdString() << "\", falling back to language \"en_US\"." << endl;
-            if(!hasEnglishTranslator) {
-                loadApplicationTranslationFile(applicationName, QStringLiteral("en_US"));
-                hasEnglishTranslator = true;
-            }
-        } else {
-            cout << "Unable to load application translation file for the language \"" << localeName.toStdString() << "\"." << endl;
-        }
+        cerr << "Unable to load application translation file for the language \"" << localeName.toLocal8Bit().data() << "\"." << endl;
    }
 }

 }

+/*!
+ * \brief Convenience functions to check whether a QCoreApplication/QGuiApplication/QApplication singleton has been instantiated yet.
+ */
 namespace ApplicationInstances {

 #if defined(GUI_QTWIDGETS)
+/*!
+ * \brief Returns whether a QApplication has been instantiated yet.
+ */
 bool hasWidgetsApp()
 {
    return qobject_cast<QApplication *>(QCoreApplication::instance()) != nullptr;
@ -145,12 +176,18 @@ bool hasWidgetsApp()
 #endif

 #if defined(GUI_QTWIDGETS) || defined(GUI_QTQUICK)
+/*!
+ * \brief Returns whether a QGuiApplication has been instantiated yet.
+ */
 bool hasGuiApp()
 {
    return qobject_cast<QGuiApplication *>(QCoreApplication::instance()) != nullptr;
 }
 #endif

+/*!
+ * \brief Returns whether a QCoreApplication has been instantiated yet.
+ */
 bool hasCoreApp()
 {
    return qobject_cast<QCoreApplication *>(QCoreApplication::instance()) != nullptr;
@ -158,8 +195,15 @@ bool hasCoreApp()

 }

+/*!
+ * \brief Provides convenience functions for handling config files.
+ */
 namespace ConfigFile {

+/*!
+ * \brief Locates the config file with the specified \a fileName for the application with the specified \a applicationName.
+ * \remarks If \a settings is not nullptr, the path provided by that object is also considered.
+ */
 QString locateConfigFile(const QString &applicationName, const QString &fileName, const QSettings *settings)
 {
    // check whether the file is in the current working directory
--- a/resources/resources.h
+++ b/resources/resources.h
@ -9,12 +9,18 @@ QT_FORWARD_DECLARE_CLASS(QString)
 QT_FORWARD_DECLARE_CLASS(QStringList)
 QT_FORWARD_DECLARE_CLASS(QSettings)

+/*!
+ * \brief Sets the application meta data in the QCoreApplication singleton.
+ */
 #define SET_QT_APPLICATION_INFO \
    QCoreApplication::setOrganizationName(QStringLiteral(APP_AUTHOR)); \
    QCoreApplication::setOrganizationDomain(QStringLiteral(APP_URL)); \
    QCoreApplication::setApplicationName(QStringLiteral(APP_NAME)); \
    QCoreApplication::setApplicationVersion(QStringLiteral(APP_VERSION))

+/*!
+ * \brief Loads translations for Qt and the application.
+ */
 #define LOAD_QT_TRANSLATIONS \
    TranslationFiles::loadQtTranslationFile(); \
    TranslationFiles::loadApplicationTranslationFile(QStringLiteral(PROJECT_NAME))
@ -29,6 +35,7 @@ LIB_EXPORT void cleanup();
 namespace TranslationFiles {

 LIB_EXPORT void loadQtTranslationFile();
+LIB_EXPORT void loadQtTranslationFile(const QString &localeName);
 LIB_EXPORT void loadApplicationTranslationFile(const QString &applicationName);
 LIB_EXPORT void loadApplicationTranslationFile(const QString &applicationName, const QString &localeName);

--- a/scripts/required_icons.sh
+++ b/scripts/required_icons.sh
@ -0,0 +1,24 @@
+#!/bin/bash
+declare -A icon_names
+
+# iterate over specified source directories
+for srcdir in "$@"; do
+    # find icons in *.ui files
+    for iconset in $(find "$srcdir" -iname '*.ui' -print0 | xargs -0 cat | grep -Po '<iconset\stheme=\".*?\"'); do
+        if [ "${iconset:0:7}" == 'theme="' ]; then
+            icon_names["${iconset: 7 : -1}"]=1
+        fi
+    done
+    # find icons in *.cpp files
+    for from_theme_call in $(find "$srcdir" -iname '*.cpp' -print0 | xargs -0 cat | grep -Po 'QIcon::fromTheme\(QStringLiteral\(\".*?\"\)'); do
+        icon_names["${from_theme_call: 33 : -2}"]=1
+    done
+done
+
+# print results
+echo 'set(REQUIRED_ICONS'
+for icon_name in "${!icon_names[@]}"
+do
+  echo "    ${icon_name}"
+done
+echo ')'