support for modal children, both in the focus code and in the raise/lower code
[dana/openbox.git] / src / client.hh
1 // -*- mode: C++; indent-tabs-mode: nil; c-basic-offset: 2; -*-
2 #ifndef   __client_hh
3 #define   __client_hh
4
5 /*! @file client.hh
6   @brief The Client class maintains the state of a client window by handling
7   property changes on the window and some client messages
8 */
9
10 #include "widgetbase.hh"
11 #include "otk/point.hh"
12 #include "otk/strut.hh"
13 #include "otk/rect.hh"
14 #include "otk/eventhandler.hh"
15 #include "otk/ustring.hh"
16
17 extern "C" {
18 #include <X11/Xlib.h>
19
20 #ifdef    SHAPE
21 #include <X11/extensions/shape.h>
22 #endif // SHAPE
23 }
24
25 #include <string>
26 #include <list>
27
28 namespace ob {
29
30 class Frame;
31
32 //! The MWM Hints as retrieved from the window property
33 /*!
34   This structure only contains 3 elements, even though the Motif 2.0
35   structure contains 5. We only use the first 3, so that is all gets defined.
36 */
37 struct MwmHints {
38   unsigned long flags;      //!< A bitmask of Client::MwmFlags values
39   unsigned long functions;  //!< A bitmask of Client::MwmFunctions values
40   unsigned long decorations;//!< A bitmask of Client::MwmDecorations values
41   //! The number of elements in the Client::MwmHints struct
42   static const unsigned int elements = 3;
43 };
44
45 //! Maintains the state of a client window.
46 /*!
47   Client maintains the state of a client window. The state consists of the
48   hints that the application sets on the window, such as the title, or window
49   gravity.
50   <p>
51   Client also manages client messages for the client window. When the
52   application (or any application) requests something to be changed for the
53   client, it will call the ActionHandler (for client messages) or update the
54   class' member variables and call whatever is nessary to complete the
55   change (such as causing a redraw of the titlebar after the title is changed).
56 */
57 class Client : public otk::EventHandler, public WidgetBase {
58 public:
59
60   //! The frame window which decorates around the client window
61   /*!
62     NOTE: This should NEVER be used inside the client class's constructor!
63   */
64   Frame *frame;
65
66   //! Holds a list of Clients
67   typedef std::list<Client*> List;
68
69   //! The possible stacking layers a client window can be a part of
70   enum StackLayer {
71     Layer_Icon,       //!< 0 - iconified windows, in any order at all
72     Layer_Desktop,    //!< 1 - desktop windows
73     Layer_Below,      //!< 2 - normal windows w/ below
74     Layer_Normal,     //!< 3 - normal windows
75     Layer_Above,      //!< 4 - normal windows w/ above
76     Layer_Top,        //!< 5 - always-on-top-windows (docks?)
77     Layer_Fullscreen, //!< 6 - fullscreeen windows
78     Layer_Internal,   //!< 7 - openbox windows/menus
79     NUM_LAYERS
80   };
81
82   //! Corners of the client window, used for anchor positions
83   enum Corner { TopLeft,
84                 TopRight,
85                 BottomLeft,
86                 BottomRight };
87
88   //! Possible window types
89   enum WindowType { Type_Desktop, //!< A desktop (bottom-most window)
90                     Type_Dock,    //!< A dock bar/panel window
91                     Type_Toolbar, //!< A toolbar window, pulled off an app
92                     Type_Menu,    //!< An unpinned menu from an app
93                     Type_Utility, //!< A small utility window such as a palette
94                     Type_Splash,  //!< A splash screen window
95                     Type_Dialog,  //!< A dialog window
96                     Type_Normal   //!< A normal application window
97   };
98
99   //! Possible flags for MWM Hints (defined by Motif 2.0)
100   enum MwmFlags { MwmFlag_Functions   = 1 << 0, //!< The MMW Hints define funcs
101                   MwmFlag_Decorations = 1 << 1  //!< The MWM Hints define decor
102   };
103
104   //! Possible functions for MWM Hints (defined by Motif 2.0)
105   enum MwmFunctions { MwmFunc_All      = 1 << 0, //!< All functions
106                       MwmFunc_Resize   = 1 << 1, //!< Allow resizing
107                       MwmFunc_Move     = 1 << 2, //!< Allow moving
108                       MwmFunc_Iconify  = 1 << 3, //!< Allow to be iconfied
109                       MwmFunc_Maximize = 1 << 4  //!< Allow to be maximized
110                       //MwmFunc_Close    = 1 << 5 //!< Allow to be closed
111   };
112
113   //! Possible decorations for MWM Hints (defined by Motif 2.0)
114   enum MemDecorations { MwmDecor_All      = 1 << 0, //!< All decorations
115                         MwmDecor_Border   = 1 << 1, //!< Show a border
116                         MwmDecor_Handle   = 1 << 2, //!< Show a handle (bottom)
117                         MwmDecor_Title    = 1 << 3, //!< Show a titlebar
118                         //MwmDecor_Menu     = 1 << 4, //!< Show a menu
119                         MwmDecor_Iconify  = 1 << 5, //!< Show an iconify button
120                         MwmDecor_Maximize = 1 << 6  //!< Show a maximize button
121   };
122
123   //! The things the user can do to the client window
124   enum Function { Func_Resize     = 1 << 0, //!< Allow resizing
125                   Func_Move       = 1 << 1, //!< Allow moving
126                   Func_Iconify    = 1 << 2, //!< Allow to be iconified
127                   Func_Maximize   = 1 << 3, //!< Allow to be maximized
128                   Func_Shade      = 1 << 4, //!< Allow to be shaded
129                   Func_Fullscreen = 1 << 5, //!< Allow to be made fullscreen
130                   Func_Close      = 1 << 6  //!< Allow to be closed
131   };
132   //! Holds a bitmask of Client::Function values
133   typedef unsigned char FunctionFlags;
134
135   //! The decorations the client window wants to be displayed on it
136   enum Decoration { Decor_Titlebar    = 1 << 0, //!< Display a titlebar
137                     Decor_Handle      = 1 << 1, //!< Display a handle (bottom)
138                     Decor_Border      = 1 << 2, //!< Display a border
139                     Decor_Iconify     = 1 << 3, //!< Display an iconify button
140                     Decor_Maximize    = 1 << 4, //!< Display a maximize button
141                     //! Display a button to toggle the window's placement on
142                     //! all desktops
143                     Decor_AllDesktops = 1 << 5,
144                     Decor_Close       = 1 << 6  //!< Display a close button
145   };
146   //! Holds a bitmask of Client::Decoration values
147   typedef unsigned char DecorationFlags;
148
149   //! Possible actions that can be made with the _NET_WM_STATE client message
150   enum StateAction { State_Remove = 0, //!< _NET_WM_STATE_REMOVE
151                      State_Add,        //!< _NET_WM_STATE_ADD
152                      State_Toggle      //!< _NET_WM_STATE_TOGGLE
153   };
154
155   //! The event mask to grab on client windows
156   static const long event_mask = PropertyChangeMask | FocusChangeMask |
157                                  StructureNotifyMask;
158
159   //! The mask of events to not let propogate past the client
160   /*!
161     This makes things like xprop work on the client window, but means we have
162     to explicitly grab clicks that we want.
163   */
164   static const long no_propagate_mask = ButtonPressMask | ButtonReleaseMask |
165                                         ButtonMotionMask;
166
167   //! The desktop value which indicated the window is iconified and not on any
168   //! desktop
169   static const long ICONIC_DESKTOP = 0xfffffffe;
170
171   //! The number of unmap events to ignore on the window
172   int ignore_unmaps;
173   
174 private:
175   //! The screen number on which the client resides
176   int      _screen;
177   
178   //! The actual window that this class is wrapping up
179   Window   _window;
180
181   //! The id of the group the window belongs to
182   Window   _group;
183
184   //! The client which this client is a transient (child) for
185   Client *_transient_for;
186
187   //! The clients which are transients (children) of this client
188   Client::List _transients;
189
190   //! The desktop on which the window resides (0xffffffff for all desktops)
191   long _desktop;
192
193   //! Normal window title
194   otk::ustring  _title;
195   //! Window title when iconifiged
196   otk::ustring  _icon_title;
197
198   //! The application that created the window
199   std::string  _app_name;
200   //! The class of the window, can used for grouping
201   std::string  _app_class;
202   //! The specified role of the window, used for identification
203   std::string  _role;
204
205   //! The type of window (what its function is)
206   WindowType   _type;
207
208   //! Position and size of the window
209   /*!
210     This will not always be the actual position of the window on screen, it is
211     rather, the position requested by the client, to which the window's gravity
212     is applied.
213   */
214   otk::Rect    _area;
215
216   //! The window's strut
217   /*!
218     The strut defines areas of the screen that are marked off-bounds for window
219     placement. In theory, where this window exists.
220   */
221   otk::Strut   _strut;
222
223   //! The logical size of the window
224   /*!
225     The "logical" size of the window is refers to the user's perception of the
226     size of the window, and is the value that should be displayed to the user.
227     For example, with xterms, this value it the number of characters being
228     displayed in the terminal, instead of the number of pixels.
229   */
230   otk::Point   _logical_size;
231
232   //! Width of the border on the window.
233   /*!
234     The window manager will set this to 0 while the window is being managed,
235     but needs to restore it afterwards, so it is saved here.
236   */
237   int _border_width;
238
239   //! The minimum aspect ratio the client window can be sized to.
240   /*!
241     A value of 0 means this is ignored.
242   */
243   float _min_ratio;
244   //! The maximum aspect ratio the client window can be sized to.
245   /*!
246     A value of 0 means this is ignored.
247   */
248   float _max_ratio;
249   
250   //! The minimum size of the client window
251   /*!
252     If the min is > the max, then the window is not resizable
253   */
254   otk::Point _min_size;
255   //! The maximum size of the client window
256   /*!
257     If the min is > the max, then the window is not resizable
258   */
259   otk::Point _max_size;
260   //! The size of increments to resize the client window by
261   otk::Point _size_inc;
262   //! The base size of the client window
263   /*!
264     This value should be subtracted from the window's actual size when
265     displaying its size to the user, or working with its min/max size
266   */
267   otk::Point _base_size;
268
269   //! Window decoration and functionality hints
270   MwmHints _mwmhints;
271   
272   //! Where to place the decorated window in relation to the undecorated window
273   int _gravity;
274
275   //! The state of the window, one of WithdrawnState, IconicState, or
276   //! NormalState
277   long _wmstate;
278
279   //! True if the client supports the delete_window protocol
280   bool _delete_window;
281   
282   //! Was the window's position requested by the application? if not, we should
283   //! place the window ourselves when it first appears
284   bool _positioned;
285   
286   //! Can the window receive input focus?
287   bool _can_focus;
288   //! Urgency flag
289   bool _urgent;
290   //! Notify the window when it receives focus?
291   bool _focus_notify;
292   //! Does the client window have the input focus?
293   bool _focused;
294
295   //! The window uses shape extension to be non-rectangular?
296   bool _shaped;
297
298   //! If the window has a modal child window, then this will point to it
299   Client *_modal_child;
300
301   //! The window is modal, so it must be processed before any windows it is
302   //! related to can be focused
303   bool _modal;
304   //! Only the window's titlebar is displayed
305   bool _shaded;
306   //! The window is iconified
307   bool _iconic;
308   //! The window is maximized to fill the screen vertically
309   bool _max_vert;
310   //! The window is maximized to fill the screen horizontally
311   bool _max_horz;
312   //! The window should not be displayed by pagers
313   bool _skip_pager;
314   //! The window should not be displayed by taskbars
315   bool _skip_taskbar;
316   //! The window is a 'fullscreen' window, and should be on top of all others
317   bool _fullscreen;
318   //! The window should be on top of other windows of the same type
319   bool _above;
320   //! The window should be underneath other windows of the same type
321   bool _below;
322
323   StackLayer _layer;
324
325   //! A bitmask of values in the Client::Decoration enum
326   /*!
327     The values in the variable are the decorations that the client wants to be
328     displayed around it.
329   */
330   DecorationFlags _decorations;
331
332   //! A bitmask of values in the Client::Decoration enum.
333   /*!
334     Specifies the decorations that should NOT be displayed on the client.
335   */
336   DecorationFlags _disabled_decorations;
337
338   //! A bitmask of values in the Client::Function enum
339   /*!
340     The values in the variable specify the ways in which the user is allowed to
341     modify this window.
342   */
343   FunctionFlags _functions;
344
345   //! Retrieves the window's initial gravity
346   void getGravity();
347   //! Retrieves the desktop hint's value and sets Client::_desktop
348   void getDesktop();
349   //! Retrieves the window's type and sets Client::_type
350   void getType();
351   //! Gets the MWM Hints and adjusts Client::_functions and
352   //! Client::_decorations
353   void getMwmHints();
354   //! Gets the position and size of the window and sets Client::_area
355   void getArea();
356   //! Gets the net_state hint and sets the boolean flags for any states set in
357   //! the hint
358   void getState();
359   //! Determines if the window uses the Shape extension and sets
360   //! Client::_shaped
361   void getShaped();
362
363   //! Set up what decor should be shown on the window and what functions should
364   //! be allowed (Client::_decorations and Client::_functions).
365   /*!
366     This also updates the NET_WM_ALLOWED_ACTIONS hint.
367   */
368   void setupDecorAndFunctions();
369   
370   //! Sets the wm_state to the specified value
371   void setWMState(long state);
372   //! Adjusts the window's net_state
373   /*!
374     This should not be called as part of the window mapping process! It is for
375     use when updating the state post-mapping.<br>
376     Client::applyStartupState is used to do the same things during the mapping
377     process.
378   */
379   void setState(StateAction action, long data1, long data2);
380
381   //! Sends the window to the specified desktop
382   /*!
383     A window is iconified by sending it to the ICONIC_DESKTOP, and restored
384     by sending it to any other valid desktop.
385   */
386   void setDesktop(long desktop);
387   //! Set whether the window is modal or not
388   /*!
389     This adjusts references in parents etc to match.
390   */
391   void setModal(bool modal);
392   
393   //! Calculates the stacking layer for the client window
394   void calcLayer();
395
396   //! Update the protocols that the window supports and adjusts things if they
397   //! change
398   void updateProtocols();
399   //! Updates the WMNormalHints and adjusts things if they change
400   void updateNormalHints();
401   //! Updates the WMHints and adjusts things if they change
402   /*!
403     @param initstate Whether to read the initial_state property from the
404                      WMHints. This should only be used during the mapping
405                      process.
406   */
407   void updateWMHints(bool initstate = false);
408   //! Updates the window's title
409   void updateTitle();
410   //! Updates the window's icon title
411   void updateIconTitle();
412   //! Updates the window's application name and class
413   void updateClass();
414   //! Updates the strut for the client
415   void updateStrut();
416   //! Updates the window's transient status, and any parents of it
417   void updateTransientFor();
418
419   //! Change the client's state hints to match the class' data
420   void changeState();
421   //! Change the allowed actions set on the client
422   void changeAllowedActions();
423
424   //! Request the client to close its window.
425   void close();
426
427   //! Shades or unshades the client window
428   /*!
429     @param shade true if the window should be shaded; false if it should be
430                  unshaded.
431   */
432   void shade(bool shade);
433
434   //! Fires the urgent callbacks which lets the user do what they want with
435   //! urgent windows
436   void fireUrgent();
437   
438   //! Fullscreen's or unfullscreen's the client window
439   /*!
440     @param fs true if the window should be made fullscreen; false if it should
441               be returned to normal state.
442     @param savearea true to have the client's current size and position saved;
443                     otherwise, they are not. You should not save when mapping a
444                     new window that is set to fullscreen.
445   */
446   void fullscreen(bool fs, bool savearea);
447
448   //! Maximize or unmaximize the client window
449   /*!
450     @param max true if the window should be maximized; false if it should be
451                returned to normal size.
452     @param dir 0 to set both horz and vert, 1 to set horz, 2 to set vert.
453     @param savearea true to have the client's current size and position saved;
454                     otherwise, they are not. You should not save when mapping a
455                     new window that is set to fullscreen.
456   */
457   void maximize(bool max, int dir, bool savearea);
458
459   //! Internal version of the Client::move function
460   /*!
461     @param x The X coordinate to move to.
462     @param y The Y coordinate to move to.
463   */
464   void internal_move(int x, int y);
465   //! Internal version of the Client::resize function
466   /*!
467     This also maintains things like the client's minsize, and size increments.
468     @param anchor The corner to keep in the same position when resizing.
469     @param w The width component of the new size for the client.
470     @param h The height component of the new size for the client.
471     @param user Specifies whether this is a user-requested change or a
472                 program requested change.
473     @param x An optional X coordinate to which the window will be moved
474              after resizing.
475     @param y An optional Y coordinate to which the window will be moved
476              after resizing.
477     The x and y coordinates must both be sepcified together, or they will have
478     no effect. When they are specified, the anchor is ignored.
479   */
480   void internal_resize(Corner anchor, int w, int h, bool user = true,
481                        int x = INT_MIN, int y = INT_MIN);
482
483   //! Attempts to find and return a modal child of this window, recursively.
484   Client *findModalChild(Client *skip = 0) const;
485
486 public:
487 #ifndef SWIG
488   //! Constructs a new Client object around a specified window id
489   /*!
490 BB    @param window The window id that the Client class should handle
491     @param screen The screen on which the window resides
492   */
493   Client(int screen, Window window);
494   //! Destroys the Client object
495   virtual ~Client();
496 #endif
497
498   //! Returns the screen on which the clien resides
499   inline int screen() const { return _screen; }
500   
501   //! Returns the window id that the Client object is handling
502   inline Window window() const { return _window; }
503
504   //! Returns the type of the window, one of the Client::WindowType values
505   inline WindowType type() const { return _type; }
506   //! Returns if the window should be treated as a normal window.
507   /*!
508     Some windows (desktops, docks, splash screens) have special rules applied
509     to them in a number of places regarding focus or user interaction.
510   */
511   inline bool normal() const {
512     return ! (_type == Type_Desktop || _type == Type_Dock ||
513               _type == Type_Splash);
514   }
515   
516   //! Returns the desktop on which the window resides
517   /*!
518     This value is a 0-based index.<br>
519     A value of 0xffffffff indicates that the window exists on all desktops.
520   */
521   inline long desktop() const { return _desktop; }
522   //! Returns the window's title
523   inline const otk::ustring &title() const { return _title; }
524   //! Returns the window's title when it is iconified
525   inline const otk::ustring &iconTitle() const { return _title; }
526   //! Returns the application's name to whom the window belongs
527   inline const std::string &appName() const { return _app_name; }
528   //! Returns the class of the window
529   inline const std::string &appClass() const { return _app_class; }
530   //! Returns the program-specified role of the window
531   inline const std::string &role() const { return _role; }
532   //! Returns if the window can be focused
533   /*!
534     @return true if the window can receive focus; otherwise, false
535   */
536   inline bool canFocus() const { return _can_focus; }
537   //! Returns if the window has indicated that it needs urgent attention
538   inline bool urgent() const { return _urgent; }
539   //! Returns if the window wants to be notified when it receives focus
540   inline bool focusNotify() const { return _focus_notify; }
541   //! Returns if the window uses the Shape extension
542   inline bool shaped() const { return _shaped; }
543   //! Returns the window's gravity
544   /*!
545     This value determines where to place the decorated window in relation to
546     its position without decorations.<br>
547     One of: NorthWestGravity, SouthWestGravity, EastGravity, ...,
548     SouthGravity, StaticGravity, ForgetGravity
549   */
550   inline int gravity() const { return _gravity; }
551   //! Returns if the application requested the initial position for the window
552   /*!
553     If the application did not request a position (this function returns false)
554     then the window should be placed intelligently by the window manager
555     initially
556   */
557   inline bool positionRequested() const { return _positioned; }
558   //! Returns the decorations that the client window wishes to be displayed on
559   //! it
560   inline DecorationFlags decorations() const { return _decorations; }
561   //! Returns the decorations that the user has requested to be disabled on the
562   //! client
563   inline DecorationFlags disabledDecorations() const
564     { return _disabled_decorations; }
565   //! Returns the functions that the user can perform on the window
566   inline FunctionFlags funtions() const { return _functions; }
567
568   //! Return the client this window is transient for
569   inline Client *transientFor() const { return _transient_for; }
570
571   //! Returns the window which is a modal child of this window
572   inline Client *modalChild() const { return _modal_child; }
573   
574   //! Returns if the window is modal
575   /*!
576     If the window is modal, then no other windows that it is related to can get
577     focus while it exists/remains modal.
578   */
579   inline bool modal() const { return _modal; }
580   //! The window should not be displayed by pagers
581   inline bool skipPager() const { return _skip_pager; }
582   //! The window should not be displayed by taskbars
583   inline bool skipTaskbar() const { return _skip_taskbar; } 
584  //! Returns if the window is shaded
585   /*!
586     When the window is shaded, only its titlebar is visible.
587   */
588   inline bool shaded() const { return _shaded; }
589   //! Returns if the window is in fullscreen mode
590   inline bool fullscreen() const { return _fullscreen; }
591   //! Returns if the window is iconified
592   /*!
593     When the window is iconified, it is not visible at all (except in iconbars/
594     panels/etc that want to show lists of iconified windows
595   */
596   inline bool iconic() const { return _iconic; }
597   //! Returns if the window is maximized vertically
598   inline bool maxVert() const { return _max_vert; }
599   //! Returns if the window is maximized horizontally
600   inline bool maxHorz() const { return _max_horz; }
601   //! Returns the window's stacking layer
602   inline StackLayer layer() const { return _layer; }
603
604   //! Returns the logical size of the window
605   /*!
606     The "logical" size of the window is refers to the user's perception of the
607     size of the window, and is the value that should be displayed to the user.
608     For example, with xterms, this value it the number of characters being
609     displayed in the terminal, instead of the number of pixels.
610   */
611   const otk::Point &logicalSize() const { return _logical_size; }
612
613   //! Applies the states requested when the window mapped
614   /*!
615     This should be called only once, during the window mapping process. It
616     applies things like maximized, and fullscreen.
617   */
618   void applyStartupState();
619   
620   //! Removes or reapplies the client's border to its window
621   /*!
622     Used when managing and unmanaging a window.
623     @param addborder true if adding the border to the client; false if removing
624                      from the client
625   */
626   void toggleClientBorder(bool addborder);
627
628   //! Returns the position and size of the client relative to the root window
629   inline const otk::Rect &area() const { return _area; }
630
631   //! Returns the client's strut definition
632   inline const otk::Strut &strut() const { return _strut; }
633
634   //! Move the window (actually, its frame) to a position.
635   /*!
636     This moves the window so that the top-left corner of its frame will be at
637     the position specified.
638     @param x The X coordinate to move to.
639     @param y The Y coordinate to move to.
640   */
641   void move(int x, int y);
642   
643   //! Resizes the client window, anchoring it in a given corner
644   /*!
645     This also maintains things like the client's minsize, and size increments.
646     @param anchor The corner to keep in the same position when resizing.
647     @param w The width component of the new size for the client.
648     @param h The height component of the new size for the client.
649   */
650   void resize(Corner anchor, int w, int h);
651
652   //! Reapplies the maximized state to the window
653   /*!
654     Use this to make the window readjust its maximized size to new
655     surroundings (struts, etc).
656   */
657   void remaximize();
658   
659   //! Choose a mask of decorations to not display on the client
660   /*!
661     Pass a value of 0 to the function to turn all decorations back on. Note
662     that you cannot add decorations to a window with this, you can only remove
663     decorations that would otherwise have been displayed.
664     @param flags The mask of values from Client::Decoration to specify which
665                  decorations should not be displayed.
666   */
667   void disableDecorations(DecorationFlags flags);
668   
669   //! Attempt to focus the client window
670   bool focus();
671
672   //! Remove focus from the client window
673   void unfocus() const;
674
675   //! Validate client, by making sure no Destroy or Unmap events exist in
676   //! the event queue for the window.
677   /*!
678     @return true if the client is valid; false if the client has already
679             been unmapped/destroyed, and so is invalid.
680   */
681   bool validate() const;
682
683   virtual void focusHandler(const XFocusChangeEvent &e);
684   virtual void unfocusHandler(const XFocusChangeEvent &e);
685   virtual void propertyHandler(const XPropertyEvent &e);
686   virtual void clientMessageHandler(const XClientMessageEvent &e);
687   virtual void configureRequestHandler(const XConfigureRequestEvent &e);
688   virtual void unmapHandler(const XUnmapEvent &e);
689   virtual void destroyHandler(const XDestroyWindowEvent &e);
690   virtual void reparentHandler(const XReparentEvent &e);
691   virtual void mapRequestHandler(const XMapRequestEvent &e);
692 #if defined(SHAPE)
693   virtual void shapeHandler(const XShapeEvent &e);
694 #endif // SHAPE 
695 };
696
697 }
698
699 #endif // __client_hh