1/*
2 This file is part of the KDE project
3 SPDX-FileCopyrightText: 2013 Martin Gräßlin <mgraesslin@kde.org>
4
5 SPDX-License-Identifier: LGPL-2.0-or-later
6*/
7
8#ifndef KCOLORSCHEMEMANAGER_H
9#define KCOLORSCHEMEMANAGER_H
10
11#include <kcolorscheme_export.h>
12
13#include <QObject>
14#include <memory>
15
16class QAbstractItemModel;
17class QGuiApplication;
18class QModelIndex;
19class QIcon;
20
21class KActionMenu;
22class KColorSchemeManagerPrivate;
23
24/*!
25 * \class KColorSchemeManager
26 * \inmodule KColorScheme
27 *
28 * \brief A small helper to get access to all available color schemes and activating a scheme in the
29 * QApplication.
30 *
31 * This is useful for applications which want to provide a selection of custom color
32 * schemes to their user. For example it is very common for photo and painting applications to use
33 * a dark color scheme even if the default is a light scheme. Since version 5.67 it also allows
34 * going back to following the system color scheme.
35 *
36 * The model() member function provides access to the KColorSchemeModel that the KColorSchemeManager uses
37 * which holds all the available color schemes. A possible usage looks like the following:
38 *
39 * \code
40 * KColorSchemeManager *schemes = new KColorSchemeManager(this);
41 * QListView *view = new QListView(this);
42 * view->setModel(schemes->model());
43 * connect(view, &QListView::activated, schemes, &KColorSchemeManager::activateScheme);
44 * \endcode
45 *
46 * A convenience function that creates a KActionMenu that contains and activates color schemes exists
47 * in KColorSchemeMenu::createMenu
48 *
49 * By default KColorSchemeManager remembers the activated color scheme and restores it on the next
50 * start of the application. Use setAutosaveChanges() to change this behavior.
51 *
52 * \sa KColorSchemeMenu::createMenu, KColorSchemeModel
53 *
54 * \since 5.0
55 */
56class KCOLORSCHEME_EXPORT KColorSchemeManager : public QObject
57{
58 Q_OBJECT
59public:
60#if KCOLORSCHEME_ENABLE_DEPRECATED_SINCE(6, 6)
61 KCOLORSCHEME_DEPRECATED_VERSION(6, 6, "Use KColorSchemeManager::instance()")
62 explicit KColorSchemeManager(QObject *parent = nullptr);
63#endif
64
65 ~KColorSchemeManager() override;
66
67 /*!
68 * A QAbstractItemModel of all available color schemes.
69 *
70 * The model provides the name of the scheme in Qt::DisplayRole, a preview
71 * in Qt::DelegateRole and the full path to the scheme file in Qt::UserRole. The system theme
72 * has an empty Qt::UserRole.
73 *
74 * Returns Model of all available color schemes.
75 * \sa KColorSchemeModel
76 */
77 QAbstractItemModel *model() const;
78
79 /*!
80 * Returns the model index for the scheme with the given \param id. If no such
81 * scheme exists an invalid index is returned. If you pass an empty string the index
82 * returned is equivalent to going back to following the system scheme.
83 * \sa model
84 *
85 * \since 6.6
86 */
87 QModelIndex indexForSchemeId(const QString &id) const;
88
89 /*!
90 * Returns the model index for the scheme with the given \param name. If no such
91 * scheme exists an invalid index is returned. If you pass an empty
92 * string the index that is equivalent to going back to following the system scheme is returned
93 * for versions 5.67 and newer.
94 * \sa model
95 */
96 QModelIndex indexForScheme(const QString &name) const;
97
98 /*!
99 * Saves the color scheme to config file. The scheme is saved by default whenever it's changed.
100 * Use this method when autosaving is turned off, see setAutosaveChanges().
101 *
102 * \since 5.89
103 */
104 void saveSchemeToConfigFile(const QString &schemeName) const;
105 /*!
106 * Sets color scheme autosaving. Default value is \c true.
107 * If this is set to \c false, the scheme is not going to be remembered when the
108 * application is restarted.
109 *
110 * \param autosaveChanges Enables/Disables autosaving of the color scheme.
111 * \since 5.89
112 */
113 void setAutosaveChanges(bool autosaveChanges);
114
115 /*!
116 * Returns the id of the currently active scheme or an empty string if the default
117 * scheme is active.
118 *
119 * \since 5.107
120 */
121 QString activeSchemeId() const;
122
123 /*!
124 * Returns the name of the currently active scheme or an empty string if the default
125 * scheme is active.
126 *
127 * \since 6.6
128 */
129 QString activeSchemeName() const;
130
131 /*!
132 * Returns the manager for the current application instance.
133 * If no instance is existing, it will be constructed.
134 * Must be called after construction of the gui application instance.
135 *
136 * Returns color scheme manager for the current application instance
137 *
138 * \since 6.6
139 */
140 static KColorSchemeManager *instance();
141
142public Q_SLOTS:
143 /*!
144 * \brief Activates the KColorScheme identified by the provided \param index.
145 *
146 * Installs the KColorScheme as the QApplication's QPalette.
147 *
148 * \param index The index for the KColorScheme to activate.
149 * The index must reference the QAbstractItemModel provided by model(). Since
150 * version 5.67 passing an invalid index activates the system scheme.
151 * \sa model()
152 */
153 void activateScheme(const QModelIndex &index);
154
155private:
156 class KCOLORSCHEME_NO_EXPORT GuardApplicationConstructor
157 {
158 };
159 KCOLORSCHEME_NO_EXPORT explicit KColorSchemeManager(GuardApplicationConstructor, QGuiApplication *app);
160 KCOLORSCHEME_NO_EXPORT void init();
161
162 std::unique_ptr<KColorSchemeManagerPrivate> const d;
163};
164
165#endif
166

source code of kcolorscheme/src/kcolorschememanager.h