1 // -*- mode: C++; indent-tabs-mode: nil; c-basic-offset: 2; -*-
6 @brief The Client class maintains the state of a client window by handling
7 property changes on the window and some client messages
11 #include "otk/strut.hh"
12 #include "otk/rect.hh"
13 #include "otk/eventhandler.hh"
14 #include "otk/ustring.hh"
20 #include <X11/extensions/shape.h>
37 //! The MWM Hints as retrieved from the window property
39 This structure only contains 3 elements, even though the Motif 2.0
40 structure contains 5. We only use the first 3, so that is all gets defined.
43 unsigned long flags
; //!< A bitmask of Client::MwmFlags values
44 unsigned long functions
; //!< A bitmask of Client::MwmFunctions values
45 unsigned long decorations
;//!< A bitmask of Client::MwmDecorations values
46 //! The number of elements in the Client::MwmHints struct
47 static const unsigned int elements
= 3;
50 //! Maintains the state of a client window.
52 Client maintains the state of a client window. The state consists of the
53 hints that the application sets on the window, such as the title, or window
56 Client also manages client messages for the client window. When the
57 application (or any application) requests something to be changed for the
58 client, it will call the ActionHandler (for client messages) or update the
59 class' member variables and call whatever is nessary to complete the
60 change (such as causing a redraw of the titlebar after the title is changed).
62 class Client
: public otk::EventHandler
{
65 //! The frame window which decorates around the client window
67 NOTE: This should NEVER be used inside the client class's constructor!
71 //! Holds a list of Clients
72 typedef std::list
<Client
*> List
;
74 //! The possible stacking layers a client window can be a part of
76 Layer_Icon
, //!< 0 - iconified windows, in any order at all
77 Layer_Desktop
, //!< 1 - desktop windows
78 Layer_Below
, //!< 2 - normal windows w/ below
79 Layer_Normal
, //!< 3 - normal windows
80 Layer_Above
, //!< 4 - normal windows w/ above
81 Layer_Top
, //!< 5 - always-on-top-windows (docks?)
82 Layer_Fullscreen
, //!< 6 - fullscreeen windows
83 Layer_Internal
, //!< 7 - openbox windows/menus
87 //! Corners of the client window, used for anchor positions
88 enum Corner
{ TopLeft
,
93 //! Possible window types
94 enum WindowType
{ Type_Desktop
, //!< A desktop (bottom-most window)
95 Type_Dock
, //!< A dock bar/panel window
96 Type_Toolbar
, //!< A toolbar window, pulled off an app
97 Type_Menu
, //!< An unpinned menu from an app
98 Type_Utility
, //!< A small utility window such as a palette
99 Type_Splash
, //!< A splash screen window
100 Type_Dialog
, //!< A dialog window
101 Type_Normal
//!< A normal application window
104 //! Possible flags for MWM Hints (defined by Motif 2.0)
105 enum MwmFlags
{ MwmFlag_Functions
= 1 << 0, //!< The MMW Hints define funcs
106 MwmFlag_Decorations
= 1 << 1 //!< The MWM Hints define decor
109 //! Possible functions for MWM Hints (defined by Motif 2.0)
110 enum MwmFunctions
{ MwmFunc_All
= 1 << 0, //!< All functions
111 MwmFunc_Resize
= 1 << 1, //!< Allow resizing
112 MwmFunc_Move
= 1 << 2, //!< Allow moving
113 MwmFunc_Iconify
= 1 << 3, //!< Allow to be iconfied
114 MwmFunc_Maximize
= 1 << 4 //!< Allow to be maximized
115 //MwmFunc_Close = 1 << 5 //!< Allow to be closed
118 //! Possible decorations for MWM Hints (defined by Motif 2.0)
119 enum MemDecorations
{ MwmDecor_All
= 1 << 0, //!< All decorations
120 MwmDecor_Border
= 1 << 1, //!< Show a border
121 MwmDecor_Handle
= 1 << 2, //!< Show a handle (bottom)
122 MwmDecor_Title
= 1 << 3, //!< Show a titlebar
123 //MwmDecor_Menu = 1 << 4, //!< Show a menu
124 MwmDecor_Iconify
= 1 << 5, //!< Show an iconify button
125 MwmDecor_Maximize
= 1 << 6 //!< Show a maximize button
128 //! The things the user can do to the client window
129 enum Function
{ Func_Resize
= 1 << 0, //!< Allow resizing
130 Func_Move
= 1 << 1, //!< Allow moving
131 Func_Iconify
= 1 << 2, //!< Allow to be iconified
132 Func_Maximize
= 1 << 3, //!< Allow to be maximized
133 Func_Shade
= 1 << 4, //!< Allow to be shaded
134 Func_Fullscreen
= 1 << 5, //!< Allow to be made fullscreen
135 Func_Close
= 1 << 6 //!< Allow to be closed
137 //! Holds a bitmask of Client::Function values
138 typedef unsigned char FunctionFlags
;
140 //! The decorations the client window wants to be displayed on it
141 enum Decoration
{ Decor_Titlebar
= 1 << 0, //!< Display a titlebar
142 Decor_Handle
= 1 << 1, //!< Display a handle (bottom)
143 Decor_Border
= 1 << 2, //!< Display a border
144 Decor_Icon
= 1 << 3, //!< Display the window's icon
145 Decor_Iconify
= 1 << 4, //!< Display an iconify button
146 Decor_Maximize
= 1 << 5, //!< Display a maximize button
147 //! Display a button to toggle the window's placement on
149 Decor_AllDesktops
= 1 << 6,
150 Decor_Close
= 1 << 7 //!< Display a close button
152 //! Holds a bitmask of Client::Decoration values
153 typedef unsigned char DecorationFlags
;
155 //! The event mask to grab on client windows
156 static const long event_mask
= PropertyChangeMask
| FocusChangeMask
|
159 //! The mask of events to not let propogate past the client
161 This makes things like xprop work on the client window, but means we have
162 to explicitly grab clicks that we want.
164 static const long no_propagate_mask
= ButtonPressMask
| ButtonReleaseMask
|
167 //! The number of unmap events to ignore on the window
171 //! The screen number on which the client resides
174 //! The actual window that this class is wrapping up
177 //! The id of the group the window belongs to
180 //! The client which this client is a transient (child) for
181 Client
*_transient_for
;
183 //! The clients which are transients (children) of this client
184 Client::List _transients
;
186 //! The desktop on which the window resides (0xffffffff for all desktops)
187 unsigned int _desktop
;
189 //! Normal window title
191 //! Window title when iconifiged
192 otk::ustring _icon_title
;
194 //! The application that created the window
195 std::string _app_name
;
196 //! The class of the window, can used for grouping
197 std::string _app_class
;
198 //! The specified role of the window, used for identification
201 //! The type of window (what its function is)
204 //! Position and size of the window
206 This will not always be the actual position of the window on screen, it is
207 rather, the position requested by the client, to which the window's gravity
212 //! The window's strut
214 The strut defines areas of the screen that are marked off-bounds for window
215 placement. In theory, where this window exists.
219 //! The logical size of the window
221 The "logical" size of the window is refers to the user's perception of the
222 size of the window, and is the value that should be displayed to the user.
223 For example, with xterms, this value it the number of characters being
224 displayed in the terminal, instead of the number of pixels.
226 otk::Size _logical_size
;
228 //! Width of the border on the window.
230 The window manager will set this to 0 while the window is being managed,
231 but needs to restore it afterwards, so it is saved here.
235 //! The minimum aspect ratio the client window can be sized to.
237 A value of 0 means this is ignored.
240 //! The maximum aspect ratio the client window can be sized to.
242 A value of 0 means this is ignored.
246 //! The minimum size of the client window
248 If the min is > the max, then the window is not resizable
251 //! The maximum size of the client window
253 If the min is > the max, then the window is not resizable
256 //! The size of increments to resize the client window by
258 //! The base size of the client window
260 This value should be subtracted from the window's actual size when
261 displaying its size to the user, or working with its min/max size
263 otk::Size _base_size
;
265 //! Window decoration and functionality hints
268 //! Where to place the decorated window in relation to the undecorated window
271 //! The state of the window, one of WithdrawnState, IconicState, or
275 //! True if the client supports the delete_window protocol
278 //! Was the window's position requested by the application? if not, we should
279 //! place the window ourselves when it first appears
282 //! Can the window receive input focus?
286 //! Notify the window when it receives focus?
288 //! Does the client window have the input focus?
291 //! The window uses shape extension to be non-rectangular?
294 //! The window is modal, so it must be processed before any windows it is
295 //! related to can be focused
297 //! Only the window's titlebar is displayed
299 //! The window is iconified
301 //! The window is maximized to fill the screen vertically
303 //! The window is maximized to fill the screen horizontally
305 //! The window should not be displayed by pagers
307 //! The window should not be displayed by taskbars
309 //! The window is a 'fullscreen' window, and should be on top of all others
311 //! The window should be on top of other windows of the same type
313 //! The window should be underneath other windows of the same type
316 //! The layer in which the window will be stacked, windows in lower layers
317 //! are always below windows in higher layers.
320 //! A bitmask of values in the Client::Decoration enum
322 The values in the variable are the decorations that the client wants to be
325 DecorationFlags _decorations
;
327 //! A bitmask of values in the Client::Decoration enum.
329 Specifies the decorations that should NOT be displayed on the client.
331 DecorationFlags _disabled_decorations
;
333 //! A bitmask of values in the Client::Function enum
335 The values in the variable specify the ways in which the user is allowed to
338 FunctionFlags _functions
;
340 //! Icons for the client as specified on the client window
342 //! The number of icons in _icons
346 Pixmap _pixmap_icon_mask
;
348 //! Retrieves the window's initial gravity
350 //! Retrieves the desktop hint's value and sets Client::_desktop
352 //! Retrieves the window's type and sets Client::_type
354 //! Gets the MWM Hints and adjusts Client::_functions and
355 //! Client::_decorations
357 //! Gets the position and size of the window and sets Client::_area
359 //! Gets the net_state hint and sets the boolean flags for any states set in
362 //! Determines if the window uses the Shape extension and sets
366 //! Set up what decor should be shown on the window and what functions should
367 //! be allowed (Client::_decorations and Client::_functions).
369 This also updates the NET_WM_ALLOWED_ACTIONS hint.
371 void setupDecorAndFunctions();
373 //! Sets the wm_state to the specified value
374 void setWMState(long state
);
375 //! Adjusts the window's net_state
377 This should not be called as part of the window mapping process! It is for
378 use when updating the state post-mapping.<br>
379 Client::applyStartupState is used to do the same things during the mapping
382 void setState(Atom action
, long data1
, long data2
);
384 //! Sends the window to the specified desktop
385 void setDesktop(unsigned int desktop
);
387 //! Calculates the stacking layer for the client window
390 //! Update the protocols that the window supports and adjusts things if they
392 void updateProtocols();
393 //! Updates the WMNormalHints and adjusts things if they change
394 void updateNormalHints();
395 //! Updates the WMHints and adjusts things if they change
397 @param initstate Whether to read the initial_state property from the
398 WMHints. This should only be used during the mapping
401 void updateWMHints(bool initstate
= false);
402 //! Updates the window's title
404 //! Updates the window's icon title
405 void updateIconTitle();
406 //! Updates the window's application name and class
408 //! Updates the strut for the client
410 //! Updates the window's transient status, and any parents of it
411 void updateTransientFor();
412 //! Updates the window's icons
414 //! Updates the window's kwm icon
415 void updateKwmIcon();
417 //! Change the client's state hints to match the class' data
419 //! Change the allowed actions set on the client
420 void changeAllowedActions();
422 //! Request the client to close its window.
425 //! Shades or unshades the client window
427 @param shade true if the window should be shaded; false if it should be
430 void shade(bool shade
);
432 //! Recursively searches the client 'tree' for a modal client, always skips
433 //! the topmost node (the window you're starting with).
434 Client
*Client::searchModalTree(Client
*node
, Client
*skip
);
436 //! Recursively searches the client 'tree' for a focused client, always skips
437 //! the topmost node (the window you're starting with).
438 Client
*Client::searchFocusTree(Client
*node
, Client
*skip
);
440 //! Fires the urgent callbacks which lets the user do what they want with
444 //! Fullscreen's or unfullscreen's the client window
446 @param fs true if the window should be made fullscreen; false if it should
447 be returned to normal state.
448 @param savearea true to have the client's current size and position saved;
449 otherwise, they are not. You should not save when mapping a
450 new window that is set to fullscreen. This has no effect
451 when restoring a window from fullscreen.
453 void fullscreen(bool fs
, bool savearea
= true);
455 //! Iconifies or uniconifies the client window
457 @param iconic true if the window should be iconified; false if it should be
459 @param curdesk If iconic is false, then this determines if the window will
460 be uniconified to the current viewable desktop (true) or to
461 its previous desktop (false)
463 void iconify(bool iconic
, bool curdesk
= true);
465 //! Maximize or unmaximize the client window
467 @param max true if the window should be maximized; false if it should be
468 returned to normal size.
469 @param dir 0 to set both horz and vert, 1 to set horz, 2 to set vert.
470 @param savearea true to have the client's current size and position saved;
471 otherwise, they are not. You should not save when mapping a
472 new window that is set to fullscreen. This has no effect
473 when unmaximizing a window.
475 void maximize(bool max
, int dir
, bool savearea
= true);
477 //! Internal version of the Client::move function
479 @param x The X coordinate to move to.
480 @param y The Y coordinate to move to.
482 void internal_move(int x
, int y
);
483 //! Internal version of the Client::resize function
485 This also maintains things like the client's minsize, and size increments.
486 @param anchor The corner to keep in the same position when resizing.
487 @param w The width component of the new size for the client.
488 @param h The height component of the new size for the client.
489 @param user Specifies whether this is a user-requested change or a
490 program requested change.
491 @param x An optional X coordinate to which the window will be moved
493 @param y An optional Y coordinate to which the window will be moved
495 The x and y coordinates must both be sepcified together, or they will have
496 no effect. When they are specified, the anchor is ignored.
498 void internal_resize(Corner anchor
, int w
, int h
,
499 bool user
= true, int x
= INT_MIN
, int y
= INT_MIN
);
501 //! Removes or reapplies the client's border to its window
503 Used when managing and unmanaging a window.
504 @param addborder true if adding the border to the client; false if removing
507 void toggleClientBorder(bool addborder
);
509 //! Applies the states requested when the window mapped
511 This should be called only once, during the window mapping process. It
512 applies things like maximized, and fullscreen.
514 void applyStartupState();
517 //! Constructs a new Client object around a specified window id
519 @param window The window id that the Client class should handle
520 @param screen The screen on which the window resides
522 Client(int screen
, Window window
);
523 //! Destroys the Client object
526 //! Returns the screen on which the clien resides
527 inline int screen() const { return _screen
; }
529 //! Returns the window id that the Client object is handling
530 inline Window
window() const { return _window
; }
532 //! Returns the type of the window, one of the Client::WindowType values
533 inline WindowType
type() const { return _type
; }
534 //! Returns if the window should be treated as a normal window.
536 Some windows (desktops, docks, splash screens) have special rules applied
537 to them in a number of places regarding focus or user interaction.
539 inline bool normal() const {
540 return ! (_type
== Type_Desktop
|| _type
== Type_Dock
||
541 _type
== Type_Splash
);
544 //! Returns the desktop on which the window resides
546 This value is a 0-based index.<br>
547 A value of 0xffffffff indicates that the window exists on all desktops.
549 inline unsigned int desktop() const { return _desktop
; }
550 //! Returns the window's title
551 inline const otk::ustring
&title() const { return _title
; }
552 //! Returns the window's title when it is iconified
553 inline const otk::ustring
&iconTitle() const { return _title
; }
554 //! Returns the application's name to whom the window belongs
555 inline const std::string
&appName() const { return _app_name
; }
556 //! Returns the class of the window
557 inline const std::string
&appClass() const { return _app_class
; }
558 //! Returns the program-specified role of the window
559 inline const std::string
&role() const { return _role
; }
560 //! Returns if the window can be focused
562 @return true if the window can receive focus; otherwise, false
564 inline bool canFocus() const { return _can_focus
; }
565 //! Returns if the window has indicated that it needs urgent attention
566 inline bool urgent() const { return _urgent
; }
567 //! Returns if the window wants to be notified when it receives focus
568 inline bool focusNotify() const { return _focus_notify
; }
569 //! Returns if the window is the focused window
570 inline bool focused() const { return _focused
; }
571 //! Returns if the window uses the Shape extension
572 inline bool shaped() const { return _shaped
; }
573 //! Returns the window's gravity
575 This value determines where to place the decorated window in relation to
576 its position without decorations.<br>
577 One of: NorthWestGravity, SouthWestGravity, EastGravity, ...,
578 SouthGravity, StaticGravity, ForgetGravity
580 inline int gravity() const { return _gravity
; }
581 //! Returns if the application requested the initial position for the window
583 If the application did not request a position (this function returns false)
584 then the window should be placed intelligently by the window manager
587 inline bool positionRequested() const { return _positioned
; }
588 //! Returns the decorations that the client window wishes to be displayed on
590 inline DecorationFlags
decorations() const { return _decorations
; }
591 //! Returns the decorations that the user has requested to be disabled on the
593 inline DecorationFlags
disabledDecorations() const
594 { return _disabled_decorations
; }
595 //! Returns the functions that the user can perform on the window
596 inline FunctionFlags
funtions() const { return _functions
; }
598 //! Return the client this window is transient for
599 inline Client
*transientFor() const { return _transient_for
; }
601 //! Returns if the window is modal
603 If the window is modal, then no other windows that it is related to can get
604 focus while it exists/remains modal.
606 inline bool modal() const { return _modal
; }
607 //! The window should not be displayed by pagers
608 inline bool skipPager() const { return _skip_pager
; }
609 //! The window should not be displayed by taskbars
610 inline bool skipTaskbar() const { return _skip_taskbar
; }
611 //! Returns if the window is shaded
613 When the window is shaded, only its titlebar is visible.
615 inline bool shaded() const { return _shaded
; }
616 //! Returns if the window is in fullscreen mode
617 inline bool fullscreen() const { return _fullscreen
; }
618 //! Returns if the window is iconified
620 When the window is iconified, it is not visible at all (except in iconbars/
621 panels/etc that want to show lists of iconified windows
623 inline bool iconic() const { return _iconic
; }
624 //! Returns if the window is maximized vertically
625 inline bool maxVert() const { return _max_vert
; }
626 //! Returns if the window is maximized horizontally
627 inline bool maxHorz() const { return _max_horz
; }
628 //! Returns the window's stacking layer
629 inline StackLayer
layer() const { return _layer
; }
631 //! Returns the logical size of the window
633 The "logical" size of the window is refers to the user's perception of the
634 size of the window, and is the value that should be displayed to the user.
635 For example, with xterms, this value it the number of characters being
636 displayed in the terminal, instead of the number of pixels.
638 const otk::Size
&logicalSize() const { return _logical_size
; }
640 //! Returns the position and size of the client relative to the root window
642 Note that this value is *not* the size and position of the window's
643 frame, though the position will often line up.<br>
644 If you want the frame's area, use Frame::area() instead.
646 inline const otk::Rect
&area() const { return _area
; }
648 //! Returns the client's strut definition
649 inline const otk::Strut
&strut() const { return _strut
; }
651 //! Returns an icon for the window
653 The icon chosen will be the smallest icon available that is still bigger or
654 equal to the specified Size.<br>
655 If none that meet the requirements is found, the largest icon that is
656 smaller than the specified size will be returned.
658 const Icon
*icon(const otk::Size
&s
) const;
660 //! Returns the pixmap for the pixmap icon specified on the window (or None)
662 The icon given by Client::icon should take precedence over this icon/mask.
664 Pixmap
pixmapIcon() const { return _pixmap_icon
; }
665 //! Returns the mask for the pixmap icon specified on the window (or None)
667 The icon given by Client::icon should take precedence over this icon/mask.
669 Pixmap
pixmapIconMask() const { return _pixmap_icon_mask
; }
671 //! Move the window (actually, its frame) to a position.
673 This moves the window so that the top-left corner of its frame will be at
674 the position specified.
675 @param x The X coordinate to move to.
676 @param y The Y coordinate to move to.
678 void move(int x
, int y
);
680 //! Resizes the client window, anchoring it in a given corner
682 This also maintains things like the client's minsize, and size increments.
683 @param anchor The corner to keep in the same position when resizing.
684 @param w The width component of the new size for the client.
685 @param h The height component of the new size for the client.
687 void resize(Corner anchor
, int w
, int h
);
689 //! Reapplies the maximized state to the window
691 Use this to make the window readjust its maximized size to new
692 surroundings (struts, etc).
696 //! Shows the window if it should be shown, or hides it
698 Used when changing desktops, the window's state, etc.
702 //! Choose a mask of decorations to not display on the client
704 Pass a value of 0 to the function to turn all decorations back on. Note
705 that you cannot add decorations to a window with this, you can only remove
706 decorations that would otherwise have been displayed.
707 @param flags The mask of values from Client::Decoration to specify which
708 decorations should not be displayed.
710 void disableDecorations(DecorationFlags flags
);
712 //! Return a modal child of the client window
714 @return A modal child of the client window, or 0 if none was found.
716 Client
*findModalChild();
718 //! Attempt to focus the client window
721 //! Remove focus from the client window
722 void unfocus() const;
724 //! Validate client, by making sure no Destroy or Unmap events exist in
725 //! the event queue for the window.
727 @return true if the client is valid; false if the client has already
728 been unmapped/destroyed, and so is invalid.
730 bool validate() const;
732 void installColormap(bool install
) const;
734 virtual void focusHandler(const XFocusChangeEvent
&e
);
735 virtual void unfocusHandler(const XFocusChangeEvent
&e
);
736 virtual void propertyHandler(const XPropertyEvent
&e
);
737 virtual void clientMessageHandler(const XClientMessageEvent
&e
);
738 virtual void configureRequestHandler(const XConfigureRequestEvent
&e
);
739 virtual void unmapHandler(const XUnmapEvent
&e
);
740 virtual void destroyHandler(const XDestroyWindowEvent
&e
);
741 virtual void reparentHandler(const XReparentEvent
&e
);
742 virtual void mapRequestHandler(const XMapRequestEvent
&e
);
744 virtual void shapeHandler(const XShapeEvent
&e
);
747 friend void Screen::manageWindow(Window
);
748 friend void Screen::unmanageWindow(Client
*);
753 #endif // __client_hh