Changeset View
Standalone View
src/kcolorschememanager.h
Show All 30 Lines | |||||
31 | class KColorSchemeManagerPrivate; | 31 | class KColorSchemeManagerPrivate; | ||
32 | 32 | | |||
33 | /** | 33 | /** | ||
34 | * @class KColorSchemeManager kcolorschememanager.h KColorSchemeManager | 34 | * @class KColorSchemeManager kcolorschememanager.h KColorSchemeManager | ||
35 | * | 35 | * | ||
36 | * A small helper to get access to all available color schemes and activating a scheme in the | 36 | * A small helper to get access to all available color schemes and activating a scheme in the | ||
37 | * QApplication. This is useful for applications which want to provide a selection of custom color | 37 | * QApplication. This is useful for applications which want to provide a selection of custom color | ||
38 | * schemes to their user. For example it is very common for photo and painting applications to use | 38 | * schemes to their user. For example it is very common for photo and painting applications to use | ||
39 | * a dark color scheme even if the default is a light scheme. | 39 | * a dark color scheme even if the default is a light scheme. Since version 5.66 it also allows | ||
40 | * going back to following the system color scheme. | ||||
kossebau: Here you might also want to state at which version this feature of "allows going back" was… | |||||
40 | * | 41 | * | ||
41 | * The KColorSchemeManager provides access to a QAbstractItemModel which holds all the available | 42 | * The KColorSchemeManager provides access to a QAbstractItemModel which holds all the available | ||
42 | * schemes. A possible usage looks like the following: | 43 | * schemes. A possible usage looks like the following: | ||
43 | * | 44 | * | ||
44 | * @code | 45 | * @code | ||
45 | * KColorSchemeManager *schemes = new KColorSchemeManager(this); | 46 | * KColorSchemeManager *schemes = new KColorSchemeManager(this); | ||
46 | * QListView *view = new QListView(this); | 47 | * QListView *view = new QListView(this); | ||
47 | * view->setModel(schemes->model()); | 48 | * view->setModel(schemes->model()); | ||
Show All 19 Lines | |||||
67 | public: | 68 | public: | ||
68 | explicit KColorSchemeManager(QObject *parent = nullptr); | 69 | explicit KColorSchemeManager(QObject *parent = nullptr); | ||
69 | virtual ~KColorSchemeManager(); | 70 | virtual ~KColorSchemeManager(); | ||
70 | 71 | | |||
71 | /** | 72 | /** | ||
72 | * A QAbstractItemModel of all available color schemes. | 73 | * A QAbstractItemModel of all available color schemes. | ||
73 | * | 74 | * | ||
74 | * The model provides the name of the scheme in Qt::DisplayRole, a preview | 75 | * The model provides the name of the scheme in Qt::DisplayRole, a preview | ||
75 | * in Qt::DelegateRole and the full path to the scheme file in Qt::UserRole. | 76 | * in Qt::DelegateRole and the full path to the scheme file in Qt::UserRole. The system theme | ||
77 | * has an empty Qt::UserRole. | ||||
76 | * | 78 | * | ||
77 | * @return Model of all available color schemes. | 79 | * @return Model of all available color schemes. | ||
78 | */ | 80 | */ | ||
79 | QAbstractItemModel *model() const; | 81 | QAbstractItemModel *model() const; | ||
80 | /** | 82 | /** | ||
81 | * Returns the model index for the scheme with the given @p name. If no such | 83 | * Returns the model index for the scheme with the given @p name. If no such | ||
82 | * scheme exists an invalid index is returned. | 84 | * scheme exists an invalid index is returned. If you pass an empty | ||
85 | * string the index that is equivalent to going back to following the system scheme is returned | ||||
86 | * for versions 5.66 and newer. | ||||
83 | * @see model | 87 | * @see model | ||
84 | */ | 88 | */ | ||
85 | QModelIndex indexForScheme(const QString &name) const; | 89 | QModelIndex indexForScheme(const QString &name) const; | ||
86 | 90 | | |||
87 | /** | 91 | /** | ||
88 | * Creates a KActionMenu populated with all the available color schemes. | 92 | * Creates a KActionMenu populated with all the available color schemes. | ||
89 | * All actions are in an action group and when one of the actions is triggered the scheme | 93 | * All actions are in an action group and when one of the actions is triggered the scheme | ||
90 | * referenced by this action is activated. | 94 | * referenced by this action is activated. | ||
91 | * | 95 | * | ||
92 | * The color scheme with the same name as @p selectedSchemeName will be checked. If none | 96 | * The color scheme with the same name as @p selectedSchemeName will be checked. If none | ||
93 | * of the available color schemes has the same name, no action will be checked. | 97 | * of the available color schemes has the same name, the system theme entry will be checked. | ||
94 | * | 98 | * | ||
95 | * The KActionMenu will not be updated in case the installed color schemes change. It's the | 99 | * The KActionMenu will not be updated in case the installed color schemes change. It's the | ||
96 | * task of the user of the KActionMenu to monitor for changes if required. | 100 | * task of the user of the KActionMenu to monitor for changes if required. | ||
97 | * | 101 | * | ||
98 | * @param icon The icon to use for the KActionMenu | 102 | * @param icon The icon to use for the KActionMenu | ||
99 | * @param text The text to use for the KActionMenu | 103 | * @param text The text to use for the KActionMenu | ||
100 | * @param selectedSchemeName The name of the color scheme to select | 104 | * @param selectedSchemeName The name of the color scheme to select | ||
101 | * @param parent The parent of the KActionMenu | 105 | * @param parent The parent of the KActionMenu | ||
102 | * @return KActionMenu populated with all available color schemes. | 106 | * @return KActionMenu populated with all available color schemes. | ||
103 | * @see activateScheme | 107 | * @see activateScheme | ||
104 | */ | 108 | */ | ||
105 | KActionMenu *createSchemeSelectionMenu(const QIcon &icon, const QString &text, const QString &selectedSchemeName, QObject *parent); | 109 | KActionMenu *createSchemeSelectionMenu(const QIcon &icon, const QString &text, const QString &selectedSchemeName, QObject *parent); | ||
106 | KActionMenu *createSchemeSelectionMenu(const QString &text, const QString &selectedSchemeName, QObject *parent); | 110 | KActionMenu *createSchemeSelectionMenu(const QString &text, const QString &selectedSchemeName, QObject *parent); | ||
107 | KActionMenu *createSchemeSelectionMenu(const QString &selectedSchemeName, QObject *parent); | 111 | KActionMenu *createSchemeSelectionMenu(const QString &selectedSchemeName, QObject *parent); | ||
112 | /** | ||||
davidre: Would I need to add @since for a new overload? | |||||
I would say yes (your question made me search for an answer since I wanted too:)), from https://community.kde.org/Guidelines_and_HOWTOs/API_Documentation:
ahmadsamir: I would say yes (your question made me search for an answer since I wanted too:)), from https… | |||||
s/wanted/wanted to know/ (phabricator doesn't let us edit inline comments.... weird). ahmadsamir: s/wanted/wanted to know/ (phabricator doesn't let us edit inline comments.... weird). | |||||
"Would I need"... put yourself in the shoes of a user of this class: you would want to know at which version this new overload is available when using it in your code which sets itself a certain version of KF as minimal expected, right? :) So yes, you want to help the users of the API to know at which versions of KF they can expect which methods and classes to be present. And thus you want to ensure "@since" with any API changes, incl. new methods added, overloaded or not. kossebau: "Would I need"... put yourself in the shoes of a user of this class: you would want to know at… | |||||
113 | * @since 5.66 | ||||
114 | */ | ||||
115 | KActionMenu *createSchemeSelectionMenu(QObject *parent); | ||||
108 | 116 | | |||
109 | public Q_SLOTS: | 117 | public Q_SLOTS: | ||
110 | /** | 118 | /** | ||
111 | * @brief Activates the KColorScheme identified by the provided @p index. | 119 | * @brief Activates the KColorScheme identified by the provided @p index. | ||
112 | * | 120 | * | ||
113 | * Installs the KColorScheme as the QApplication's QPalette. | 121 | * Installs the KColorScheme as the QApplication's QPalette. | ||
114 | * | 122 | * | ||
115 | * @param index The index for the KColorScheme to activate. | 123 | * @param index The index for the KColorScheme to activate. | ||
116 | * The index must reference the QAbstractItemModel provided by @link model @endlink | 124 | * The index must reference the QAbstractItemModel provided by @link model @endlink. Since | ||
125 | * version 5.66 passing an invalid index activates the system scheme. | ||||
117 | * @see model() | 126 | * @see model() | ||
118 | */ | 127 | */ | ||
119 | void activateScheme(const QModelIndex &index); | 128 | void activateScheme(const QModelIndex &index); | ||
120 | 129 | | |||
121 | private: | 130 | private: | ||
122 | QScopedPointer<KColorSchemeManagerPrivate> d; | 131 | QScopedPointer<KColorSchemeManagerPrivate> d; | ||
123 | }; | 132 | }; | ||
124 | 133 | | |||
125 | #endif | 134 | #endif | ||
What should be the use-case for this new function and should it really be a slot? asemke: What should be the use-case for this new function and should it really be a slot? | |||||
I thought it would be nice to have as a convenience function if an application has changed the scheme to easily go back to the system color scheme. I don't know if it should be a slot. I put it there because activateScheme is here. davidre: I thought it would be nice to have as a convenience function if an application has changed the… | |||||
I think the only communication channel with KColorSchemeManager is via the menu created in createSchemeSelectionMenu(). Setting back the default scheme will also be done via this menu. I don't see why an application would need such a helper function - there is simply no other handling of the color schemes in the applications except of that menu. Also, if somebody would still need such a helper function, he/she could use activateScheme(QModelIndex()) instead of followSystemScheme(). activateScheme() exists already and an empty QModelIndex() could be interpreted as the default color scheme. asemke: I think the only communication channel with KColorSchemeManager is via the menu created in… | |||||
davidre: I like that idea with an empty ModelIndex. |
Here you might also want to state at which version this feature of "allows going back" was added, to make it clear that with older versions of KF this was not possible.
Same with the existing methods where behaviour was changed.