Differential D25877 Diff 71975 src/kcolorschememanager.h

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. 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
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.
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
109	public 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.
121	private:	131		private:
122	QScopedPointer<KColorSchemeManagerPrivate> d;	132		QScopedPointer<KColorSchemeManagerPrivate> d;
123	};	133		};
124		134
125	#endif	135		#endif