File indexing completed on 2024-03-03 04:02:37

0001 /* vi: ts=8 sts=4 sw=4
0002 
0003     This file is part of the KDE project, module kdecore.
0004     SPDX-FileCopyrightText: 2000 Geert Jansen <jansen@kde.org>
0005     SPDX-FileCopyrightText: 2000 Antonio Larrosa <larrosa@kde.org>
0006 
0007     SPDX-License-Identifier: LGPL-2.0-only
0008 */
0009 
0010 #ifndef KICONTHEME_H
0011 #define KICONTHEME_H
0012 
0013 #include <kiconthemes_export.h>
0014 
0015 #include <QList>
0016 #include <QString>
0017 #include <QStringList>
0018 
0019 #include <memory>
0020 
0021 #include "kiconloader.h"
0022 
0023 class QAction;
0024 
0025 /**
0026  * @internal
0027  * Class to use/access icon themes in KDE. This class is used by the
0028  * iconloader but can be used by others too.
0029  * @warning You should not use this class externally. This class is exported because
0030  *          the KCM needs it.
0031  * @see KIconLoader
0032  */
0033 class KICONTHEMES_EXPORT KIconTheme
0034 {
0035 public:
0036     /**
0037      * Load an icon theme by name.
0038      * @param name the name of the theme (e.g. "hicolor" or "keramik")
0039      * @param appName the name of the application. Can be null. This argument
0040      *        allows applications to have themed application icons.
0041      * @param basePathHint optional hint where to search the app themes.
0042      *        This is appended at the end of the search paths
0043      */
0044     explicit KIconTheme(const QString &name, const QString &appName = QString(), const QString &basePathHint = QString());
0045     ~KIconTheme();
0046 
0047     KIconTheme(const KIconTheme &) = delete;
0048     KIconTheme &operator=(const KIconTheme &) = delete;
0049 
0050     /**
0051      * The stylized name of the icon theme.
0052      * @return the (human-readable) name of the theme
0053      */
0054     QString name() const;
0055 
0056     /**
0057      * The internal name of the icon theme (same as the name argument passed
0058      *  to the constructor).
0059      * @return the internal name of the theme
0060      */
0061     QString internalName() const;
0062 
0063     /**
0064      * A description for the icon theme.
0065      * @return a human-readable description of the theme, QString()
0066      *         if there is none
0067      */
0068     QString description() const;
0069 
0070     /**
0071      * Return the name of the "example" icon. This can be used to
0072      * present the theme to the user.
0073      * @return the name of the example icon, QString() if there is none
0074      */
0075     QString example() const;
0076 
0077     /**
0078      * Return the name of the screenshot.
0079      * @return the name of the screenshot, QString() if there is none
0080      */
0081     QString screenshot() const;
0082 
0083     /**
0084      * Returns the toplevel theme directory.
0085      * @return the directory of the theme
0086      */
0087     QString dir() const;
0088 
0089     /**
0090      * The themes this icon theme falls back on.
0091      * @return a list of icon themes that are used as fall-backs
0092      */
0093     QStringList inherits() const;
0094 
0095     /**
0096      * The icon theme exists?
0097      * @return true if the icon theme is valid
0098      */
0099     bool isValid() const;
0100 
0101     /**
0102      * The icon theme should be hidden to the user?
0103      * @return true if the icon theme is hidden
0104      */
0105     bool isHidden() const;
0106 
0107     /**
0108      * The minimum display depth required for this theme. This can either
0109      * be 8 or 32.
0110      * @return the minimum bpp (8 or 32)
0111      */
0112     int depth() const;
0113 
0114     /**
0115      * The default size of this theme for a certain icon group.
0116      * @param group The icon group. See KIconLoader::Group.
0117      * @return The default size in pixels for the given icon group.
0118      */
0119     int defaultSize(KIconLoader::Group group) const;
0120 
0121     /**
0122      * Query available sizes for a group.
0123      * @param group The icon group. See KIconLoader::Group.
0124      * @return a list of available sizes for the given group
0125      */
0126     QList<int> querySizes(KIconLoader::Group group) const;
0127 
0128     /**
0129      * Query available icons for a size and context.
0130      * @param size the size of the icons
0131      * @param context the context of the icons
0132      * @return the list of icon names
0133      */
0134     QStringList queryIcons(int size, KIconLoader::Context context = KIconLoader::Any) const;
0135 
0136     /**
0137      * Query available icons for a context and preferred size.
0138      * @param size the size of the icons
0139      * @param context the context of the icons
0140      * @return the list of icon names
0141      */
0142     QStringList queryIconsByContext(int size, KIconLoader::Context context = KIconLoader::Any) const;
0143 
0144     /**
0145      * Lookup an icon in the theme.
0146      * @param name The name of the icon, with extension.
0147      * @param size The desired size of the icon.
0148      * @param match The matching mode. KIconLoader::MatchExact returns an icon
0149      * only if matches exactly. KIconLoader::MatchBest returns the best matching
0150      * icon.
0151      * @return An absolute path to the file of the icon if it's found, QString() otherwise.
0152      * @see KIconLoader::isValid will return true, and false otherwise.
0153      */
0154     QString iconPath(const QString &name, int size, KIconLoader::MatchType match) const;
0155 
0156     /**
0157      * Lookup an icon in the theme.
0158      * @param name The name of the icon, with extension.
0159      * @param size The desired size of the icon.
0160      * @param match The matching mode. KIconLoader::MatchExact returns an icon
0161      * only if matches exactly. KIconLoader::MatchBest returns the best matching
0162      * icon.
0163      * @param scale The scale of the icon group.
0164      * @return An absolute path to the file of the icon if it's found, QString() otherwise.
0165      * @see KIconLoader::isValid will return true, and false otherwise.
0166      * @since 5.48
0167      */
0168     // TODO KF6 merge iconPath() with and without "scale" and move that argument after "size"
0169     QString iconPath(const QString &name, int size, KIconLoader::MatchType match, qreal scale) const;
0170 
0171     /**
0172      * Lookup an icon in the theme.
0173      * @param name The name of the icon, without extension.
0174      * @param size The desired size of the icon.
0175      * @param match The matching mode. KIconLoader::MatchExact returns an icon
0176      * only if matches exactly. KIconLoader::MatchBest returns the best matching
0177      * icon.
0178      * @return An absolute path to the file of the icon if it's found, QString() otherwise.
0179      * @see KIconLoader::isValid will return true, and false otherwise.
0180      *
0181      * @since 5.22
0182      */
0183     QString iconPathByName(const QString &name, int size, KIconLoader::MatchType match) const;
0184 
0185     /**
0186      * Lookup an icon in the theme.
0187      * @param name The name of the icon, without extension.
0188      * @param size The desired size of the icon.
0189      * @param match The matching mode. KIconLoader::MatchExact returns an icon
0190      * only if matches exactly. KIconLoader::MatchBest returns the best matching
0191      * icon.
0192      * @param scale The scale of the icon group.
0193      * @return An absolute path to the file of the icon if it's found, QString() otherwise.
0194      * @see KIconLoader::isValid will return true, and false otherwise.
0195      *
0196      * @since 5.48
0197      */
0198     // TODO KF6 merge iconPathByName() with and without "scale" and move that argument after "size"
0199     QString iconPathByName(const QString &name, int size, KIconLoader::MatchType match, qreal scale) const;
0200 
0201     /**
0202      * Returns true if the theme has any icons for the given context.
0203      */
0204     bool hasContext(KIconLoader::Context context) const;
0205 
0206     /**
0207      * If true, this theme is made of SVG icons that will be colorized following the system
0208      * color scheme. This is necessary for monochrome themes that should look visible on both
0209      * light and dark color schemes.
0210      * @return true if the SVG will be colorized with a stylesheet.
0211      * @since 5.22
0212      */
0213     bool followsColorScheme() const;
0214 
0215     /**
0216      * List all icon themes installed on the system, global and local.
0217      * @return the list of all icon themes
0218      */
0219     static QStringList list();
0220 
0221     /**
0222      * Returns the current icon theme.
0223      * @return the name of the current theme
0224      */
0225     static QString current();
0226 
0227     /**
0228      * Force a current theme and disable automatic resolution of the current
0229      * theme in favor of the forced theme.
0230      *
0231      * To reset a forced theme, simply set an empty themeName.
0232      *
0233      * @param themeName name of the theme to force as current theme, or an
0234      *        empty string to unset theme forcing.
0235      *
0236      * @note This should only be used when a very precise expectation about
0237      *       the current theme is present. Most notably in unit tests
0238      *       this can be used to force a given theme.
0239      *
0240      * @warning A forced theme persists across reconfigure() calls!
0241      *
0242      * @see current
0243      * @since 5.23
0244      */
0245     static void forceThemeForTests(const QString &themeName);
0246 
0247     /**
0248      * Reconfigure the theme.
0249      */
0250     static void reconfigure();
0251 
0252     /**
0253      * Returns the default icon theme.
0254      * @return the name of the default theme name
0255      */
0256     static QString defaultThemeName();
0257 
0258 private:
0259     std::unique_ptr<class KIconThemePrivate> const d;
0260 };
0261 
0262 #endif