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 "widgetbase.hh"
12 #include "otk/point.hh"
13 #include "otk/strut.hh"
14 #include "otk/rect.hh"
15 #include "otk/eventhandler.hh"
16 #include "otk/ustring.hh"
22 #include <X11/extensions/shape.h>
34 //! The MWM Hints as retrieved from the window property
36 This structure only contains 3 elements, even though the Motif 2.0
37 structure contains 5. We only use the first 3, so that is all gets defined.
40 unsigned long flags
; //!< A bitmask of Client::MwmFlags values
41 unsigned long functions
; //!< A bitmask of Client::MwmFunctions values
42 unsigned long decorations
;//!< A bitmask of Client::MwmDecorations values
43 //! The number of elements in the Client::MwmHints struct
44 static const unsigned int elements
= 3;
47 //! Maintains the state of a client window.
49 Client maintains the state of a client window. The state consists of the
50 hints that the application sets on the window, such as the title, or window
53 Client also manages client messages for the client window. When the
54 application (or any application) requests something to be changed for the
55 client, it will call the ActionHandler (for client messages) or update the
56 class' member variables and call whatever is nessary to complete the
57 change (such as causing a redraw of the titlebar after the title is changed).
59 class Client
: public otk::EventHandler
, public WidgetBase
{
62 //! The frame window which decorates around the client window
64 NOTE: This should NEVER be used inside the client class's constructor!
68 //! Holds a list of Clients
69 typedef std::list
<Client
*> List
;
71 //! The possible stacking layers a client window can be a part of
73 Layer_Icon
, //!< 0 - iconified windows, in any order at all
74 Layer_Desktop
, //!< 1 - desktop windows
75 Layer_Below
, //!< 2 - normal windows w/ below
76 Layer_Normal
, //!< 3 - normal windows
77 Layer_Above
, //!< 4 - normal windows w/ above
78 Layer_Top
, //!< 5 - always-on-top-windows (docks?)
79 Layer_Fullscreen
, //!< 6 - fullscreeen windows
80 Layer_Internal
, //!< 7 - openbox windows/menus
84 //! Corners of the client window, used for anchor positions
85 enum Corner
{ TopLeft
,
90 //! Possible window types
91 enum WindowType
{ Type_Desktop
, //!< A desktop (bottom-most window)
92 Type_Dock
, //!< A dock bar/panel window
93 Type_Toolbar
, //!< A toolbar window, pulled off an app
94 Type_Menu
, //!< An unpinned menu from an app
95 Type_Utility
, //!< A small utility window such as a palette
96 Type_Splash
, //!< A splash screen window
97 Type_Dialog
, //!< A dialog window
98 Type_Normal
//!< A normal application window
101 //! Possible flags for MWM Hints (defined by Motif 2.0)
102 enum MwmFlags
{ MwmFlag_Functions
= 1 << 0, //!< The MMW Hints define funcs
103 MwmFlag_Decorations
= 1 << 1 //!< The MWM Hints define decor
106 //! Possible functions for MWM Hints (defined by Motif 2.0)
107 enum MwmFunctions
{ MwmFunc_All
= 1 << 0, //!< All functions
108 MwmFunc_Resize
= 1 << 1, //!< Allow resizing
109 MwmFunc_Move
= 1 << 2, //!< Allow moving
110 MwmFunc_Iconify
= 1 << 3, //!< Allow to be iconfied
111 MwmFunc_Maximize
= 1 << 4 //!< Allow to be maximized
112 //MwmFunc_Close = 1 << 5 //!< Allow to be closed
115 //! Possible decorations for MWM Hints (defined by Motif 2.0)
116 enum MemDecorations
{ MwmDecor_All
= 1 << 0, //!< All decorations
117 MwmDecor_Border
= 1 << 1, //!< Show a border
118 MwmDecor_Handle
= 1 << 2, //!< Show a handle (bottom)
119 MwmDecor_Title
= 1 << 3, //!< Show a titlebar
120 //MwmDecor_Menu = 1 << 4, //!< Show a menu
121 MwmDecor_Iconify
= 1 << 5, //!< Show an iconify button
122 MwmDecor_Maximize
= 1 << 6 //!< Show a maximize button
125 //! The things the user can do to the client window
126 enum Function
{ Func_Resize
= 1 << 0, //!< Allow resizing
127 Func_Move
= 1 << 1, //!< Allow moving
128 Func_Iconify
= 1 << 2, //!< Allow to be iconified
129 Func_Maximize
= 1 << 3, //!< Allow to be maximized
130 Func_Shade
= 1 << 4, //!< Allow to be shaded
131 Func_Fullscreen
= 1 << 5, //!< Allow to be made fullscreen
132 Func_Close
= 1 << 6 //!< Allow to be closed
134 //! Holds a bitmask of Client::Function values
135 typedef unsigned char FunctionFlags
;
137 //! The decorations the client window wants to be displayed on it
138 enum Decoration
{ Decor_Titlebar
= 1 << 0, //!< Display a titlebar
139 Decor_Handle
= 1 << 1, //!< Display a handle (bottom)
140 Decor_Border
= 1 << 2, //!< Display a border
141 Decor_Iconify
= 1 << 3, //!< Display an iconify button
142 Decor_Maximize
= 1 << 4, //!< Display a maximize button
143 //! Display a button to toggle the window's placement on
145 Decor_AllDesktops
= 1 << 5,
146 Decor_Close
= 1 << 6 //!< Display a close button
148 //! Holds a bitmask of Client::Decoration values
149 typedef unsigned char DecorationFlags
;
151 //! Possible actions that can be made with the _NET_WM_STATE client message
152 enum StateAction
{ State_Remove
= 0, //!< _NET_WM_STATE_REMOVE
153 State_Add
, //!< _NET_WM_STATE_ADD
154 State_Toggle
//!< _NET_WM_STATE_TOGGLE
157 //! The event mask to grab on client windows
158 static const long event_mask
= PropertyChangeMask
| FocusChangeMask
|
161 //! The mask of events to not let propogate past the client
163 This makes things like xprop work on the client window, but means we have
164 to explicitly grab clicks that we want.
166 static const long no_propagate_mask
= ButtonPressMask
| ButtonReleaseMask
|
169 //! The desktop value which indicated the window is iconified and not on any
171 static const long ICONIC_DESKTOP
= 0xfffffffe;
173 //! The number of unmap events to ignore on the window
177 //! The screen number on which the client resides
180 //! The actual window that this class is wrapping up
183 //! The id of the group the window belongs to
186 //! The client which this client is a transient (child) for
187 Client
*_transient_for
;
189 //! The clients which are transients (children) of this client
190 Client::List _transients
;
192 //! The desktop on which the window resides (0xffffffff for all desktops)
195 //! Normal window title
197 //! Window title when iconifiged
198 otk::ustring _icon_title
;
200 //! The application that created the window
201 std::string _app_name
;
202 //! The class of the window, can used for grouping
203 std::string _app_class
;
204 //! The specified role of the window, used for identification
207 //! The type of window (what its function is)
210 //! Position and size of the window
212 This will not always be the actual position of the window on screen, it is
213 rather, the position requested by the client, to which the window's gravity
218 //! The window's strut
220 The strut defines areas of the screen that are marked off-bounds for window
221 placement. In theory, where this window exists.
225 //! The logical size of the window
227 The "logical" size of the window is refers to the user's perception of the
228 size of the window, and is the value that should be displayed to the user.
229 For example, with xterms, this value it the number of characters being
230 displayed in the terminal, instead of the number of pixels.
232 otk::Point _logical_size
;
234 //! Width of the border on the window.
236 The window manager will set this to 0 while the window is being managed,
237 but needs to restore it afterwards, so it is saved here.
241 //! The minimum aspect ratio the client window can be sized to.
243 A value of 0 means this is ignored.
246 //! The maximum aspect ratio the client window can be sized to.
248 A value of 0 means this is ignored.
252 //! The minimum size of the client window
254 If the min is > the max, then the window is not resizable
256 otk::Point _min_size
;
257 //! The maximum size of the client window
259 If the min is > the max, then the window is not resizable
261 otk::Point _max_size
;
262 //! The size of increments to resize the client window by
263 otk::Point _size_inc
;
264 //! The base size of the client window
266 This value should be subtracted from the window's actual size when
267 displaying its size to the user, or working with its min/max size
269 otk::Point _base_size
;
271 //! Window decoration and functionality hints
274 //! Where to place the decorated window in relation to the undecorated window
277 //! The state of the window, one of WithdrawnState, IconicState, or
281 //! True if the client supports the delete_window protocol
284 //! Was the window's position requested by the application? if not, we should
285 //! place the window ourselves when it first appears
288 //! Can the window receive input focus?
292 //! Notify the window when it receives focus?
294 //! Does the client window have the input focus?
297 //! The window uses shape extension to be non-rectangular?
300 //! If the window has a modal child window, then this will point to it
301 Client
*_modal_child
;
303 //! The window is modal, so it must be processed before any windows it is
304 //! related to can be focused
306 //! Only the window's titlebar is displayed
308 //! The window is iconified
310 //! The window is maximized to fill the screen vertically
312 //! The window is maximized to fill the screen horizontally
314 //! The window should not be displayed by pagers
316 //! The window should not be displayed by taskbars
318 //! The window is a 'fullscreen' window, and should be on top of all others
320 //! The window should be on top of other windows of the same type
322 //! The window should be underneath other windows of the same type
327 //! A bitmask of values in the Client::Decoration enum
329 The values in the variable are the decorations that the client wants to be
332 DecorationFlags _decorations
;
334 //! A bitmask of values in the Client::Decoration enum.
336 Specifies the decorations that should NOT be displayed on the client.
338 DecorationFlags _disabled_decorations
;
340 //! A bitmask of values in the Client::Function enum
342 The values in the variable specify the ways in which the user is allowed to
345 FunctionFlags _functions
;
347 //! Retrieves the window's initial gravity
349 //! Retrieves the desktop hint's value and sets Client::_desktop
351 //! Retrieves the window's type and sets Client::_type
353 //! Gets the MWM Hints and adjusts Client::_functions and
354 //! Client::_decorations
356 //! Gets the position and size of the window and sets Client::_area
358 //! Gets the net_state hint and sets the boolean flags for any states set in
361 //! Determines if the window uses the Shape extension and sets
365 //! Set up what decor should be shown on the window and what functions should
366 //! be allowed (Client::_decorations and Client::_functions).
368 This also updates the NET_WM_ALLOWED_ACTIONS hint.
370 void setupDecorAndFunctions();
372 //! Sets the wm_state to the specified value
373 void setWMState(long state
);
374 //! Adjusts the window's net_state
376 This should not be called as part of the window mapping process! It is for
377 use when updating the state post-mapping.<br>
378 Client::applyStartupState is used to do the same things during the mapping
381 void setState(StateAction action
, long data1
, long data2
);
383 //! Sends the window to the specified desktop
385 A window is iconified by sending it to the ICONIC_DESKTOP, and restored
386 by sending it to any other valid desktop.
388 void setDesktop(long desktop
);
389 //! Set whether the window is modal or not
391 This adjusts references in parents etc to match.
393 void setModal(bool modal
);
395 //! Calculates the stacking layer for the client window
398 //! Update the protocols that the window supports and adjusts things if they
400 void updateProtocols();
401 //! Updates the WMNormalHints and adjusts things if they change
402 void updateNormalHints();
403 //! Updates the WMHints and adjusts things if they change
405 @param initstate Whether to read the initial_state property from the
406 WMHints. This should only be used during the mapping
409 void updateWMHints(bool initstate
= false);
410 //! Updates the window's title
412 //! Updates the window's icon title
413 void updateIconTitle();
414 //! Updates the window's application name and class
416 //! Updates the strut for the client
418 //! Updates the window's transient status, and any parents of it
419 void updateTransientFor();
421 //! Change the client's state hints to match the class' data
423 //! Change the allowed actions set on the client
424 void changeAllowedActions();
426 //! Request the client to close its window.
429 //! Shades or unshades the client window
431 @param shade true if the window should be shaded; false if it should be
434 void shade(bool shade
);
436 //! Fires the urgent callbacks which lets the user do what they want with
440 //! Fullscreen's or unfullscreen's the client window
442 @param fs true if the window should be made fullscreen; false if it should
443 be returned to normal state.
444 @param savearea true to have the client's current size and position saved;
445 otherwise, they are not. You should not save when mapping a
446 new window that is set to fullscreen. This has no effect
447 when restoring a window from fullscreen.
449 void fullscreen(bool fs
, bool savearea
= true);
451 //! Maximize or unmaximize the client window
453 @param max true if the window should be maximized; false if it should be
454 returned to normal size.
455 @param dir 0 to set both horz and vert, 1 to set horz, 2 to set vert.
456 @param savearea true to have the client's current size and position saved;
457 otherwise, they are not. You should not save when mapping a
458 new window that is set to fullscreen. This has no effect
459 when unmaximizing a window.
461 void maximize(bool max
, int dir
, bool savearea
= true);
463 //! Internal version of the Client::move function
465 @param x The X coordinate to move to.
466 @param y The Y coordinate to move to.
468 void internal_move(int x
, int y
);
469 //! Internal version of the Client::resize function
471 This also maintains things like the client's minsize, and size increments.
472 @param anchor The corner to keep in the same position when resizing.
473 @param w The width component of the new size for the client.
474 @param h The height component of the new size for the client.
475 @param user Specifies whether this is a user-requested change or a
476 program requested change.
477 @param x An optional X coordinate to which the window will be moved
479 @param y An optional Y coordinate to which the window will be moved
481 The x and y coordinates must both be sepcified together, or they will have
482 no effect. When they are specified, the anchor is ignored.
484 void internal_resize(Corner anchor
, int w
, int h
, bool user
= true,
485 int x
= INT_MIN
, int y
= INT_MIN
);
487 //! Attempts to find and return a modal child of this window, recursively.
488 Client
*findModalChild(Client
*skip
= 0) const;
490 //! Removes or reapplies the client's border to its window
492 Used when managing and unmanaging a window.
493 @param addborder true if adding the border to the client; false if removing
496 void toggleClientBorder(bool addborder
);
498 //! Applies the states requested when the window mapped
500 This should be called only once, during the window mapping process. It
501 applies things like maximized, and fullscreen.
503 void applyStartupState();
507 //! Constructs a new Client object around a specified window id
509 BB @param window The window id that the Client class should handle
510 @param screen The screen on which the window resides
512 Client(int screen
, Window window
);
513 //! Destroys the Client object
517 //! Returns the screen on which the clien resides
518 inline int screen() const { return _screen
; }
520 //! Returns the window id that the Client object is handling
521 inline Window
window() const { return _window
; }
523 //! Returns the type of the window, one of the Client::WindowType values
524 inline WindowType
type() const { return _type
; }
525 //! Returns if the window should be treated as a normal window.
527 Some windows (desktops, docks, splash screens) have special rules applied
528 to them in a number of places regarding focus or user interaction.
530 inline bool normal() const {
531 return ! (_type
== Type_Desktop
|| _type
== Type_Dock
||
532 _type
== Type_Splash
);
535 //! Returns the desktop on which the window resides
537 This value is a 0-based index.<br>
538 A value of 0xffffffff indicates that the window exists on all desktops.
540 inline long desktop() const { return _desktop
; }
541 //! Returns the window's title
542 inline const otk::ustring
&title() const { return _title
; }
543 //! Returns the window's title when it is iconified
544 inline const otk::ustring
&iconTitle() const { return _title
; }
545 //! Returns the application's name to whom the window belongs
546 inline const std::string
&appName() const { return _app_name
; }
547 //! Returns the class of the window
548 inline const std::string
&appClass() const { return _app_class
; }
549 //! Returns the program-specified role of the window
550 inline const std::string
&role() const { return _role
; }
551 //! Returns if the window can be focused
553 @return true if the window can receive focus; otherwise, false
555 inline bool canFocus() const { return _can_focus
; }
556 //! Returns if the window has indicated that it needs urgent attention
557 inline bool urgent() const { return _urgent
; }
558 //! Returns if the window wants to be notified when it receives focus
559 inline bool focusNotify() const { return _focus_notify
; }
560 //! Returns if the window is the focused window
561 inline bool focused() const { return _focused
; }
562 //! Returns if the window uses the Shape extension
563 inline bool shaped() const { return _shaped
; }
564 //! Returns the window's gravity
566 This value determines where to place the decorated window in relation to
567 its position without decorations.<br>
568 One of: NorthWestGravity, SouthWestGravity, EastGravity, ...,
569 SouthGravity, StaticGravity, ForgetGravity
571 inline int gravity() const { return _gravity
; }
572 //! Returns if the application requested the initial position for the window
574 If the application did not request a position (this function returns false)
575 then the window should be placed intelligently by the window manager
578 inline bool positionRequested() const { return _positioned
; }
579 //! Returns the decorations that the client window wishes to be displayed on
581 inline DecorationFlags
decorations() const { return _decorations
; }
582 //! Returns the decorations that the user has requested to be disabled on the
584 inline DecorationFlags
disabledDecorations() const
585 { return _disabled_decorations
; }
586 //! Returns the functions that the user can perform on the window
587 inline FunctionFlags
funtions() const { return _functions
; }
589 //! Return the client this window is transient for
590 inline Client
*transientFor() const { return _transient_for
; }
592 //! Returns the window which is a modal child of this window
593 inline Client
*modalChild() const { return _modal_child
; }
595 //! Returns if the window is modal
597 If the window is modal, then no other windows that it is related to can get
598 focus while it exists/remains modal.
600 inline bool modal() const { return _modal
; }
601 //! The window should not be displayed by pagers
602 inline bool skipPager() const { return _skip_pager
; }
603 //! The window should not be displayed by taskbars
604 inline bool skipTaskbar() const { return _skip_taskbar
; }
605 //! Returns if the window is shaded
607 When the window is shaded, only its titlebar is visible.
609 inline bool shaded() const { return _shaded
; }
610 //! Returns if the window is in fullscreen mode
611 inline bool fullscreen() const { return _fullscreen
; }
612 //! Returns if the window is iconified
614 When the window is iconified, it is not visible at all (except in iconbars/
615 panels/etc that want to show lists of iconified windows
617 inline bool iconic() const { return _iconic
; }
618 //! Returns if the window is maximized vertically
619 inline bool maxVert() const { return _max_vert
; }
620 //! Returns if the window is maximized horizontally
621 inline bool maxHorz() const { return _max_horz
; }
622 //! Returns the window's stacking layer
623 inline StackLayer
layer() const { return _layer
; }
625 //! Returns the logical size of the window
627 The "logical" size of the window is refers to the user's perception of the
628 size of the window, and is the value that should be displayed to the user.
629 For example, with xterms, this value it the number of characters being
630 displayed in the terminal, instead of the number of pixels.
632 const otk::Point
&logicalSize() const { return _logical_size
; }
634 //! Returns the position and size of the client relative to the root window
635 inline const otk::Rect
&area() const { return _area
; }
637 //! Returns the client's strut definition
638 inline const otk::Strut
&strut() const { return _strut
; }
640 //! Move the window (actually, its frame) to a position.
642 This moves the window so that the top-left corner of its frame will be at
643 the position specified.
644 @param x The X coordinate to move to.
645 @param y The Y coordinate to move to.
647 void move(int x
, int y
);
649 //! Resizes the client window, anchoring it in a given corner
651 This also maintains things like the client's minsize, and size increments.
652 @param anchor The corner to keep in the same position when resizing.
653 @param w The width component of the new size for the client.
654 @param h The height component of the new size for the client.
656 void resize(Corner anchor
, int w
, int h
);
658 //! Reapplies the maximized state to the window
660 Use this to make the window readjust its maximized size to new
661 surroundings (struts, etc).
665 //! Choose a mask of decorations to not display on the client
667 Pass a value of 0 to the function to turn all decorations back on. Note
668 that you cannot add decorations to a window with this, you can only remove
669 decorations that would otherwise have been displayed.
670 @param flags The mask of values from Client::Decoration to specify which
671 decorations should not be displayed.
673 void disableDecorations(DecorationFlags flags
);
675 //! Attempt to focus the client window
678 //! Remove focus from the client window
679 void unfocus() const;
681 //! Validate client, by making sure no Destroy or Unmap events exist in
682 //! the event queue for the window.
684 @return true if the client is valid; false if the client has already
685 been unmapped/destroyed, and so is invalid.
687 bool validate() const;
689 void installColormap(bool install
) const;
691 virtual void focusHandler(const XFocusChangeEvent
&e
);
692 virtual void unfocusHandler(const XFocusChangeEvent
&e
);
693 virtual void propertyHandler(const XPropertyEvent
&e
);
694 virtual void clientMessageHandler(const XClientMessageEvent
&e
);
695 virtual void configureRequestHandler(const XConfigureRequestEvent
&e
);
696 virtual void unmapHandler(const XUnmapEvent
&e
);
697 virtual void destroyHandler(const XDestroyWindowEvent
&e
);
698 virtual void reparentHandler(const XReparentEvent
&e
);
699 virtual void mapRequestHandler(const XMapRequestEvent
&e
);
701 virtual void shapeHandler(const XShapeEvent
&e
);
704 friend void Screen::manageWindow(Window
);
705 friend void Screen::unmanageWindow(Client
*);
710 #endif // __client_hh