File indexing completed on 2024-03-24 15:25:56

0001 /*
0002     This file is part of the KDE project
0003     SPDX-FileCopyrightText: 2013 Martin Gräßlin <mgraesslin@kde.org>
0004 
0005     SPDX-License-Identifier: LGPL-2.0-or-later
0006 */
0007 
0008 #ifndef KCOLORSCHEMEMANAGER_H
0009 #define KCOLORSCHEMEMANAGER_H
0010 
0011 #include <kconfigwidgets_export.h>
0012 
0013 #include <QObject>
0014 #include <memory>
0015 
0016 class QAbstractItemModel;
0017 class QModelIndex;
0018 class QIcon;
0019 
0020 class KActionMenu;
0021 class KColorSchemeManagerPrivate;
0022 
0023 /**
0024  * @class KColorSchemeManager kcolorschememanager.h KColorSchemeManager
0025  *
0026  * A small helper to get access to all available color schemes and activating a scheme in the
0027  * QApplication. This is useful for applications which want to provide a selection of custom color
0028  * schemes to their user. For example it is very common for photo and painting applications to use
0029  * a dark color scheme even if the default is a light scheme. Since version 5.67 it also allows
0030  * going back to following the system color scheme.
0031  *
0032  * The KColorSchemeManager provides access to a QAbstractItemModel which holds all the available
0033  * schemes. A possible usage looks like the following:
0034  *
0035  * @code
0036  * KColorSchemeManager *schemes = new KColorSchemeManager(this);
0037  * QListView *view = new QListView(this);
0038  * view->setModel(schemes->model());
0039  * connect(view, &QListView::activated, schemes, &KColorSchemeManager::activateScheme);
0040  * @endcode
0041  *
0042  * In addition the KColorSchemeManager also provides the possibility to create a KActionMenu populated
0043  * with all the available color schemes in an action group. If one of the actions is selected the
0044  * scheme is applied instantly:
0045  *
0046  * @code
0047  * QToolButton *button = new QToolButton();
0048  * KColorSchemeManager *schemes = new KColorSchemeManager(this);
0049  * KActionMenu *menu = schemes->createSchemeSelectionMenu(QStringLiteral("Oxygen"), button);
0050  * button->setMenu(menu->menu());
0051  * @endcode
0052  *
0053  * @since 5.0
0054  */
0055 class KCONFIGWIDGETS_EXPORT KColorSchemeManager : public QObject
0056 {
0057     Q_OBJECT
0058 public:
0059     explicit KColorSchemeManager(QObject *parent = nullptr);
0060     ~KColorSchemeManager() override;
0061 
0062     /**
0063      * A QAbstractItemModel of all available color schemes.
0064      *
0065      * The model provides the name of the scheme in Qt::DisplayRole, a preview
0066      * in Qt::DelegateRole and the full path to the scheme file in Qt::UserRole. The system theme
0067      * has an empty Qt::UserRole.
0068      *
0069      * @return Model of all available color schemes.
0070      */
0071     QAbstractItemModel *model() const;
0072     /**
0073      * Returns the model index for the scheme with the given @p name. If no such
0074      * scheme exists an invalid index is returned. If you pass an empty
0075      * string the index that is equivalent to going back to following the system scheme is returned
0076      * for versions 5.67 and newer.
0077      * @see model
0078      */
0079     QModelIndex indexForScheme(const QString &name) const;
0080 
0081 #if KCONFIGWIDGETS_ENABLE_DEPRECATED_SINCE(5, 107)
0082     /**
0083      * Creates a KActionMenu populated with all the available color schemes.
0084      * All actions are in an action group and when one of the actions is triggered the scheme
0085      * referenced by this action is activated.
0086      *
0087      * The color scheme with the same name as @p selectedSchemeName will be checked. If none
0088      * of the available color schemes has the same name, the system theme entry will be checked.
0089      *
0090      * The KActionMenu will not be updated in case the installed color schemes change. It's the
0091      * task of the user of the KActionMenu to monitor for changes if required.
0092      *
0093      * @param icon The icon to use for the KActionMenu
0094      * @param text The text to use for the KActionMenu
0095      * @param selectedSchemeName The name of the color scheme to select
0096      * @param parent The parent of the KActionMenu
0097      * @return KActionMenu populated with all available color schemes.
0098      * @see activateScheme
0099      *
0100      * @deprecated since 5.107, use KColorSchemeMenu::createMenu and set the text and icon manually  and check an action of the returned menu
0101      */
0102     KCONFIGWIDGETS_DEPRECATED_VERSION(5, 107, "Use KColorSchemeMenu::createMenu")
0103     KActionMenu *createSchemeSelectionMenu(const QIcon &icon, const QString &text, const QString &selectedSchemeName, QObject *parent);
0104 
0105     /**
0106      * Overload for createSchemeSelectionMenu(const QIcon &icon, const QString &text, const QString &selectedSchemeName, QObject *parent).
0107      *
0108      * Since 5.67 sets the icon to theme id "preferences-desktop-color", before set a null icon.
0109      *
0110      * @deprecated since 5.107, use KColorSchemeMenu::createMenu and set the text and check an action manually
0111      */
0112     KCONFIGWIDGETS_DEPRECATED_VERSION(5, 107, "Use KColorSchemeMenu::createMenu")
0113     KActionMenu *createSchemeSelectionMenu(const QString &text, const QString &selectedSchemeName, QObject *parent);
0114     /**
0115      * Overload for createSchemeSelectionMenu(const QIcon &icon, const QString &text, const QString &selectedSchemeName, QObject *parent).
0116      *
0117      * Since 5.67 sets the icon to theme id "preferences-desktop-color" and the text to "Color Scheme", before set a null icon and an empty string.
0118      *
0119      * @deprecated since 5.107, use KColorSchemeMenu::createMenu and check an action manually
0120      */
0121     KCONFIGWIDGETS_DEPRECATED_VERSION(5, 107, "Use KColorSchemeMenu::createMenu")
0122     KActionMenu *createSchemeSelectionMenu(const QString &selectedSchemeName, QObject *parent);
0123     /**
0124      * Overload for createSchemeSelectionMenu(const QIcon &icon, const QString &text, const QString &selectedSchemeName, QObject *parent).
0125      *
0126      * Sets the icon to theme id "preferences-desktop-color" and the text to "Color Scheme".
0127      * Since 5.93 the selectedSchemeName is set to the value previously saved (if any).
0128      * Before that it was set to an empty string.
0129      * @since 5.67
0130      * @deprecated since 5.107, use KColorSchemeMenu::createMenu
0131      */
0132     KCONFIGWIDGETS_DEPRECATED_VERSION(5, 107, "Use KColorSchemeMenu::createMenu")
0133     KActionMenu *createSchemeSelectionMenu(QObject *parent);
0134 #endif
0135 
0136     /**
0137      * Saves the color scheme to config file. The scheme is saved by default whenever it's changed.
0138      * Use this method when autosaving is turned off, see setAutosaveChanges().
0139      *
0140      * @since 5.89
0141      */
0142     void saveSchemeToConfigFile(const QString &schemeName) const;
0143     /**
0144      * Sets color scheme autosaving. Default value is @c true.
0145      * If this is set to @c false, the scheme is not going to be remembered when the
0146      * application is restarted.
0147      *
0148      * @param autosaveChanges Enables/Disables autosaving of the color scheme.
0149      * @since 5.89
0150      */
0151     void setAutosaveChanges(bool autosaveChanges);
0152 
0153     /**
0154      * Returns the id of the currently active scheme or an empty string if the default
0155      * scheme is active.
0156      *
0157      * @since 5.107
0158      */
0159     QString activeSchemeId() const;
0160 
0161 public Q_SLOTS:
0162     /**
0163      * @brief Activates the KColorScheme identified by the provided @p index.
0164      *
0165      * Installs the KColorScheme as the QApplication's QPalette.
0166      *
0167      * @param index The index for the KColorScheme to activate.
0168      * The index must reference the QAbstractItemModel provided by @link model @endlink. Since
0169      * version 5.67 passing an invalid index activates the system scheme.
0170      * @see model()
0171      */
0172     void activateScheme(const QModelIndex &index);
0173 
0174 private:
0175     std::unique_ptr<KColorSchemeManagerPrivate> const d;
0176 };
0177 
0178 #endif