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

KDE's Doxygen guidelines are available online.