MauiKit Controls

csdcontrols.h
1#pragma once
2
3#include <QObject>
4#include <QSettings>
5#include <QQmlEngine>
6
7namespace MauiMan
8{
9 class ThemeManager;
10}
11
12/**
13 * @brief An abstraction for a client-side-decoration button.
14 *
15 * This class is exposed as the type `CSDButton` to the QML engine, and it is used for creating the CSD window control themes.
16 *
17 * CSDButton represents a button and its states. By reading the theme configuration, this class changes the images used as its state changes. The states need to be set manually.
18 */
19class CSDButton : public QObject
20{
22 QML_ELEMENT
23 Q_DISABLE_COPY(CSDButton)
24
25 /**
26 * Whether the button is currently being hovered.
27 * Uses the `Hover` config entry to read the image file asset.
28 */
29 Q_PROPERTY(bool isHovered READ isHovered WRITE setIsHovered NOTIFY isHoveredChanged)
30
31 /**
32 * Whether the window is currently maximized.
33 * Uses the `Restore` config section to read the image file assets.
34 */
35 Q_PROPERTY(bool isMaximized READ isMaximized WRITE setIsMaximized NOTIFY isMaximizedChanged)
36
37 /**
38 * Whether the button is currently being pressed.
39 * Uses the `Pressed` config entry to read the image file asset.
40 */
41 Q_PROPERTY(bool isPressed READ isPressed WRITE setIsPressed NOTIFY isPressedChanged)
42
43 /**
44 * Whether the window is currently focused.
45 * Uses the `Normal` config entry to read the image file asset, if focused, other wise, the `Backdrop` entry.
46 */
47 Q_PROPERTY(bool isFocused READ isFocused WRITE setIsFocused NOTIFY isFocusedChanged)
48
49 /**
50 * The button type.
51 * @see CSDButtonType
52 */
53 Q_PROPERTY(CSDButtonType type READ type WRITE setType NOTIFY typeChanged)
54
55 /**
56 * The source file path of the theme being used.
57 */
58 Q_PROPERTY(QUrl source READ source NOTIFY sourceChanged FINAL)
59
60 /**
61 * The style to be used for picking up the image assets and config.
62 * By default this will be set to the current preferred window controls style preference from MauiMan.
63 * However, this can be overridden to another existing style.
64 */
65 Q_PROPERTY(QString style READ style WRITE setStyle NOTIFY styleChanged)
66
67public:
68
69 /**
70 * @brief The states of a window control button.
71 */
73 {
74 /**
75 * The window surface is focused
76 */
78
79 /**
80 * The button is being hovered but has not been activated
81 */
83
84 /**
85 * The button is being pressed and has not been released
86 */
88
89 /**
90 * The window surface is in not focused
91 */
93
94 /**
95 * The window or the button are not enabled
96 */
98 }; Q_ENUM(CSDButtonState)
99
100 /**
101 * @brief The possible types of supported window control buttons
102 */
103 enum CSDButtonType
104 {
105 /**
106 * Closes the window surface
107 */
108 Close,
109
110 /**
111 * Minimizes/hides the window surface
112 */
113 Minimize,
114
115 /**
116 * Maximizes the window surface
117 */
118 Maximize,
119
120 /**
121 * Restores the window surface to the previous geometry it had before being maximized
122 */
123 Restore,
124
125 /**
126 * Makes the window surface occupy the whole screen area
127 */
128 Fullscreen,
129
130 /**
131 * No button
132 */
133 None
134 };Q_ENUM(CSDButtonType)
135
136 explicit CSDButton(QObject *parent =nullptr);
137
138 CSDButtonState state() const;
139 void setState(const CSDButtonState &state);
140 QUrl source() const;
141
142 bool isHovered() const;
143 void setIsHovered(bool newIsHovered);
144
145 bool isMaximized() const;
146 void setIsMaximized(bool newIsMaximized);
147
148 bool isPressed() const;
149 void setIsPressed(bool newIsPressed);
150
151 bool isFocused() const;
152 void setIsFocused(bool newIsFocused);
153
154 CSDButton::CSDButtonType type() const;
155 void setType(CSDButton::CSDButtonType newType);
156
157 QString style() const;
158 void setStyle(const QString &style);
159
160public Q_SLOTS:
161
162 /**
163 * @brief Maps a based string value convention representing a button type to a CSDButton::CSDButtonType
164 *
165 * Usually each window control button is represented as a single letter, and the order of the window control buttons are an array of those string values.
166 *
167 * An example would be the following array `{"I", "A", "X"}`, which represents the following order: minimize, maximize, close
168 *
169 */
170 CSDButton::CSDButtonType mapType(const QString &value);
171
172private:
173 typedef QHash<CSDButtonState, QUrl> CSDButtonSources;
174
175 CSDButtonType m_type = CSDButtonType::None;
176 QUrl m_source;
177 QUrl m_dir;
178 CSDButtonState m_state = CSDButtonState::Normal;
179
180 CSDButtonSources m_sources; //the state and the source associated
181 QString m_style;
182
183 bool m_isHovered;
184
185 bool m_isMaximized;
186
187 bool m_isPressed;
188
189 bool m_isFocused;
190
191 QString mapButtonType(const CSDButtonType &type);
192 QString mapButtonState(const CSDButtonState &type);
193 QUrl extractStateValue(QSettings &settings, const CSDButton::CSDButtonState &state);
194 void setSources();
195 void requestCurrentSource();
196
198 void stateChanged();
199 void sourceChanged();
200 void isHoveredChanged();
201 void isMaximizedChanged();
202 void isPressedChanged();
203 void isFocusedChanged();
204 void typeChanged();
205 void styleChanged();
206};
207
208/**
209 * @brief The client-side-decorations manager for the MauiKit application.
210 */
211class CSDControls : public QObject
212{
214 // QML_SINGLETON
215 QML_NAMED_ELEMENT(CSD)
216 QML_ATTACHED(CSDControls)
217 QML_UNCREATABLE("Cannot be created CSDControls")
218 Q_DISABLE_COPY(CSDControls)
219
220 /**
221 * Whether the application shall use CSD (client side decorations).
222 *
223 * @note This property by default uses the MauiMan global preference, but can it be overridden. To reset it back to the original system preference value set it to `undefined`.
224 */
225 Q_PROPERTY(bool enabled READ enableCSD WRITE setEnableCSD RESET resetEnableCSD NOTIFY enableCSDChanged)
226
227 /**
228 * The source file path of the style being used.
229 */
230 Q_PROPERTY(QUrl source READ source NOTIFY sourceChanged FINAL)
231
232 /**
233 * The name of the style/theme being used.
234 * This is picked up from the global MauiMan preferences and can not be overridden by the application.
235 * This preference is exposed to the end user in the Maui Settings.
236 */
237 Q_PROPERTY(QString styleName READ styleName NOTIFY styleNameChanged FINAL)
238
239 /**
240 * The model of the window control buttons to be shown, and the order in which they should appear in the right side.
241 * Although the WindowControlsLinux type can be placed arbitrary, it is strongly suggested to always placed them in a right-side area
242 */
243 Q_PROPERTY(QStringList rightWindowControls MEMBER m_rightWindowControls FINAL CONSTANT)
244
245public:
246 explicit CSDControls(QObject *parent =nullptr);
247
248 bool enableCSD() const;
249
250 void setEnableCSD(const bool &value);
251 void resetEnableCSD();
252
253 QUrl source() const;
254 QString styleName() const;
255
256 /**
257 * @private
258 */
259 static CSDControls *qmlAttachedProperties(QObject *object);
260
261 /**
262 * @brief Retrieves the single instance of MauiApp.
263 */
264 static CSDControls *instance();
265
266 QObject * qmlInstance(QQmlEngine *engine, QJSEngine *scriptEngine) {
267 Q_UNUSED(engine);
268 Q_UNUSED(scriptEngine);
269 // C++ and QML instance they are the same instance
270 return CSDControls::instance();
271 }
272
273private:
275
276 MauiMan::ThemeManager *m_themeSettings;
277
278 bool m_enableCSD = false;
279 bool m_enabledCSD_blocked = false;
280
281 QUrl m_source;
282 QString m_styleName = QStringLiteral("Nitrux");
283 QStringList m_rightWindowControls;
284
285 void getWindowControlsSettings();
286 void setStyle();
287
289 void enableCSDChanged();
290 void styleNameChanged();
291 void sourceChanged();
292};
293
294QML_DECLARE_TYPEINFO(CSDControls, QML_HAS_ATTACHED_PROPERTIES)
295
An abstraction for a client-side-decoration button.
Definition csdcontrols.h:20
CSDButtonType type
The button type.
Definition csdcontrols.h:53
bool isPressed
Whether the button is currently being pressed.
Definition csdcontrols.h:41
bool isFocused
Whether the window is currently focused.
Definition csdcontrols.h:47
Q_ENUM(CSDButtonState) enum CSDButtonType
The possible types of supported window control buttons.
Definition csdcontrols.h:98
QUrl source
The source file path of the theme being used.
Definition csdcontrols.h:58
CSDButton::CSDButtonType mapType(const QString &value)
Maps a based string value convention representing a button type to a CSDButton::CSDButtonType.
QML_ELEMENTbool isHovered
Whether the button is currently being hovered.
Definition csdcontrols.h:29
CSDButtonState
The states of a window control button.
Definition csdcontrols.h:73
@ Disabled
The window or the button are not enabled.
Definition csdcontrols.h:97
@ Normal
The window surface is focused.
Definition csdcontrols.h:77
@ Pressed
The button is being pressed and has not been released.
Definition csdcontrols.h:87
@ Hover
The button is being hovered but has not been activated.
Definition csdcontrols.h:82
@ Backdrop
The window surface is in not focused.
Definition csdcontrols.h:92
QString style
The style to be used for picking up the image assets and config.
Definition csdcontrols.h:65
bool isMaximized
Whether the window is currently maximized.
Definition csdcontrols.h:35
The client-side-decorations manager for the MauiKit application.
static CSDControls * instance()
Retrieves the single instance of MauiApp.
QUrl source
The source file path of the style being used.
bool enabled
Whether the application shall use CSD (client side decorations).
QStringList rightWindowControls
The model of the window control buttons to be shown, and the order in which they should appear in the...
QString styleName
The name of the style/theme being used.
Q_OBJECTQ_OBJECT
Q_PROPERTY(...)
Q_SIGNALSQ_SIGNALS
Q_SLOTSQ_SLOTS
QObject * parent() const const
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Fri May 17 2024 11:56:16 by doxygen 1.10.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.