KDecoration2

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

KDE's Doxygen guidelines are available online.