Differential D25877 Diff 71976 src/kcolorschememanager.h

Changeset View

Standalone View

View Options

src/kcolorschememanager.h

Show All 30 Lines
31class 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. It also allows going back to following
40​ * the system color scheme.
kossebauUnsubmitted
Done

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.

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
67public: 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.
83 * @see model 86​ * @see model
84 */ 87​ */
85 QModelIndex indexForScheme(const QString &name) const; 88​ QModelIndex indexForScheme(const QString &name) const;
86 89​
87 /** 90​ /**
88 * Creates a KActionMenu populated with all the available color schemes. 91​ * 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 92​ * All actions are in an action group and when one of the actions is triggered the scheme
90 * referenced by this action is activated. 93​ * referenced by this action is activated.
91 * 94​ *
92 * The color scheme with the same name as @p selectedSchemeName will be checked. If none 95​ * 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. 96​ * of the available color schemes has the same name, the system theme entry will be checked.
94 * 97​ *
95 * The KActionMenu will not be updated in case the installed color schemes change. It's the 98​ * 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. 99​ * task of the user of the KActionMenu to monitor for changes if required.
97 * 100​ *
98 * @param icon The icon to use for the KActionMenu 101​ * @param icon The icon to use for the KActionMenu
99 * @param text The text to use for the KActionMenu 102​ * @param text The text to use for the KActionMenu
100 * @param selectedSchemeName The name of the color scheme to select 103​ * @param selectedSchemeName The name of the color scheme to select
101 * @param parent The parent of the KActionMenu 104​ * @param parent The parent of the KActionMenu
102 * @return KActionMenu populated with all available color schemes. 105​ * @return KActionMenu populated with all available color schemes.
103 * @see activateScheme 106​ * @see activateScheme
104 */ 107​ */
105 KActionMenu *createSchemeSelectionMenu(const QIcon &icon, const QString &text, const QString &selectedSchemeName, QObject *parent); 108​ KActionMenu *createSchemeSelectionMenu(const QIcon &icon, const QString &text, const QString &selectedSchemeName, QObject *parent);
106 KActionMenu *createSchemeSelectionMenu(const QString &text, const QString &selectedSchemeName, QObject *parent); 109​ KActionMenu *createSchemeSelectionMenu(const QString &text, const QString &selectedSchemeName, QObject *parent);
107 KActionMenu *createSchemeSelectionMenu(const QString &selectedSchemeName, QObject *parent); 110​ KActionMenu *createSchemeSelectionMenu(const QString &selectedSchemeName, QObject *parent);
111​ KActionMenu *createSchemeSelectionMenu(QObject *parent);
davidreAuthorUnsubmitted
Done

Would I need to add @since for a new overload?

davidre: Would I need to add @since for a new overload?
ahmadsamirUnsubmitted
Done

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:

The @since tag tells users since when the class has existed. It is usual to put a KDE release number here.

Method documentation: We can use @author and @since just like we do for classes.

ahmadsamir: I would say yes (your question made me search for an answer since I wanted too:)), from https…
ahmadsamirUnsubmitted
Done

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).
kossebauUnsubmitted
Done

"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…
108 112​
109public Q_SLOTS: 113​public Q_SLOTS:
110 /** 114​ /**
111 * @brief Activates the KColorScheme identified by the provided @p index. 115​ * @brief Activates the KColorScheme identified by the provided @p index.
112 * 116​ *
113 * Installs the KColorScheme as the QApplication's QPalette. 117​ * Installs the KColorScheme as the QApplication's QPalette.
114 * 118​ *
115 * @param index The index for the KColorScheme to activate. 119​ * @param index The index for the KColorScheme to activate.
116 * The index must reference the QAbstractItemModel provided by @link model @endlink 120​ * The index must reference the QAbstractItemModel provided by @link model @endlink
117 * @see model() 121​ * @see model()
118 */ 122​ */
119 void activateScheme(const QModelIndex &index); 123​ void activateScheme(const QModelIndex &index);
120 124​
125​ /**
126​ * Convenience function to go back to following the system color scheme.
127​ * @since 5.66
128​ */
129​ void followSystemScheme();
asemkeUnsubmitted
Done

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?
130​
davidreAuthorUnsubmitted
Done

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…
asemkeUnsubmitted
Done

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…
davidreAuthorUnsubmitted
Done

I like that idea with an empty ModelIndex.

davidre: I like that idea with an empty ModelIndex.
121private: 131​private:
122 QScopedPointer<KColorSchemeManagerPrivate> d; 132​ QScopedPointer<KColorSchemeManagerPrivate> d;
123}; 133​};
124 134​
125#endif 135​#endif