1/* This file is part of the KDE libraries
2 Copyright (C) 1999 Matthias Ettrich (ettrich@kde.org)
3 Copyright (C) 2007 Lubos Lunak (l.lunak@kde.org)
4
5 This library is free software; you can redistribute it and/or
6 modify it under the terms of the GNU Library General Public
7 License as published by the Free Software Foundation; either
8 version 2 of the License, or (at your option) any later version.
9
10 This library is distributed in the hope that it will be useful,
11 but WITHOUT ANY WARRANTY; without even the implied warranty of
12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 Library General Public License for more details.
14
15 You should have received a copy of the GNU Library General Public License
16 along with this library; see the file COPYING.LIB. If not, write to
17 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
18 Boston, MA 02110-1301, USA.
19*/
20/*
21 * kwindowsystem.h. Part of the KDE project.
22 */
23
24#ifndef KWINDOWSYSTEM_H
25#define KWINDOWSYSTEM_H
26
27#include <kdeui_export.h>
28#include <QtCore/QObject>
29#include <QtGui/QWidgetList> //For WId
30#include <netwm_def.h>
31#include <kwindowinfo.h>
32
33class KWindowSystemPrivate;
34
35/**
36 *
37 * Convenience access to certain properties and features of the
38 * window manager.
39 *
40 * The class KWindowSystem provides information about the state of the
41 * window manager and allows asking the window manager to change them
42 * using a more high-level interface than the NETWinInfo/NETRootInfo
43 * lowlevel classes.
44 *
45 * Because of limitiations of the way Qt is implemented on Mac OSX, the WId's
46 * returned by methods in this class are not compatible with those expected
47 * by other Qt methods. So while it should be fine to pass WId's retrieved by
48 * for example calling the winId method on a QWidget to methods in this class
49 * the reverse is not true. You should never pass a WId obtained from this class
50 * to a Qt method accepting a WId parameter.
51 *
52 * @short Class for interaction with the window manager.
53 * @author Matthias Ettrich (ettrich@kde.org)
54 */
55class KDEUI_EXPORT KWindowSystem : public QObject, public NET
56{
57 Q_OBJECT
58
59public:
60 /**
61 * Access to the singleton instance. Useful mainly for connecting to signals.
62 */
63 static KWindowSystem* self();
64
65 /**
66 * Returns the list of all toplevel windows currently managed by the
67 * window manager in the order of creation. Please do not rely on
68 * indexes of this list: Whenever you enter Qt's event loop in your
69 * application, it may happen that entries are removed or added.
70 * Your module should perhaps work on a copy of this list and verify a
71 * window with hasWId() before any operations.
72 *
73 * Iteration over this list can be done easily with
74 * \code
75 * QList<WId>::ConstIterator it;
76 * for ( it = KWindowSystem::windows().begin();
77 * it != KWindowSystem::windows().end(); ++it ) {
78 * ... do something here, (*it) is the current WId.
79 * }
80 * \endcode
81 * @return the list of all toplevel windows
82 */
83 static const QList<WId>& windows();
84
85 /**
86 * Test to see if @p id still managed at present.
87 * @param id the window id to test
88 * @return true if the window id is still managed
89 **/
90 static bool hasWId(WId id);
91
92 /**
93 * Returns information about window @p win. It is recommended to check
94 * whether the returned info is valid by calling the valid() method.
95 * @param win the id of the window
96 * @param properties all properties that should be retrieved (see NET::Property
97 * enum for details). Unlisted properties cause related information to be invalid
98 * in the returned data, but make this function faster when not all data is needed.
99 * @param properties2 additional properties (see NET::Property2 enum)
100 * @return the window information
101 */
102 static KWindowInfo windowInfo( WId win, unsigned long properties, unsigned long properties2 = 0 );
103
104 /**
105 * Returns the list of all toplevel windows currently managed by the
106 * window manager in the current stacking order (from lower to
107 * higher). May be useful for pagers.
108 * @return the list of all toplevel windows in stacking order
109 */
110 static QList<WId> stackingOrder();
111
112 /**
113 * Returns the currently active window, or 0 if no window is active.
114 * @return the window id of the active window, or 0 if no window is
115 * active
116 **/
117 static WId activeWindow();
118
119 /**
120 * Requests that window @p win is activated.
121 *
122 * There are two ways how to activate a window, by calling
123 * activateWindow() and forceActiveWindow(). Generally,
124 * applications shouldn't make attempts to explicitly activate
125 * their windows, and instead let the user to activate them.
126 * In the special cases where this may be needed, applications
127 * should use activateWindow(). Window manager may consider whether
128 * this request wouldn't result in focus stealing, which
129 * would be obtrusive, and may refuse the request.
130 *
131 * The usage of forceActiveWindow() is meant only for pagers
132 * and similar tools, which represent direct user actions
133 * related to window manipulation.
134 * Except for rare cases, this request will be always honored,
135 * and normal applications are forbidden to use it.
136 *
137 * In case of problems, consult the KWin README in the kdebase
138 * package (kdebase/kwin/README), or ask on the kwin@kde.org
139 * mailing list.
140 *
141 * @param win the id of the window to make active
142 * @param time X server timestamp of the user activity that
143 * caused this request
144 */
145 static void activateWindow( WId win, long time = 0 );
146
147 /**
148 * Sets window @p win to be the active window. Note that this
149 * should be called only in special cases, applications
150 * shouldn't force themselves or other windows to be the active
151 * window. Generally, this call should used only by pagers
152 * and similar tools. See the explanation in description
153 * of activateWindow().
154 *
155 * @param win the id of the window to make active
156 * @param time X server timestamp of the user activity that
157 * caused this request
158 */
159 static void forceActiveWindow( WId win, long time = 0 );
160
161 /**
162 * When application finishes some operation and wants to notify
163 * the user about it, it can call demandAttention(). Instead
164 * of activating the window, which could be obtrusive, the window
165 * will be marked specially as demanding user's attention.
166 * See also explanation in description of activateWindow().
167 *
168 * Note that it's usually better to use KNotifyClient.
169 */
170 static void demandAttention( WId win, bool set = true );
171
172 /**
173 * Returns true if a compositing manager is running (i.e. ARGB windows
174 * are supported, effects will be provided, etc.).
175 */
176 static bool compositingActive();
177
178 /**
179 * Returns the current virtual desktop.
180 * @return the current virtual desktop
181 **/
182 static int currentDesktop();
183
184 /**
185 * Returns the number of virtual desktops.
186 * @return the number of virtual desktops
187 **/
188 static int numberOfDesktops();
189
190 /**
191 * Convenience function to set the current desktop to @p desktop.
192 * See NETRootInfo.
193 * @param desktop the number of the new desktop
194 */
195 static void setCurrentDesktop( int desktop );
196
197 /**
198 * Sets window @p win to be present on all virtual desktops if @p
199 * is true. Otherwise the window lives only on one single desktop.
200 *
201 * @param win the id of the window
202 * @param b true to show the window on all desktops, false
203 * otherwise
204 */
205 static void setOnAllDesktops( WId win, bool b );
206
207 /**
208 * Moves window @p win to desktop @p desktop.
209 *
210 * @param win the id of the window
211 * @param desktop the number of the new desktop
212 */
213 static void setOnDesktop( WId win, int desktop);
214
215 /**
216 * Sets the parent window of @p subwindow to be @p mainwindow.
217 * This overrides the parent set the usual way as the QWidget parent,
218 * but only for the window manager - e.g. stacking order and window grouping
219 * will be affected, but features like automatic deletion of children
220 * when the parent is deleted are unaffected and normally use
221 * the QWidget parent.
222 *
223 * This function should be used before a dialog is shown for a window
224 * that belongs to another application.
225 */
226 static void setMainWindow( QWidget* subwindow, WId mainwindow );
227#ifdef Q_WS_X11
228 /**
229 * Returns the WM_TRANSIENT_FOR property for the given window, i.e. the mainwindow
230 * for this window.
231 *
232 * @param window the id of the window
233 */
234 static WId transientFor( WId window );
235
236 /**
237 * Returns the leader window for the group the given window is in, if any.
238 * @param window the id of the window
239 */
240 static WId groupLeader( WId window );
241#endif
242 /**
243 * Returns an icon for window @p win.
244 *
245 * If @p width and @p height are specified, the best icon for the requested
246 * size is returned.
247 *
248 * If @p scale is true, the icon is smooth-scaled to have exactly
249 * the requested size.
250 *
251 * @param win the id of the window
252 * @param width the desired width, or -1
253 * @param height the desired height, or -1
254 * @param scale if true the icon will be scaled to the desired size. Otherwise the
255 * icon will not be modified.
256 * @return the icon of the window
257 */
258 static QPixmap icon( WId win, int width = -1, int height = -1, bool scale = false );
259
260 /**
261 * Masks specifying from which sources to read an icon. They are tried from the best
262 * until an icon is found.
263 * @li NETWM from property from the window manager specification
264 * @li WMHints from WMHints property
265 * @li ClassHint load icon after getting name from the classhint
266 * @li XApp load the standard X icon (last fallback)
267 */
268 enum IconSource { NETWM = 1, //!< read from property from the window manager specification
269 WMHints = 2, //!< read from WMHints property
270 ClassHint = 4, //!< load icon after getting name from the classhint
271 XApp = 8 //!<load the standard X icon (last fallback)
272 };
273 /**
274 * @overload
275 *
276 * Overloaded variant that allows specifying from which sources the icon should be read.
277 * You should usually prefer the simpler variant which tries all possibilities to get
278 * an icon.
279 *
280 * @param win the id of the window
281 * @param width the desired width, or -1
282 * @param height the desired height, or -1
283 * @param scale if true the icon will be scaled to the desired size. Otherwise the
284 * icon will not be modified.
285 * @param flags OR-ed flags from the IconSource enum
286 */
287 static QPixmap icon( WId win, int width, int height, bool scale, int flags );
288
289 /**
290 * Sets an @p icon and a @p miniIcon on window @p win
291 * @param win the id of the window
292 * @param icon the new icon
293 * @param miniIcon the new mini icon
294 */
295 static void setIcons( WId win, const QPixmap& icon, const QPixmap& miniIcon );
296 /**
297 * Sets the type of window @p win to @p windowType.
298 *
299 * @param win the id of the window
300 * @param windowType the type of the window (see NET::WindowType)
301 */
302 static void setType( WId win, NET::WindowType windowType );
303 /**
304 * Sets the state of window @p win to @p state.
305 *
306 * Possible values are or'ed combinations of NET::Modal,
307 * NET::Sticky, NET::MaxVert, NET::MaxHoriz, NET::Shaded,
308 * NET::SkipTaskbar, NET::SkipPager, NET::Hidden,
309 * NET::FullScreen, NET::KeepAbove, NET::KeepBelow, NET::StaysOnTop
310 *
311 * @param win the id of the window
312 * @param state the new flags that will be set
313 */
314 static void setState( WId win, unsigned long state );
315
316 /**
317 * Clears the state of window @p win from @p state.
318 *
319 * Possible values are or'ed combinations of NET::Modal,
320 * NET::Sticky, NET::MaxVert, NET::MaxHoriz, NET::Shaded,
321 * NET::SkipTaskbar, NET::SkipPager, NET::Hidden,
322 * NET::FullScreen, NET::KeepAbove, NET::KeepBelow, NET::StaysOnTop
323 *
324 * @param win the id of the window
325 * @param state the flags that will be cleared
326 */
327 static void clearState( WId win, unsigned long state );
328
329 /**
330 * Iconifies a window. Compatible to XIconifyWindow but has an
331 * additional parameter @p animation.
332 *
333 * @param win the id of the window
334 * @param animation true to show an animation
335 * @see deIconifyWindow()
336 */
337 static void minimizeWindow( WId win, bool animation = true );
338
339 /**
340 * DeIconifies a window. Compatible to XMapWindow but has an
341 * additional parameter @p animation.
342 *
343 * @param win the id of the window
344 * @param animation true to show an animation
345 * @see iconifyWindow()
346 */
347 static void unminimizeWindow( WId win, bool animation = true );
348
349 /**
350 * Raises the given window. This call is only for pagers and similar
351 * tools that represent direct user actions. Applications should not
352 * use it, they should keep using QWidget::raise() or XRaiseWindow()
353 * if necessary.
354 */
355 static void raiseWindow( WId win );
356
357 /**
358 * Lowers the given window. This call is only for pagers and similar
359 * tools that represent direct user actions. Applications should not
360 * use it, they should keep using QWidget::lower() or XLowerWindow()
361 * if necessary.
362 */
363 static void lowerWindow( WId win );
364
365 /**
366 * @internal
367 * Returns true if the WM uses IconicState also for windows
368 * on inactive virtual desktops.
369 */
370 static bool icccmCompliantMappingState();
371
372 /**
373 * Returns the workarea for the specified desktop, or the current
374 * work area if no desktop has been specified.
375 * @param desktop the number of the desktop to check, -1 for the
376 * current desktop
377 * @return the size and position of the desktop
378 **/
379 static QRect workArea( int desktop = - 1 );
380
381
382 /**
383 * Returns the workarea for the specified desktop, or the current
384 * work area if no desktop has been specified. Excludes struts of
385 * clients in the exclude List.
386 *
387 * @param excludes the list of clients whose struts will be excluded
388 * @param desktop the number of the desktop to check, -1 for the
389 * current desktop
390 * @return the size and position of the desktop
391 **/
392 static QRect workArea( const QList<WId> &excludes, int desktop = -1);
393
394 /**
395 * Returns the name of the specified desktop.
396 * @param desktop the number of the desktop
397 * @return the name of the desktop
398 **/
399 static QString desktopName( int desktop );
400
401 /**
402 * Sets the name of the specified desktop.
403 * @param desktop the number of the desktop
404 * @param name the new name for the desktop
405 **/
406 static void setDesktopName( int desktop, const QString& name );
407
408 /**
409 * Returns the state of showing the desktop.
410 */
411 static bool showingDesktop();
412
413 /**
414 * Sets user timestamp @p time on window @p win. The timestamp
415 * is expressed as XServer time. If a window
416 * is shown with user timestamp older than the time of the last
417 * user action, it won't be activated after being shown.
418 * The most common case is the special value 0 which means
419 * not to activate the window after being shown.
420 */
421 static void setUserTime( WId win, long time );
422 /**
423 * Sets the strut of window @p win to @p to @p left width
424 * ranging from @p left_start to @p left_end on the left edge,
425 * and simiarly for the other edges. For not reserving a strut, pass 0 as the width.
426 * E.g. to reserve 10x10 square in the topleft corner, use e.g.
427 * setExtendedStrut( w, 10, 0, 10, 0, 0, 0, 0, 0, 0, 0, 0, 0 ).
428 *
429 * @param win the id of the window
430 * @param left_width width of the strut at the left edge
431 * @param left_start starting y coordinate of the strut at the left edge
432 * @param left_end ending y coordinate of the strut at the left edge
433 * @param right_width width of the strut at the right edge
434 * @param right_start starting y coordinate of the strut at the right edge
435 * @param right_end ending y coordinate of the strut at the right edge
436 * @param top_width width of the strut at the top edge
437 * @param top_start starting x coordinate of the strut at the top edge
438 * @param top_end ending x coordinate of the strut at the top edge
439 * @param bottom_width width of the strut at the bottom edge
440 * @param bottom_start starting x coordinate of the strut at the bottom edge
441 * @param bottom_end ending x coordinate of the strut at the bottom edge
442 */
443 static void setExtendedStrut( WId win, int left_width, int left_start, int left_end,
444 int right_width, int right_start, int right_end, int top_width, int top_start, int top_end,
445 int bottom_width, int bottom_start, int bottom_end );
446
447 /**
448 * Convenience function for setExtendedStrut() that automatically makes struts
449 * as wide/high as the screen width/height.
450 * Sets the strut of window @p win to @p left, @p right, @p top, @p bottom.
451 *
452 * @param win the id of the window
453 * @param left the left strut
454 * @param right the right strut
455 * @param top the top strut
456 * @param bottom the bottom strut
457 */
458 static void setStrut( WId win, int left, int right, int top, int bottom );
459 /**
460 * Returns true if the WM announces which actions it allows for windows.
461 */
462 static bool allowedActionsSupported();
463 /**
464 * Function that reads and returns the contents of the given text
465 * property (WM_NAME, WM_ICON_NAME,...).
466 */
467 static QString readNameProperty( WId window, unsigned long atom );
468
469 /**
470 * Informs kwin via dbus to not manage a window with the
471 * specified @p title.
472 *
473 * Useful for swallowing legacy applications, for example java
474 * applets.
475 *
476 * @param title the title of the window
477 */
478 static void doNotManage( const QString& title );
479
480 /**
481 * Allows a window from another process to raise and activate itself.
482 * Depending on the window manager, the grant may only be temporary,
483 * or for a single activation, and it may require the current process
484 * to be the "foreground" one" (ie. the process with the input focus).
485 *
486 * You should call this function before executing actions that may trigger
487 * the showing of a window or dialog in another process, e.g. a dbus signal
488 * or function call, or any other inter-process notification mechanism.
489 *
490 * This is mostly used on Windows, where windows are not allowed to be raised
491 * and activated if their process is not the foreground one, but it may also
492 * apply to other window managers.
493 *
494 * @param pid if specified, the grant only applies to windows belonging to the
495 * specific process. By default, a value of -1 means all processes.
496 */
497 static void allowExternalProcessWindowActivation( int pid = -1 );
498
499 /**
500 * Sets whether the client wishes to block compositing (for better performance)
501 * @since 4.7
502 */
503 static void setBlockingCompositing( WId window, bool active );
504
505#ifdef Q_WS_X11
506 /**
507 * @internal
508 * Returns true if viewports are mapped to virtual desktops.
509 */
510 static bool mapViewport();
511 /**
512 * @internal
513 * Returns mapped virtual desktop for the given position in the viewport.
514 */
515 static int viewportToDesktop( const QPoint& pos );
516 /**
517 * @internal
518 * Returns mapped virtual desktop for the given window geometry.
519 */
520 static int viewportWindowToDesktop( const QRect& r );
521 /**
522 * @internal
523 * Returns topleft corner of the viewport area for the given mapped virtual desktop.
524 */
525 static QPoint desktopToViewport( int desktop, bool absolute );
526 /**
527 * @internal
528 * @since 4.0.1
529 * Checks the relative difference used to move a window will still be inside
530 * valid desktop area.
531 */
532 static QPoint constrainViewportRelativePosition( const QPoint& pos );
533#endif
534
535Q_SIGNALS:
536
537 /**
538 * Switched to another virtual desktop.
539 * @param desktop the number of the new desktop
540 */
541 void currentDesktopChanged( int desktop);
542
543 /**
544 * A window has been added.
545 * @param id the id of the window
546 */
547 void windowAdded(WId id);
548
549 /**
550 * A window has been removed.
551 * @param id the id of the window that has been removed
552 */
553 void windowRemoved(WId id);
554
555 /**
556 * Hint that \<Window> is active (= has focus) now.
557 * @param id the id of the window that is active
558 */
559 void activeWindowChanged(WId id);
560
561 /**
562 * Desktops have been renamed.
563 */
564 void desktopNamesChanged();
565
566 /**
567 * The number of desktops changed.
568 * @param num the new number of desktops
569 */
570 void numberOfDesktopsChanged(int num);
571
572 /**
573 * The workarea has changed.
574 */
575 void workAreaChanged();
576
577 /**
578 * Something changed with the struts, may or may not have changed
579 * the work area. Usually just using the workAreaChanged() signal
580 * is sufficient.
581 */
582 void strutChanged();
583
584 /**
585 * Emitted when the stacking order of the window changed. The new order
586 * can be obtained with stackingOrder().
587 */
588 void stackingOrderChanged();
589
590 /**
591 * The window changed.
592 *
593 * The properties parameter contains the NET properties that
594 * were modified (see netwm_def.h). First element are NET::Property
595 * values, second element are NET::Property2 values (i.e. the format
596 * is the same like for the NETWinInfo class constructor).
597 * @param id the id of the window
598 * @param properties the properties that were modified
599 */
600 void windowChanged(WId id, const unsigned long* properties );
601
602 /**
603 * @deprecated
604 * The window changed.
605 *
606 * The unsigned int parameter contains the NET properties that
607 * were modified (see netwm_def.h).
608 * @param id the id of the window
609 * @param properties the properties that were modified
610 */
611 void windowChanged(WId id, unsigned int properties);
612
613 /**
614 * The window changed somehow.
615 * @param id the id of the window
616 */
617 void windowChanged(WId id);
618
619 /**
620 * The state of showing the desktop has changed.
621 */
622 void showingDesktopChanged( bool showing );
623
624 /**
625 * Compositing was enabled or disabled.
626 *
627 * Note that this signal may be emitted before any compositing plugins
628 * have been initialized in the window manager.
629 *
630 * If you need to check if a specific compositing plugin such as the
631 * blur effect is enabled, you should track that separately rather
632 * than test for it in a slot connected to this signal.
633 *
634 * @since 4.7.1
635 */
636 void compositingChanged( bool enabled );
637
638protected:
639 virtual void connectNotify( const char* signal );
640
641private:
642 friend class KWindowSystemStaticContainer;
643
644 KWindowSystem() {}
645
646 enum { INFO_BASIC=1, // desktop info, not per-window
647 INFO_WINDOWS=2 }; // also per-window info
648
649 static void init(int);
650
651 friend class KWindowSystemPrivate;
652 static KWindowSystemPrivate* s_d_func();
653};
654
655#endif
656