File indexing completed on 2024-05-19 07:43:15

0001 // SPDX-License-Identifier: LGPL-2.1-only OR LGPL-3.0-only OR LicenseRef-KDE-Accepted-LGPL
0002 // SPDX-FileCopyrightText: 2022-2023 Harald Sitter <sitter@kde.org>
0003 
0004 #ifndef KCOUNTRYFLAGEMOJIICONENGINE_H
0005 #define KCOUNTRYFLAGEMOJIICONENGINE_H
0006 
0007 #include <QIconEngine>
0008 
0009 #include <kguiaddons_export.h>
0010 
0011 class KCountryFlagEmojiIconEnginePrivate;
0012 
0013 /**
0014  * @brief Provides emoji flags as icons
0015  * This is a special icon engine that internally paints flags using emoji fonts.
0016  * It provides access to country and region flags from the system emoji font.
0017  * ```
0018  *   auto l = new QLabel;
0019  *   l->setMinimumSize(512, 512);
0020  *   l->setPixmap(QIcon(new KCountryFlagEmojiIconEngine("AT")).pixmap(512, 512));
0021  * ```
0022  * @since 6.0
0023  */
0024 class KGUIADDONS_EXPORT KCountryFlagEmojiIconEngine : public QIconEngine
0025 {
0026 public:
0027     /**
0028      * @brief Construct a new KCountryFlagEmojiIconEngine object
0029      * Please note that regional flag support can be spotty in emoji fonts.
0030      * @param regionOrCountry either a ISO 3166-1 alpha-2 country code or a ISO 3166-2 region code (e.g. AT for Austria or GB-SCT for Scotland)
0031      */
0032     explicit KCountryFlagEmojiIconEngine(const QString &regionOrCountry);
0033     ~KCountryFlagEmojiIconEngine() override;
0034     Q_DISABLE_COPY_MOVE(KCountryFlagEmojiIconEngine)
0035 
0036     QIconEngine *clone() const override;
0037     QString key() const override;
0038     void paint(QPainter *painter, const QRect &rect, QIcon::Mode mode, QIcon::State state) override;
0039     QPixmap pixmap(const QSize &size, QIcon::Mode mode, QIcon::State state) override;
0040     QPixmap scaledPixmap(const QSize &size, QIcon::Mode mode, QIcon::State state, qreal scale) override;
0041 
0042     /**
0043      * @brief Check whether the internal emoji unicode sequence is null
0044      * This does not necessarily mean that the pixmap output will be a valid flag - that entirely depends on the system's precise font configuration.
0045      * @return true when the construction of the emoji string failed
0046      * @return false when the construction of the emoji string succeeded
0047      */
0048     bool isNull() override;
0049 
0050     /**
0051      * @brief Set the Global Default Font object
0052      * This is primarily useful for platform themes that wish to force a specific font being used. By default the "emoji" font family will be used.
0053      * Forcing a specific font and making sure it is available as runtime requirement is the most reliable way to ensure that flag support is working
0054      * regardless of system configuration.
0055      * @param font the default font to use
0056      */
0057     static void setGlobalDefaultFont(const QFont &font);
0058 
0059 private:
0060     std::unique_ptr<KCountryFlagEmojiIconEnginePrivate> const d;
0061 };
0062 
0063 #endif