KDecoration2

decoratedclient.h
1/*
2 * SPDX-FileCopyrightText: 2014 Martin Gräßlin <mgraesslin@kde.org>
3 *
4 * SPDX-License-Identifier: LGPL-2.1-only OR LGPL-3.0-only OR LicenseRef-KDE-Accepted-LGPL
5 */
6#pragma once
7
8#include "decoration.h"
9#include "decorationdefines.h"
10#include <kdecoration2/kdecoration2_export.h>
11
12#include <QFont>
13#include <QIcon>
14#include <QObject>
15#include <QPalette>
16#include <QPointer>
17#include <QtGui/qwindowdefs.h>
18
19#include <memory>
20
21namespace KDecoration2
22{
23class DecorationBridge;
24class DecoratedClientPrivate;
25
26/**
27 * @brief The Client which gets decorated.
28 *
29 * The DecoratedClient provides access to all the properties relevant for decorating the Client.
30 * Each DecoratedClient is bound to one Decoration and each Decoration is bound to this one
31 * DecoratedClient.
32 *
33 * The DecoratedClient only exports properties, it does not provide any means to change the state.
34 * To change state one needs to call the methods on Decoration. This is as the backend might
35 * disallow state changes. Therefore any changes should be bound to the change signals of the
36 * DecoratedClient and not be bound to state changes of input elements (such as a button).
37 */
38class KDECORATIONS2_EXPORT DecoratedClient : public QObject
39{
40 Q_OBJECT
41 /**
42 * The Decoration of this DecoratedClient
43 **/
44 Q_PROPERTY(KDecoration2::Decoration *decoration READ decoration CONSTANT)
45 /**
46 * Whether the DecoratedClient is active (has focus) or is inactive.
47 **/
48 Q_PROPERTY(bool active READ isActive NOTIFY activeChanged)
49 /**
50 * The caption of the DecoratedClient.
51 **/
52 Q_PROPERTY(QString caption READ caption NOTIFY captionChanged)
53 /**
54 * Whether the DecoratedClient is on all desktops or on just one.
55 **/
56 Q_PROPERTY(bool onAllDesktops READ isOnAllDesktops NOTIFY onAllDesktopsChanged)
57 /**
58 * Whether the DecoratedClient is shaded. Shaded means that the actual content is
59 * not visible, only the Decoration is visible.
60 **/
61 Q_PROPERTY(bool shaded READ isShaded NOTIFY shadedChanged)
62 /**
63 * The icon of the DecoratedClient. This can be used as the icon for the window menu button.
64 **/
65 Q_PROPERTY(QIcon icon READ icon NOTIFY iconChanged)
66 /**
67 * Whether the DecoratedClient is maximized. A DecoratedClient is maximized if it is both
68 * maximizedHorizontally and maximizedVertically. The Decoration of a maximized DecoratedClient
69 * should only consist of the title bar area.
70 **/
71 Q_PROPERTY(bool maximized READ isMaximized NOTIFY maximizedChanged)
72 /**
73 * Whether the DecoratedClient is maximized horizontally. A horizontally maximized DecoratedClient
74 * uses the maximal possible width.
75 **/
76 Q_PROPERTY(bool maximizedHorizontally READ isMaximizedHorizontally NOTIFY maximizedHorizontallyChanged)
77 /**
78 * Whether the DecoratedClient is maximized vertically. A vertically maximized DecoratedClient
79 * uses the maximal possible height.
80 **/
81 Q_PROPERTY(bool maximizedVertically READ isMaximizedVertically NOTIFY maximizedVerticallyChanged)
82 /**
83 * Whether the DecoratedClient is set to be kept above other DecoratedClients. There can be multiple
84 * DecoratedClients which are set to be kept above.
85 **/
86 Q_PROPERTY(bool keepAbove READ isKeepAbove NOTIFY keepAboveChanged)
87 /**
88 * Whether the DecoratedClient is set to be kept below other DecoratedClients. There can be multiple
89 * DecoratedClients which are set to be kept below.
90 **/
91 Q_PROPERTY(bool keepBelow READ isKeepBelow NOTIFY keepBelowChanged)
92
93 /**
94 * Whether the DecoratedClient can be closed. If this property is @c false a DecorationButton
95 * for closing the DecoratedClient should be disabled.
96 **/
97 Q_PROPERTY(bool closeable READ isCloseable NOTIFY closeableChanged)
98 /**
99 * Whether the DecoratedClient can be maximized. If this property is @c false a DecorationButton
100 * for maximizing the DecoratedClient should be disabled.
101 **/
102 Q_PROPERTY(bool maximizeable READ isMaximizeable NOTIFY maximizeableChanged)
103 /**
104 * Whether the DecoratedClient can be minimized. If this property is @c false a DecorationButton
105 * for minimizing the DecoratedClient should be disabled.
106 **/
107 Q_PROPERTY(bool minimizeable READ isMinimizeable NOTIFY minimizeableChanged)
108 /**
109 * Whether the DecoratedClient provides context help.
110 * The Decoration should only show a context help button if this property is @c true.
111 **/
112 Q_PROPERTY(bool providesContextHelp READ providesContextHelp NOTIFY providesContextHelpChanged)
113 /**
114 * Whether the DecoratedClient is a modal dialog.
115 **/
116 Q_PROPERTY(bool modal READ isModal CONSTANT)
117 /**
118 * Whether the DecoratedClient can be shaded. If this property is @c false a DecorationButton
119 * for shading the DecoratedClient should be disabled.
120 **/
121 Q_PROPERTY(bool shadeable READ isShadeable NOTIFY shadeableChanged)
122 /**
123 * Whether the DecoratedClient can be moved.
124 **/
125 Q_PROPERTY(bool moveable READ isMoveable NOTIFY moveableChanged)
126 /**
127 * Whether the DecoratedClient can be resized.
128 **/
129 Q_PROPERTY(bool resizeable READ isResizeable NOTIFY resizeableChanged)
130
131 /**
132 * The width of the DecoratedClient.
133 **/
134 Q_PROPERTY(int width READ width NOTIFY widthChanged)
135 /**
136 * The height of the DecoratedClient.
137 **/
138 Q_PROPERTY(int height READ height NOTIFY heightChanged)
139 /**
140 * The size of the DecoratedClient.
141 **/
142 Q_PROPERTY(QSize size READ size NOTIFY sizeChanged)
143 /**
144 * The palette this DecoratedClient uses. The palette might be different for each
145 * DecoratedClient and the Decoration should honor the palette.
146 **/
147 Q_PROPERTY(QPalette palette READ palette NOTIFY paletteChanged)
148 /**
149 * The Edges which are adjacent to a screen edge. E.g. for a maximized DecoratedClient this
150 * will include all Edges. The Decoration can use this information to hide borders.
151 **/
152 Q_PROPERTY(Qt::Edges adjacentScreenEdges READ adjacentScreenEdges NOTIFY adjacentScreenEdgesChanged)
153 /**
154 * Whether the DecoratedClient has an application menu
155 * @since 5.9
156 */
157 Q_PROPERTY(bool hasApplicationMenu READ hasApplicationMenu NOTIFY hasApplicationMenuChanged)
158 /**
159 * Whether the application menu for this DecoratedClient is currently shown to the user
160 * The Decoration can use this information to highlight the respective button.
161 * @since 5.9
162 */
163 Q_PROPERTY(bool applicationMenuActive READ isApplicationMenuActive NOTIFY applicationMenuActiveChanged)
164
165 // TODO: properties for windowId and decorationId?
166
167public:
168 DecoratedClient() = delete;
169 ~DecoratedClient() override;
170 bool isActive() const;
171 QString caption() const;
172 bool isOnAllDesktops() const;
173 bool isShaded() const;
174 QIcon icon() const;
175 bool isMaximized() const;
176 bool isMaximizedHorizontally() const;
177 bool isMaximizedVertically() const;
178 bool isKeepAbove() const;
179 bool isKeepBelow() const;
180
181 bool isCloseable() const;
182 bool isMaximizeable() const;
183 bool isMinimizeable() const;
184 bool providesContextHelp() const;
185 bool isModal() const;
186 bool isShadeable() const;
187 bool isMoveable() const;
188 bool isResizeable() const;
189
190 Qt::Edges adjacentScreenEdges() const;
191
192 WId windowId() const;
193 WId decorationId() const;
194
195 QString windowClass() const;
196
197 int width() const;
198 int height() const;
199 QSize size() const;
200
201 Decoration *decoration() const;
202 QPalette palette() const;
203 /**
204 * Used to get colors in QPalette.
205 * @param group The color group
206 * @param role The color role
207 * @return palette().color(group, role)
208 * @since 5.3
209 **/
210 QColor color(QPalette::ColorGroup group, QPalette::ColorRole role) const;
211 /**
212 * Used to get additional colors that are not in QPalette.
213 * @param group The color group
214 * @param role The color role
215 * @return The color if provided for combination of group and role, otherwise invalid QColor.
216 * @since 5.3
217 **/
218 QColor color(ColorGroup group, ColorRole role) const;
219
220 /**
221 * Whether the DecoratedClient has an application menu
222 * @since 5.9
223 */
224 bool hasApplicationMenu() const;
225 /**
226 * Whether the application menu for this DecoratedClient is currently shown to the user
227 * The Decoration can use this information to highlight the respective button.
228 * @since 5.9
229 */
230 bool isApplicationMenuActive() const;
231
232 /**
233 * Request the application menu to be shown to the user
234 * @param actionId The DBus menu ID of the action that should be highlighted, 0 for none.
235 */
236 void showApplicationMenu(int actionId);
237
238Q_SIGNALS:
239 void activeChanged(bool);
240 void captionChanged(QString);
241 void onAllDesktopsChanged(bool);
242 void shadedChanged(bool);
243 void iconChanged(QIcon);
244 void maximizedChanged(bool);
245 void maximizedHorizontallyChanged(bool);
246 void maximizedVerticallyChanged(bool);
247 void keepAboveChanged(bool);
248 void keepBelowChanged(bool);
249
250 void closeableChanged(bool);
251 void maximizeableChanged(bool);
252 void minimizeableChanged(bool);
253 void providesContextHelpChanged(bool);
254 void shadeableChanged(bool);
255 void moveableChanged(bool);
256 void resizeableChanged(bool);
257
258 void widthChanged(int);
259 void heightChanged(int);
260 void sizeChanged(const QSize &size);
261 void paletteChanged(const QPalette &palette);
262 void adjacentScreenEdgesChanged(Qt::Edges edges);
263
264 void hasApplicationMenuChanged(bool);
265 void applicationMenuActiveChanged(bool);
266
267private:
268 friend class Decoration;
269 DecoratedClient(Decoration *parent, DecorationBridge *bridge);
270 const std::unique_ptr<DecoratedClientPrivate> d;
271};
272
273} // namespace
The Client which gets decorated.
Base class for the Decoration.
Definition decoration.h:58
Framework for creating window decorations.
ColorRole
Color roles are used for DecoratedClient::color().
ColorGroup
Color groups are used for DecoratedClient::color().
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Mon Nov 4 2024 16:31:06 by doxygen 1.12.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.