KWindowSystem

kwindowsystem.h
1 /*
2  This file is part of the KDE libraries
3  SPDX-FileCopyrightText: 1999 Matthias Ettrich <[email protected]>
4  SPDX-FileCopyrightText: 2007 Lubos Lunak <[email protected]>
5 
6  SPDX-License-Identifier: LGPL-2.1-or-later
7 */
8 /*
9  * kwindowsystem.h. Part of the KDE project.
10  */
11 
12 #ifndef KWINDOWSYSTEM_H
13 #define KWINDOWSYSTEM_H
14 
15 #include <QObject>
16 #include <QWidgetList> //For WId
17 #include <kwindowinfo.h>
18 #include <kwindowsystem_export.h>
19 #include <netwm_def.h>
20 
21 class KWindowSystemPrivate;
22 class NETWinInfo;
23 
24 /**
25  *
26  * Convenience access to certain properties and features of the
27  * window manager.
28  *
29  * The class KWindowSystem provides information about the state of the
30  * window manager and allows asking the window manager to change them
31  * using a more high-level interface than the NETWinInfo/NETRootInfo
32  * lowlevel classes.
33  *
34  * Because of limitations of the way Qt is implemented on Mac OSX, the WId's
35  * returned by methods in this class are not compatible with those expected
36  * by other Qt methods. So while it should be fine to pass WId's retrieved by
37  * for example calling the winId method on a QWidget to methods in this class
38  * the reverse is not true. You should never pass a WId obtained from this class
39  * to a Qt method accepting a WId parameter.
40  *
41  * @short Class for interaction with the window manager.
42  * @author Matthias Ettrich ([email protected])
43  */
44 class KWINDOWSYSTEM_EXPORT KWindowSystem : public QObject, public NET
45 {
46  Q_OBJECT
47  Q_PROPERTY(bool isPlatformWayland READ isPlatformWayland CONSTANT)
48  Q_PROPERTY(bool isPlatformX11 READ isPlatformX11 CONSTANT)
49 
50 public:
51  /**
52  * Access to the singleton instance. Useful mainly for connecting to signals.
53  */
54  static KWindowSystem *self();
55 
56 #if KWINDOWSYSTEM_ENABLE_DEPRECATED_SINCE(5, 101)
57  /**
58  * Returns the list of all toplevel windows currently managed by the
59  * window manager in the order of creation. Please do not rely on
60  * indexes of this list: Whenever you enter Qt's event loop in your
61  * application, it may happen that entries are removed or added.
62  * Your module should perhaps work on a copy of this list and verify a
63  * window with hasWId() before any operations.
64  *
65  * Iteration over this list can be done easily with
66  * \code
67  * QList<WId> windows = KWindowSystem::windows();
68  * for (auto it = windows.cbegin(), end = windows.cend(); it != end; ++it) {
69  * ... do something here, (*it) is the current WId.
70  * }
71  * \endcode
72  * @return the list of all toplevel windows
73  * @deprecated since 5.101, use KX11Extras::windows()
74  */
75  KWINDOWSYSTEM_DEPRECATED_VERSION(5, 101, "Use KX11Extras::windows() instead")
76  static QList<WId> windows();
77 #endif
78 
79 #if KWINDOWSYSTEM_ENABLE_DEPRECATED_SINCE(5, 101)
80  /**
81  * Test to see if @p id still managed at present.
82  * @param id the window id to test
83  * @return true if the window id is still managed
84  * @deprecated since 5.101, use KX11Extras::hasWId()
85  **/
86  KWINDOWSYSTEM_DEPRECATED_VERSION(5, 101, "Use KX11Extras::hasWId() instead")
87  static bool hasWId(WId id);
88 #endif
89 
90 #if KWINDOWSYSTEM_ENABLE_DEPRECATED_SINCE(5, 0)
91  /**
92  * Returns information about window @p win. It is recommended to check
93  * whether the returned info is valid by calling the valid() method.
94  * @param win the id of the window
95  * @param properties all properties that should be retrieved (see NET::Property
96  * enum for details). Unlisted properties cause related information to be invalid
97  * in the returned data, but make this function faster when not all data is needed.
98  * @param properties2 additional properties (see NET::Property2 enum)
99  * @return the window information
100  * @deprecated Since 5.0, use KWindowInfo directly
101  */
102  KWINDOWSYSTEM_DEPRECATED_VERSION(5, 0, "Use KWindowInfo(WId, NET::Properties, NET::Properties2")
103  static KWindowInfo windowInfo(WId win, NET::Properties properties, NET::Properties2 properties2 = NET::Properties2());
104 #endif
105 
106 #if KWINDOWSYSTEM_ENABLE_DEPRECATED_SINCE(5, 101)
107  /**
108  * Returns the list of all toplevel windows currently managed by the
109  * window manager in the current stacking order (from lower to
110  * higher). May be useful for pagers.
111  * @return the list of all toplevel windows in stacking order
112  * @deprecated since 5.101, use KX11Extras::stackingOrder()
113  */
114  KWINDOWSYSTEM_DEPRECATED_VERSION(5, 101, "Use KX11Extras::stackingOrder() instead")
115  static QList<WId> stackingOrder();
116 #endif
117 
118 #if KWINDOWSYSTEM_ENABLE_DEPRECATED_SINCE(5, 101)
119  /**
120  * Returns the currently active window, or 0 if no window is active.
121  * @return the window id of the active window, or 0 if no window is
122  * active
123  * @deprecated since 5.101, use KX11Extras::activeWindow()
124  **/
125  KWINDOWSYSTEM_DEPRECATED_VERSION(5, 101, "Use KX11Extras::activeWindow() instead")
126  static WId activeWindow();
127 #endif
128 
129 #if KWINDOWSYSTEM_ENABLE_DEPRECATED_SINCE(5, 101)
130  /**
131  * Requests that window @p win is activated.
132  *
133  * There are two ways how to activate a window, by calling
134  * activateWindow() and forceActiveWindow(). Generally,
135  * applications shouldn't make attempts to explicitly activate
136  * their windows, and instead let the user to activate them.
137  * In the special cases where this may be needed, applications
138  * should use activateWindow(). Window manager may consider whether
139  * this request wouldn't result in focus stealing, which
140  * would be obtrusive, and may refuse the request.
141  *
142  * The usage of forceActiveWindow() is meant only for pagers
143  * and similar tools, which represent direct user actions
144  * related to window manipulation.
145  * Except for rare cases, this request will be always honored,
146  * and normal applications are forbidden to use it.
147  *
148  * In case of problems, consult the KWin README in the kdebase
149  * package (kdebase/kwin/README), or ask on the [email protected]
150  * mailing list.
151  *
152  * @param win the id of the window to make active
153  * @param time X server timestamp of the user activity that
154  * caused this request
155  * @deprecated since 5.101, use KX11Extras::activateWindow() or KWindowSystem::activateWindow(QWindow *) instead
156  */
157  KWINDOWSYSTEM_DEPRECATED_VERSION(5, 101, "Use KX11Extras::activateWindow() or KWindowSystem::activateWindow(QWindow *) instead")
158  static void activateWindow(WId win, long time = 0);
159 #endif
160 
161  /**
162  * Requests that window @p win is activated.
163  *
164  * There are two ways how to activate a window, by calling
165  * activateWindow() and forceActiveWindow(). Generally,
166  * applications shouldn't make attempts to explicitly activate
167  * their windows, and instead let the user to activate them.
168  * In the special cases where this may be needed, applications
169  * should use activateWindow(). Window manager may consider whether
170  * this request wouldn't result in focus stealing, which
171  * would be obtrusive, and may refuse the request.
172  *
173  * The usage of forceActiveWindow() is meant only for pagers
174  * and similar tools, which represent direct user actions
175  * related to window manipulation.
176  * Except for rare cases, this request will be always honored,
177  * and normal applications are forbidden to use it.
178  *
179  * In case of problems, consult the KWin README in the kdebase
180  * package (kdebase/kwin/README), or ask on the [email protected]
181  * mailing list.
182  *
183  * @param window the window to make active
184  * @param time X server timestamp of the user activity that
185  * caused this request
186  *
187  * @since 5.89
188  */
189  Q_INVOKABLE static void activateWindow(QWindow *window, long time = 0);
190 
191 #if KWINDOWSYSTEM_ENABLE_DEPRECATED_SINCE(5, 101)
192  /**
193  * Sets window @p win to be the active window. Note that this
194  * should be called only in special cases, applications
195  * shouldn't force themselves or other windows to be the active
196  * window. Generally, this call should used only by pagers
197  * and similar tools. See the explanation in description
198  * of activateWindow().
199  *
200  * @param win the id of the window to make active
201  * @param time X server timestamp of the user activity that
202  * caused this request
203  * @deprecated since 5.101, use KX11Extras::forceActiveWindow()
204  */
205  KWINDOWSYSTEM_DEPRECATED_VERSION(5, 101, "Use KX11Extras::forceActiveWindow() instead")
206  static void forceActiveWindow(WId win, long time = 0);
207 #endif
208 
209 #if KWINDOWSYSTEM_ENABLE_DEPRECATED_SINCE(5, 101)
210  /**
211  * When application finishes some operation and wants to notify
212  * the user about it, it can call demandAttention(). Instead
213  * of activating the window, which could be obtrusive, the window
214  * will be marked specially as demanding user's attention.
215  * See also explanation in description of activateWindow().
216  *
217  * Note that it's usually better to use KNotifyClient.
218  * @deprecated since 5.101, use QWindow::alert() instead().
219  */
220  KWINDOWSYSTEM_DEPRECATED_VERSION(5, 101, "Use QWindow::alert()")
221  static void demandAttention(WId win, bool set = true);
222 #endif
223 
224 #if KWINDOWSYSTEM_ENABLE_DEPRECATED_SINCE(5, 101)
225  /**
226  * Returns true if a compositing manager is running (i.e. ARGB windows
227  * are supported, effects will be provided, etc.).
228  * @deprecated since 5.101, use KX11Extras::compositingActive()
229  */
230  KWINDOWSYSTEM_DEPRECATED_VERSION(5, 101, "Use KX11Extras::compositingActive() instead")
231  static bool compositingActive();
232 #endif
233 
234 #if KWINDOWSYSTEM_ENABLE_DEPRECATED_SINCE(5, 101)
235  /**
236  * Returns the current virtual desktop.
237  * @return the current virtual desktop
238  * @deprecated since 5.101, use KX11Extras::currentDesktop()
239  **/
240  KWINDOWSYSTEM_DEPRECATED_VERSION(5, 101, "Use KX11Extras::currentDesktop() instead")
241  static int currentDesktop();
242 #endif
243 
244 #if KWINDOWSYSTEM_ENABLE_DEPRECATED_SINCE(5, 101)
245  /**
246  * Returns the number of virtual desktops.
247  * @return the number of virtual desktops
248  * @deprecated since 5.101, use KX11Extras::numberOfDesktops()
249  **/
250  KWINDOWSYSTEM_DEPRECATED_VERSION(5, 101, "Use KX11Extras::numberOfDesktops() instead")
251  static int numberOfDesktops();
252 #endif
253 
254 #if KWINDOWSYSTEM_ENABLE_DEPRECATED_SINCE(5, 101)
255  /**
256  * Convenience function to set the current desktop to @p desktop.
257  * See NETRootInfo.
258  * @param desktop the number of the new desktop
259  * @deprecated since 5.101, use KX11Extras::setCurrentDesktop()
260  */
261  KWINDOWSYSTEM_DEPRECATED_VERSION(5, 101, "Use KX11Extras::setCurrentDesktop() instead")
262  static void setCurrentDesktop(int desktop);
263 #endif
264 
265 #if KWINDOWSYSTEM_ENABLE_DEPRECATED_SINCE(5, 101)
266  /**
267  * Sets window @p win to be present on all virtual desktops if @p
268  * is true. Otherwise the window lives only on one single desktop.
269  *
270  * @param win the id of the window
271  * @param b true to show the window on all desktops, false
272  * otherwise
273  * @deprecated since 5.101, use KX11Extras::setOnAllDesktops()
274  */
275  KWINDOWSYSTEM_DEPRECATED_VERSION(5, 101, "Use KX11Extras::setOnAllDesktops() instead")
276  static void setOnAllDesktops(WId win, bool b);
277 #endif
278 
279 #if KWINDOWSYSTEM_ENABLE_DEPRECATED_SINCE(5, 101)
280  /**
281  * Moves window @p win to desktop @p desktop.
282  *
283  * @param win the id of the window
284  * @param desktop the number of the new desktop
285  * @deprecated since 5.101, use KX11Extras::setOnDesktop()
286  */
287  KWINDOWSYSTEM_DEPRECATED_VERSION(5, 101, "Use KX11Extras::setOnDesktop() instead")
288  static void setOnDesktop(WId win, int desktop);
289 #endif
290 
291 #if KWINDOWSYSTEM_ENABLE_DEPRECATED_SINCE(5, 101)
292  /**
293  * Moves window @p win to activities @p activities.
294  *
295  * @param win the id of the window
296  * @param activities the list of activity UUIDs
297  *
298  * @since 5.1
299  * @see KWindowInfo::activities
300  * @deprecated since 5.101, use KX11Extras::setOnActivities()
301  */
302  KWINDOWSYSTEM_DEPRECATED_VERSION(5, 101, "Use KX11Extras::setOnActivities() instead")
303  static void setOnActivities(WId win, const QStringList &activities);
304 #endif
305 
306  /**
307  * Sets the parent window of @p subwindow to be @p mainwindow.
308  * This overrides the parent set the usual way as the QWidget or QWindow parent,
309  * but only for the window manager - e.g. stacking order and window grouping
310  * will be affected, but features like automatic deletion of children
311  * when the parent is deleted are unaffected and normally use
312  * the QObject parent.
313  *
314  * This function should be used before a dialog is shown for a window
315  * that belongs to another application.
316  */
317  static void setMainWindow(QWindow *subwindow, WId mainwindow);
318 
319 #if KWINDOWSYSTEM_ENABLE_DEPRECATED_SINCE(5, 62)
320  /**
321  * Sets the parent window of @p subwindow to be @p mainwindow.
322  * This overrides the parent set the usual way as the QWidget parent,
323  * but only for the window manager - e.g. stacking order and window grouping
324  * will be affected, but features like automatic deletion of children
325  * when the parent is deleted are unaffected and normally use
326  * the QWidget parent.
327  *
328  * This function should be used before a dialog is shown for a window
329  * that belongs to another application.
330  * @deprecated since 5.62, use setMainWindow(QWindow *). If all you have is a QWidget*,
331  * you might need to call setAttribute(Qt::WA_NativeWindow, true); before calling
332  * >window()->windowHandle().
333  */
334  KWINDOWSYSTEM_DEPRECATED_VERSION(5, 62, "Use KWindowSystem::setMainWindow(QWindow *)")
335  static void setMainWindow(QWidget *subwindow, WId mainwindow);
336 #endif
337 
338 #if KWINDOWSYSTEM_ENABLE_DEPRECATED_SINCE(5, 0)
339  /**
340  * Returns the WM_TRANSIENT_FOR property for the given window, i.e. the mainwindow
341  * for this window.
342  *
343  * @param window the id of the window
344  * @deprecated Since 5.0, use KWindowInfo::transientFor
345  */
346  KWINDOWSYSTEM_DEPRECATED_VERSION(5, 0, "Use KWindowInfo::transientFor()")
347  static WId transientFor(WId window);
348 
349  /**
350  * Returns the leader window for the group the given window is in, if any.
351  * @param window the id of the window
352  * @deprecated Since 5.0, use KWindowInfo::groupLeader
353  */
354  KWINDOWSYSTEM_DEPRECATED_VERSION(5, 0, "Use KWindowInfo::groupLeader()")
355  static WId groupLeader(WId window);
356 #endif
357 
358 #if KWINDOWSYSTEM_ENABLE_DEPRECATED_SINCE(5, 101)
359  /**
360  * Returns an icon for window @p win.
361  *
362  * If @p width and @p height are specified, the best icon for the requested
363  * size is returned.
364  *
365  * If @p scale is true, the icon is smooth-scaled to have exactly
366  * the requested size.
367  *
368  * @param win the id of the window
369  * @param width the desired width, or -1
370  * @param height the desired height, or -1
371  * @param scale if true the icon will be scaled to the desired size. Otherwise the
372  * icon will not be modified.
373  * @return the icon of the window
374  * @deprecated since 5.101, use KX11Extras::icon()
375  */
376  KWINDOWSYSTEM_DEPRECATED_VERSION(5, 101, "Use KX11Extras::icon() instead")
377  static QPixmap icon(WId win, int width = -1, int height = -1, bool scale = false);
378 #endif
379 
380 #if KWINDOWSYSTEM_ENABLE_DEPRECATED_SINCE(5, 101)
381  /**
382  * Masks specifying from which sources to read an icon. They are tried from the best
383  * until an icon is found.
384  * @li NETWM from property from the window manager specification
385  * @li WMHints from WMHints property
386  * @li ClassHint load icon after getting name from the classhint
387  * @li XApp load the standard X icon (last fallback)
388  */
389  enum IconSource {
390  NETWM = 1, //!< read from property from the window manager specification
391  WMHints = 2, //!< read from WMHints property
392  ClassHint = 4, //!< load icon after getting name from the classhint
393  XApp = 8, //!< load the standard X icon (last fallback)
394  };
395 #endif
396 
397 #if KWINDOWSYSTEM_ENABLE_DEPRECATED_SINCE(5, 101)
398  /**
399  * @overload
400  *
401  * Overloaded variant that allows specifying from which sources the icon should be read.
402  * You should usually prefer the simpler variant which tries all possibilities to get
403  * an icon.
404  *
405  * @param win the id of the window
406  * @param width the desired width, or -1
407  * @param height the desired height, or -1
408  * @param scale if true the icon will be scaled to the desired size. Otherwise the
409  * icon will not be modified.
410  * @param flags OR-ed flags from the IconSource enum
411  * @deprecated since 5.101, use KX11Extras::icon()
412  */
413  KWINDOWSYSTEM_DEPRECATED_VERSION(5, 101, "Use KX11Extras::icon() instead")
414  static QPixmap icon(WId win, int width, int height, bool scale, int flags);
415 #endif
416 
417 #if KWINDOWSYSTEM_ENABLE_DEPRECATED_SINCE(5, 101)
418  /**
419  * @overload
420  *
421  * Overloaded variant that allows passing in the NETWinInfo to use for reading the
422  * information. This variant is only useful on the X11 platform, other platforms do not
423  * use NETWinInfo and delegate to the variant without NETWinInfo. Though if compiled with
424  * X11 support the X11 variant is used on other platforms if info is not @c nullptr.
425  * This can be used by applications using e.g. platform wayland but also connecting to an
426  * XServer.
427  *
428  * The NETWinInfo must be constructed with property NET::WMIcon in order to use the
429  * IconSource flag NETWM. NET::WM2IconPixmap for IconSource flag WMHints and
430  * NET::WM2WindowClass for IconSource flag ClassHint.
431  *
432  * @param win the id of the window
433  * @param width the desired width, or -1
434  * @param height the desired height, or -1
435  * @param scale if true the icon will be scaled to the desired size. Otherwise the
436  * icon will not be modified.
437  * @param flags OR-ed flags from the IconSource enum
438  * @param into the NETWinInfo to use for reading properties.
439  * @since 5.7
440  * @deprecated since 5.101, use KX11Extras::icon()
441  **/
442  KWINDOWSYSTEM_DEPRECATED_VERSION(5, 101, "Use KX11Extras::icon() instead")
443  static QPixmap icon(WId win, int width, int height, bool scale, int flags, NETWinInfo *info);
444 #endif
445 
446 #if KWINDOWSYSTEM_ENABLE_DEPRECATED_SINCE(5, 101)
447  /**
448  * Sets an @p icon and a @p miniIcon on window @p win
449  * @param win the id of the window
450  * @param icon the new icon
451  * @param miniIcon the new mini icon
452  * @deprecated since 5.101, use QWindow::setIcon() or QGuiApplication::setWindowIcon()
453  */
454  KWINDOWSYSTEM_DEPRECATED_VERSION(5, 101, "Use QWindow::setIcon() or QGuiApplication::setWindowIcon()")
455  static void setIcons(WId win, const QPixmap &icon, const QPixmap &miniIcon);
456 #endif
457 
458  /**
459  * Sets the type of window @p win to @p windowType.
460  *
461  * @param win the id of the window
462  * @param windowType the type of the window (see NET::WindowType)
463  */
464  static void setType(WId win, NET::WindowType windowType);
465  /**
466  * Sets the state of window @p win to @p state.
467  *
468  * Possible values are or'ed combinations of NET::Modal,
469  * NET::Sticky, NET::MaxVert, NET::MaxHoriz, NET::Shaded,
470  * NET::SkipTaskbar, NET::SkipPager, NET::Hidden,
471  * NET::FullScreen, NET::KeepAbove, NET::KeepBelow,
472  * NET::SkipSwitcher
473  *
474  * @param win the id of the window
475  * @param state the new flags that will be set
476  */
477  static void setState(WId win, NET::States state);
478 
479  /**
480  * Clears the state of window @p win from @p state.
481  *
482  * Possible values are or'ed combinations of NET::Modal,
483  * NET::Sticky, NET::MaxVert, NET::MaxHoriz, NET::Shaded,
484  * NET::SkipTaskbar, NET::SkipPager, NET::Hidden,
485  * NET::FullScreen, NET::KeepAbove, NET::KeepBelow,
486  * NET::SkipSwitcher
487  *
488  * @param win the id of the window
489  * @param state the flags that will be cleared
490  */
491  static void clearState(WId win, NET::States state);
492 
493 #if KWINDOWSYSTEM_ENABLE_DEPRECATED_SINCE(5, 101)
494  /**
495  * Minimizes the window with id @p win.
496  * On X11 this follows the protocol described in ICCCM section 4.1.4.
497  *
498  * @param win The window to minimize
499  * @see unminimizeWindow()
500  * @deprecated since 5.101, use KX11Extras::minimizeWindow() or QWindow::setState()
501  */
502  KWINDOWSYSTEM_DEPRECATED_VERSION(5, 101, "Use KX11Extras::minimizeWindow() or QWindow::setState() instead")
503  static void minimizeWindow(WId win);
504 #endif
505 
506 #if KWINDOWSYSTEM_ENABLE_DEPRECATED_SINCE(5, 101)
507  /**
508  * Unminimizes the window with id @p win.
509  * On X11 this follows the protocol described in ICCCM section 4.1.4.
510  *
511  * @param win The window to unminimize
512  * @see minimizeWindow()
513  * @deprecated since 5.101, use KX11Extras::unminimizeWindow() or QWindow::setState()
514  **/
515  KWINDOWSYSTEM_DEPRECATED_VERSION(5, 101, "Use KX11Extras::unminimizeWindow() or QWindow::setState() instead")
516  static void unminimizeWindow(WId win);
517 #endif
518 
519 #if KWINDOWSYSTEM_ENABLE_DEPRECATED_SINCE(5, 0)
520  /**
521  * @deprecated since 5.0 the @p animation is ignored.
522  */
523  KWINDOWSYSTEM_DEPRECATED_VERSION(5, 0, "Use KWindowSystem::minimizeWindow(WId)")
524  static void minimizeWindow(WId win, bool animation);
525 #endif
526 
527 #if KWINDOWSYSTEM_ENABLE_DEPRECATED_SINCE(5, 0)
528  /**
529  * @deprecated since 5.0 the @p animation is ignored.
530  */
531  KWINDOWSYSTEM_DEPRECATED_VERSION(5, 0, "Use KWindowSystem::unminimizeWindow(WId)")
532  static void unminimizeWindow(WId win, bool animation);
533 #endif
534 
535  /**
536  * Raises the given window. This call is only for pagers and similar
537  * tools that represent direct user actions. Applications should not
538  * use it, they should keep using QWidget::raise() or XRaiseWindow()
539  * if necessary.
540  */
541  static void raiseWindow(WId win);
542 
543 #if KWINDOWSYSTEM_ENABLE_DEPRECATED_SINCE(5, 101)
544  /**
545  * Lowers the given window. This call is only for pagers and similar
546  * tools that represent direct user actions. Applications should not
547  * use it, they should keep using QWidget::lower() or XLowerWindow()
548  * if necessary.
549  *
550  * @deprecated since 5.101, no known users.
551  */
552  KWINDOWSYSTEM_DEPRECATED_VERSION(5, 101, "No known users.")
553  static void lowerWindow(WId win);
554 #endif
555 
556 #if KWINDOWSYSTEM_ENABLE_DEPRECATED_SINCE(5, 101)
557  /**
558  * @internal
559  * Returns true if the WM uses IconicState also for windows
560  * on inactive virtual desktops.
561  *
562  * @deprecated since 5.101, internal.
563  */
564  KWINDOWSYSTEM_DEPRECATED_VERSION(5, 101, "Internal")
565  static bool icccmCompliantMappingState();
566 #endif
567 
568 #if KWINDOWSYSTEM_ENABLE_DEPRECATED_SINCE(5, 101)
569  /**
570  * Returns the workarea for the specified desktop, or the current
571  * work area if no desktop has been specified.
572  * @param desktop the number of the desktop to check, -1 for the
573  * current desktop
574  * @return the size and position of the desktop
575  * @deprecated since 5.101, use KX11Extras::workArea()
576  **/
577  KWINDOWSYSTEM_DEPRECATED_VERSION(5, 101, "Use KX11Extras::workArea() instead")
578  static QRect workArea(int desktop = -1);
579 #endif
580 
581 #if KWINDOWSYSTEM_ENABLE_DEPRECATED_SINCE(5, 101)
582  /**
583  * Returns the workarea for the specified desktop, or the current
584  * work area if no desktop has been specified. Excludes struts of
585  * clients in the exclude List.
586  *
587  * @param excludes the list of clients whose struts will be excluded
588  * @param desktop the number of the desktop to check, -1 for the
589  * current desktop
590  * @return the size and position of the desktop
591  * @deprecated since 5.101, use KX11Extras::workArea()
592  **/
593  KWINDOWSYSTEM_DEPRECATED_VERSION(5, 101, "Use KX11Extras::workArea() instead")
594  static QRect workArea(const QList<WId> &excludes, int desktop = -1);
595 #endif
596 
597 #if KWINDOWSYSTEM_ENABLE_DEPRECATED_SINCE(5, 101)
598  /**
599  * Returns the name of the specified desktop.
600  * @param desktop the number of the desktop
601  * @return the name of the desktop
602  * @deprecated since 5.101, use KX11Extras::desktopName()
603  **/
604  KWINDOWSYSTEM_DEPRECATED_VERSION(5, 101, "Use KX11Extras::desktopName() instead")
605  static QString desktopName(int desktop);
606 #endif
607 
608 #if KWINDOWSYSTEM_ENABLE_DEPRECATED_SINCE(5, 101)
609  /**
610  * Sets the name of the specified desktop.
611  * @param desktop the number of the desktop
612  * @param name the new name for the desktop
613  * @deprecated since 5.101, use KX11Extras::setDesktopName()
614  **/
615  KWINDOWSYSTEM_DEPRECATED_VERSION(5, 101, "Use KX11Extras::setDesktopName() instead")
616  static void setDesktopName(int desktop, const QString &name);
617 #endif
618 
619  /**
620  * Returns the state of showing the desktop.
621  */
622  static bool showingDesktop();
623 
624  /**
625  * Sets the state of the "showing desktop" mode of the window manager. If on,
626  * windows are hidden and desktop background is shown and focused.
627  *
628  * @param showing if true, the window manager is put in "showing desktop" mode.
629  * If false, the window manager is put out of that mode.
630  *
631  * @since 5.7.0
632  */
633  static void setShowingDesktop(bool showing);
634 
635 #if KWINDOWSYSTEM_ENABLE_DEPRECATED_SINCE(5, 101)
636  /**
637  * Sets user timestamp @p time on window @p win. The timestamp
638  * is expressed as XServer time. If a window
639  * is shown with user timestamp older than the time of the last
640  * user action, it won't be activated after being shown.
641  * The most common case is the special value 0 which means
642  * not to activate the window after being shown.
643  *
644  * @deprecated since 5.101, use QX11Info::setAppUserTime().
645  */
646  KWINDOWSYSTEM_DEPRECATED_VERSION(5, 101, "Use QX11Info::setAppUserTime()")
647  static void setUserTime(WId win, long time);
648 #endif
649 
650 #if KWINDOWSYSTEM_ENABLE_DEPRECATED_SINCE(5, 101)
651  /**
652  * Sets the strut of window @p win to @p left_width
653  * ranging from @p left_start to @p left_end on the left edge,
654  * and simiarly for the other edges. For not reserving a strut, pass 0 as the width.
655  * E.g. to reserve 10x10 square in the topleft corner, use e.g.
656  * setExtendedStrut( w, 10, 0, 10, 0, 0, 0, 0, 0, 0, 0, 0, 0 ).
657  *
658  * @param win the id of the window
659  * @param left_width width of the strut at the left edge
660  * @param left_start starting y coordinate of the strut at the left edge
661  * @param left_end ending y coordinate of the strut at the left edge
662  * @param right_width width of the strut at the right edge
663  * @param right_start starting y coordinate of the strut at the right edge
664  * @param right_end ending y coordinate of the strut at the right edge
665  * @param top_width width of the strut at the top edge
666  * @param top_start starting x coordinate of the strut at the top edge
667  * @param top_end ending x coordinate of the strut at the top edge
668  * @param bottom_width width of the strut at the bottom edge
669  * @param bottom_start starting x coordinate of the strut at the bottom edge
670  * @param bottom_end ending x coordinate of the strut at the bottom edge
671  */
672  KWINDOWSYSTEM_DEPRECATED_VERSION(5, 101, "Use KX11Extras::setExtendedStrut() instead. In KF6 all arguments must be in the logical coordinates.")
673  static void setExtendedStrut(WId win,
674  int left_width,
675  int left_start,
676  int left_end,
677  int right_width,
678  int right_start,
679  int right_end,
680  int top_width,
681  int top_start,
682  int top_end,
683  int bottom_width,
684  int bottom_start,
685  int bottom_end);
686 #endif
687 
688 #if KWINDOWSYSTEM_ENABLE_DEPRECATED_SINCE(5, 101)
689  /**
690  * Convenience function for setExtendedStrut() that automatically makes struts
691  * as wide/high as the screen width/height.
692  * Sets the strut of window @p win to @p left, @p right, @p top, @p bottom.
693  *
694  * @param win the id of the window
695  * @param left the left strut
696  * @param right the right strut
697  * @param top the top strut
698  * @param bottom the bottom strut
699  */
700  KWINDOWSYSTEM_DEPRECATED_VERSION(5, 101, "Use KX11Extras::setStrut() instead. In KF6 all arguments must be in the logical coordinates.")
701  static void setStrut(WId win, int left, int right, int top, int bottom);
702 #endif
703 
704  /**
705  * Returns true if the WM announces which actions it allows for windows.
706  */
707  static bool allowedActionsSupported();
708 
709 #if KWINDOWSYSTEM_ENABLE_DEPRECATED_SINCE(5, 101)
710  /**
711  * Function that reads and returns the contents of the given text
712  * property (WM_NAME, WM_ICON_NAME,...).
713  */
714  KWINDOWSYSTEM_DEPRECATED_VERSION(5, 101, "Use KX11Extras::readNameProperty() instead")
715  static QString readNameProperty(WId window, unsigned long atom);
716 #endif
717 
718 #if KWINDOWSYSTEM_ENABLE_DEPRECATED_SINCE(5, 104)
719  /**
720  * Allows a window from another process to raise and activate itself.
721  * Depending on the window manager, the grant may only be temporary,
722  * or for a single activation, and it may require the current process
723  * to be the "foreground" one" (ie. the process with the input focus).
724  *
725  * You should call this function before executing actions that may trigger
726  * the showing of a window or dialog in another process, e.g. a dbus signal
727  * or function call, or any other inter-process notification mechanism.
728  *
729  * This is mostly used on Windows, where windows are not allowed to be raised
730  * and activated if their process is not the foreground one, but it may also
731  * apply to other window managers.
732  *
733  * @param pid if specified, the grant only applies to windows belonging to the
734  * specific process. By default, a value of -1 means all processes.
735  *
736  * @deprecated since 5.104, not implemented.
737  */
738  KWINDOWSYSTEM_DEPRECATED_VERSION(5, 104, "Not implemented")
739  static void allowExternalProcessWindowActivation(int pid = -1);
740 #endif
741 
742 #if KWINDOWSYSTEM_ENABLE_DEPRECATED_SINCE(5, 101)
743  /**
744  * Sets whether the client wishes to block compositing (for better performance)
745  * @since 4.7
746  * @deprecated since 5.101, no known users.
747  */
748  KWINDOWSYSTEM_DEPRECATED_VERSION(5, 101, "No known users")
749  static void setBlockingCompositing(WId window, bool active);
750 #endif
751 
752 #if KWINDOWSYSTEM_ENABLE_DEPRECATED_SINCE(5, 101)
753  /**
754  * @internal
755  * Returns true if viewports are mapped to virtual desktops.
756  */
757  static bool mapViewport();
758 #endif
759 
760  /**
761  * @internal
762  * Returns mapped virtual desktop for the given position in the viewport.
763  */
764  static int viewportToDesktop(const QPoint &pos);
765  /**
766  * @internal
767  * Returns mapped virtual desktop for the given window geometry.
768  */
769  static int viewportWindowToDesktop(const QRect &r);
770  /**
771  * @internal
772  * Returns topleft corner of the viewport area for the given mapped virtual desktop.
773  */
774  static QPoint desktopToViewport(int desktop, bool absolute);
775 
776 #if KWINDOWSYSTEM_ENABLE_DEPRECATED_SINCE(5, 101)
777  /**
778  * @internal
779  * @since 4.0.1
780  * Checks the relative difference used to move a window will still be inside
781  * valid desktop area.
782  */
783  KWINDOWSYSTEM_DEPRECATED_VERSION(5, 101, "No known users")
784  static QPoint constrainViewportRelativePosition(const QPoint &pos);
785 #endif
786 
787  /**
788  * Updates the platform-specific startup id, if any.
789  *
790  * This method is to be called when a running application instance
791  * is reused for handling the request to start this application.
792  * A typical use would be in the handler of the KDBusService activation signal.
793  *
794  * For X11, this updates the id for the Startup Notification protocol,
795  * taking the id from QX11Info::nextStartupId(), if not empty.
796  * For Wayland, this updates the token for the XDG Activation protocol,
797  * taking the token from the "XDG_ACTIVATION_TOKEN" environment variable
798  * and then unsetting it, if not empty.
799  *
800  * @param window the main window (needed by X11 platform)
801  *
802  * @since 5.91
803  */
804  static void updateStartupId(QWindow *window);
805 
806  /**
807  * Enum describing the windowing system platform used by the QGuiApplication.
808  * @see platform
809  * @since 5.25
810  **/
811  enum class Platform {
812  /**
813  * A platform unknown to the application is used
814  **/
815  Unknown,
816  /**
817  * The xcb/X11 windowing system platorm.
818  **/
819  X11,
820  /**
821  * The Wayland windowing system platform.
822  **/
823  Wayland,
824  };
825  Q_ENUM(Platform)
826  /**
827  * Returns the Platform used by the QGuiApplication.
828  * This method allows to check for the used windowing system in a cheap and reliable way.
829  * The Platform gets resolved the first time the method is invoked and cached for further
830  * usages.
831  * @returns The Platform used by the QGuiApplication.
832  * @since 5.25
833  **/
834  static Platform platform();
835 
836  /**
837  * Convenience method to check whether the Platform is X11.
838  * @see platform
839  * @see isPlatformWayland
840  * @since 5.25
841  **/
842  static bool isPlatformX11();
843 
844  /**
845  * Convenience method to check whether the Platform is Wayland.
846  * @see platform
847  * @see isPlatformX11
848  * @since 5.25
849  **/
850  static bool isPlatformWayland();
851 
852  /**
853  * Requests an xdg_activation_v1 token for a specific window.
854  *
855  * @param win window in behalf this request is made
856  * @param serial of the event that triggered the request
857  * @param app_id identifier of the application that we are launching
858  *
859  * @see lastInputSerial
860  * @since 5.83
861  */
862  Q_INVOKABLE static void requestXdgActivationToken(QWindow *win, uint32_t serial, const QString &app_id);
863 
864  /**
865  * Sets the @p token that will be used when activateWindow is called next
866  *
867  * @since 5.83
868  */
869  Q_INVOKABLE static void setCurrentXdgActivationToken(const QString &token);
870 
871  /**
872  * Offers the seat's current serial
873  *
874  * This will mostly be useful on wayland sessions.
875  *
876  * @since 5.83
877  */
878  Q_INVOKABLE static quint32 lastInputSerial(QWindow *window);
879 
880 Q_SIGNALS:
881 
882 #if KWINDOWSYSTEM_ENABLE_DEPRECATED_SINCE(5, 101)
883  /**
884  * Switched to another virtual desktop.
885  * @param desktop the number of the new desktop
886  * @deprecated since 5.101, use KX11Extras::currentDesktopChanged()
887  */
888  KWINDOWSYSTEM_DEPRECATED_VERSION(5, 101, "Use KX11Extras::currentDesktopChanged()")
889  void currentDesktopChanged(int desktop);
890 #endif
891 
892 #if KWINDOWSYSTEM_ENABLE_DEPRECATED_SINCE(5, 101)
893  /**
894  * A window has been added.
895  * @param id the id of the window
896  * @deprecated since 5.101, use KX11Extras::windowAdded()
897  */
898  KWINDOWSYSTEM_DEPRECATED_VERSION(5, 101, "Use KX11Extras::windowAdded()")
899  void windowAdded(WId id);
900 #endif
901 
902 #if KWINDOWSYSTEM_ENABLE_DEPRECATED_SINCE(5, 101)
903  /**
904  * A window has been removed.
905  * @param id the id of the window that has been removed
906  * @deprecated since 5.101, use KX11Extras::windowRemoved()
907  */
908  KWINDOWSYSTEM_DEPRECATED_VERSION(5, 101, "Use KX11Extras::windowRemoved()")
909  void windowRemoved(WId id);
910 #endif
911 
912 #if KWINDOWSYSTEM_ENABLE_DEPRECATED_SINCE(5, 101)
913  /**
914  * Hint that <Window> is active (= has focus) now.
915  * @param id the id of the window that is active
916  * @deprecated since 5.101, use KX11Extras::activeWindowChanged()
917  */
918  KWINDOWSYSTEM_DEPRECATED_VERSION(5, 101, "Use KX11Extras::activeWindowChanged()")
919  void activeWindowChanged(WId id);
920 #endif
921 
922 #if KWINDOWSYSTEM_ENABLE_DEPRECATED_SINCE(5, 101)
923  /**
924  * Desktops have been renamed.
925  * @deprecated since 5.101, use KX11Extras::desktopNamesChanged()
926  */
927  KWINDOWSYSTEM_DEPRECATED_VERSION(5, 101, "Use KX11Extras::desktopNamesChanged()")
928  void desktopNamesChanged();
929 #endif
930 
931 #if KWINDOWSYSTEM_ENABLE_DEPRECATED_SINCE(5, 101)
932  /**
933  * The number of desktops changed.
934  * @param num the new number of desktops
935  * @deprecated since 5.101, use KX11Extras::numberOfDesktopsChanged()
936  */
937  KWINDOWSYSTEM_DEPRECATED_VERSION(5, 101, "Use KX11Extras::numberOfDesktopsChanged()")
938  void numberOfDesktopsChanged(int num);
939 #endif
940 
941 #if KWINDOWSYSTEM_ENABLE_DEPRECATED_SINCE(5, 101)
942  /**
943  * The workarea has changed.
944  * @deprecated since 5.101, use KX11Extras::workAreaChanged()
945  */
946  KWINDOWSYSTEM_DEPRECATED_VERSION(5, 101, "Use KX11Extras::workAreaChanged()")
947  void workAreaChanged();
948 #endif
949 
950 #if KWINDOWSYSTEM_ENABLE_DEPRECATED_SINCE(5, 101)
951  /**
952  * Something changed with the struts, may or may not have changed
953  * the work area. Usually just using the workAreaChanged() signal
954  * is sufficient.
955  * @deprecated since 5.101, use KX11Extras::strutChanged()
956  */
957  KWINDOWSYSTEM_DEPRECATED_VERSION(5, 101, "Use KX11Extras::strutChanged()")
958  void strutChanged();
959 #endif
960 
961 #if KWINDOWSYSTEM_ENABLE_DEPRECATED_SINCE(5, 101)
962  /**
963  * Emitted when the stacking order of the window changed. The new order
964  * can be obtained with stackingOrder().
965  * @deprecated since 5.101, use KX11Extras::stackingOrderChanged()
966  */
967  KWINDOWSYSTEM_DEPRECATED_VERSION(5, 101, "Use KX11Extras::stackingOrderChanged()")
968  void stackingOrderChanged();
969 #endif
970 
971 #if KWINDOWSYSTEM_ENABLE_DEPRECATED_SINCE(5, 101)
972  /**
973  * The window changed.
974  *
975  * Carries the NET::Properties and NET::Properties2 that were changed.
976  *
977  * @param id the id of the window
978  * @param properties the properties that were modified
979  * @param properties2 the properties2 that were modified
980  *
981  * @since 5.0
982  * @deprecated since 5.101, use KX11Extras::windowChanged()
983  */
984  KWINDOWSYSTEM_DEPRECATED_VERSION(5, 101, "Use KX11Extras::windowChanged")
985  void windowChanged(WId id, NET::Properties properties, NET::Properties2 properties2); // clazy:exclude=overloaded-signal
986 #endif
987 
988 #if KWINDOWSYSTEM_ENABLE_DEPRECATED_SINCE(5, 0)
989  /**
990  * The window changed.
991  *
992  * The properties parameter contains the NET properties that
993  * were modified (see netwm_def.h). First element are NET::Property
994  * values, second element are NET::Property2 values (i.e. the format
995  * is the same like for the NETWinInfo class constructor).
996  * @param id the id of the window
997  * @param properties the properties that were modified
998  *
999  * @deprecated since 5.0 use windowChanged(WId, NET::Properties, NET::Properties2)
1000  */
1001  KWINDOWSYSTEM_DEPRECATED_VERSION(5, 0, "Use KWindowSystem::windowChanged(WId, NET::Properties, NET::Properties2)")
1002  QT_MOC_COMPAT void windowChanged(WId id, const unsigned long *properties); // clazy:exclude=overloaded-signal
1003 #endif
1004 
1005 #if KWINDOWSYSTEM_ENABLE_DEPRECATED_SINCE(5, 0)
1006  /**
1007  * The window changed.
1008  *
1009  * The unsigned int parameter contains the NET properties that
1010  * were modified (see netwm_def.h).
1011  * @param id the id of the window
1012  * @param properties the properties that were modified
1013  * @deprecated Since 5.0
1014  */
1015  KWINDOWSYSTEM_DEPRECATED_VERSION(5, 0, "Use KWindowSystem::windowChanged(WId, NET::Properties, NET::Properties2)")
1016  QT_MOC_COMPAT void windowChanged(WId id, unsigned int properties); // clazy:exclude=overloaded-signal
1017 #endif
1018 
1019 #if KWINDOWSYSTEM_ENABLE_DEPRECATED_SINCE(5, 80)
1020  /**
1021  * The window changed somehow.
1022  * @param id the id of the window
1023  *
1024  * @deprecated since 5.80, use windowChanged(WId, NET::Properties, NET::Properties2);
1025  **/
1026  KWINDOWSYSTEM_DEPRECATED_VERSION(5, 80, "Use KWindowSystem::windowChanged(WId, NET::Properties, NET::Properties2)")
1027  void windowChanged(WId id); // clazy:exclude=overloaded-signal
1028 #endif
1029 
1030  /**
1031  * The state of showing the desktop has changed.
1032  */
1033  void showingDesktopChanged(bool showing);
1034 
1035 #if KWINDOWSYSTEM_ENABLE_DEPRECATED_SINCE(5, 101)
1036  /**
1037  * Compositing was enabled or disabled.
1038  *
1039  * Note that this signal may be emitted before any compositing plugins
1040  * have been initialized in the window manager.
1041  *
1042  * If you need to check if a specific compositing plugin such as the
1043  * blur effect is enabled, you should track that separately rather
1044  * than test for it in a slot connected to this signal.
1045  *
1046  * @since 4.7.1
1047  * @deprecated since 5.101, use KX11Extras::compositingChanged()
1048  */
1049  KWINDOWSYSTEM_DEPRECATED_VERSION(5, 101, "Use KX11Extras::compositingChanged()")
1050  void compositingChanged(bool enabled);
1051 #endif
1052 
1053  /**
1054  * Activation @p token to pass to the client.
1055  *
1056  * @see requestXdgActivationToken
1057  * @see setCurrentXdgActivationToken
1058  * @since 5.83
1059  */
1060  void xdgActivationTokenArrived(int serial, const QString &token);
1061 
1062 protected:
1063  void connectNotify(const QMetaMethod &signal) override;
1064 
1065 private:
1066  friend class KWindowSystemStaticContainer;
1067  friend class KX11Extras;
1068 
1069  KWindowSystem()
1070  {
1071  }
1072  static KWindowSystemPrivate *d_func();
1073 };
1074 
1075 #endif
Platform
Enum describing the windowing system platform used by the QGuiApplication.
Q_PROPERTY(...)
A collection of functions to obtain information from and manipulate X11 windows.
Definition: kx11extras.h:27
Q_ENUM(...)
This class provides information about a given window in the platform specific windowing system.
Definition: kwindowinfo.h:62
IconSource
Masks specifying from which sources to read an icon.
Q_SIGNALSQ_SIGNALS
Convenience access to certain properties and features of the window manager.
Definition: kwindowsystem.h:44
Common API for application window properties/protocols.
Definition: netwm.h:974
Base namespace class.
Definition: netwm_def.h:334
virtual void connectNotify(const QMetaMethod &signal)
WindowType
Window type.
Definition: netwm_def.h:357
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Sun Dec 3 2023 04:14:01 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.