add a bunch of documentation
[mikachu/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 extern "C" {
6 #include <X11/Xlib.h>
7 }
8
9 #include <string>
10
11 #include "otk/strut.hh"
12 #include "otk/rect.hh"
13
14 namespace ob {
15
16 //! Maintains the state of a client window.
17 /*!
18   OBClient maintains the state of a client window. The state consists of the
19   hints that the application sets on the window, such as the title, or window
20   gravity.
21   <p>
22   OBClient also manages client messages for the client window. When the
23   application (or any application) requests something to be changed for the
24   client, it will call the ActionHandler (for client messages) or update the
25   class' member variables and call whatever is nessary to complete the
26   change (such as causing a redraw of the titlebar after the title is changed).
27 */
28 class OBClient {
29 public:
30   //! Possible window types
31   enum WindowType { Type_Desktop, //!< A desktop (bottom-most window)
32                     Type_Dock,    //!< A dock bar/panel window
33                     Type_Toolbar, //!< A toolbar window, pulled off an app
34                     Type_Menu,    //!< A sticky menu from an app
35                     Type_Utility, //!< A small utility window such as a palette
36                     Type_Splash,  //!< A splash screen window
37                     Type_Dialog,  //!< A dialog window
38                     Type_Normal   //!< A normal application window
39   };
40
41   //! Possible flags for MWM Hints (defined by Motif 2.0)
42   enum MwmFlags { MwmFlag_Functions   = 1 << 0, //!< The MMW Hints define funcs
43                   MwmFlag_Decorations = 1 << 1  //!< The MWM Hints define decor
44   };
45
46   //! Possible functions for MWM Hints (defined by Motif 2.0)
47   enum MwmFunctions { MwmFunc_All      = 1 << 0, //!< All functions
48                       MwmFunc_Resize   = 1 << 1, //!< Allow resizing
49                       MwmFunc_Move     = 1 << 2, //!< Allow moving
50                       MwmFunc_Iconify  = 1 << 3, //!< Allow to be iconfied
51                       MwmFunc_Maximize = 1 << 4  //!< Allow to be maximized
52                       //MwmFunc_Close    = 1 << 5 //!< Allow to be closed
53   };
54
55   //! Possible decorations for MWM Hints (defined by Motif 2.0)
56   enum MemDecorations { MwmDecor_All      = 1 << 0, //!< All decorations
57                         MwmDecor_Border   = 1 << 1, //!< Show a border
58                         MwmDecor_Handle   = 1 << 2, //!< Show a handle (bottom)
59                         MwmDecor_Title    = 1 << 3, //!< Show a titlebar
60                         //MwmDecor_Menu     = 1 << 4, //!< Show a menu
61                         MwmDecor_Iconify  = 1 << 5, //!< Show an iconify button
62                         MwmDecor_Maximize = 1 << 6  //!< Show a maximize button
63   };
64
65   //! The things the user can do to the client window
66   enum Function { Func_Resize   = 1 << 0, //!< Allow resizing
67                   Func_Move     = 1 << 1, //!< Allow moving
68                   Func_Iconify  = 1 << 2, //!< Allow to be iconified
69                   Func_Maximize = 1 << 3, //!< Allow to be maximized
70                   Func_Close    = 1 << 4  //!< Allow to be closed
71   };
72   //! Holds a bitmask of OBClient::Function values
73   typedef unsigned char FunctionFlags;
74
75   //! The decorations the client window wants to be displayed on it
76   enum Decoration { Decor_Titlebar = 1 << 0, //!< Display a titlebar
77                     Decor_Handle   = 1 << 1, //!< Display a handle (bottom)
78                     Decor_Border   = 1 << 2, //!< Display a border
79                     Decor_Iconify  = 1 << 3, //!< Display an iconify button
80                     Decor_Maximize = 1 << 4, //!< Display a maximize button
81                     Decor_Close    = 1 << 5  //!< Display a close button
82   };
83   //! Holds a bitmask of OBClient::Decoration values
84   typedef unsigned char DecorationFlags;
85
86   //! The MWM Hints as retrieved from the window property
87   /*!
88     This structure only contains 3 elements, even though the Motif 2.0
89     structure contains 5. We only use the first 3, so that is all gets defined.
90   */
91   typedef struct MwmHints {
92     //! The number of elements in the OBClient::MwmHints struct
93     static const unsigned int elements = 3;
94     unsigned long flags;      //!< A bitmask of OBClient::MwmFlags values
95     unsigned long functions;  //!< A bitmask of OBClient::MwmFunctions values
96     unsigned long decorations;//!< A bitmask of OBClient::MwmDecorations values
97   };
98
99   //! Possible actions that can be made with the _NET_WM_STATE client message
100   enum StateAction { State_Remove = 0, //!< _NET_WM_STATE_REMOVE
101                      State_Add,        //!< _NET_WM_STATE_ADD
102                      State_Toggle      //!< _NET_WM_STATE_TOGGLE
103   };
104
105 private:
106   //! The actual window that this class is wrapping up
107   Window   _window;
108
109   //! The id of the group the window belongs to
110   Window   _group;
111
112   // XXX: transient_for, transients
113
114   //! The desktop on which the window resides (0xffffffff for all desktops)
115   unsigned long _desktop;
116
117   //! Normal window title
118   std::string  _title; // XXX: Have to keep track if this string is Utf8 or not
119   //! Window title when iconifiged
120   std::string  _icon_title;
121
122   //! The application that created the window
123   std::string  _app_name;
124   //! The class of the window, can used for grouping
125   std::string  _app_class;
126
127   //! The type of window (what its function is)
128   WindowType   _type;
129
130   //! Position and size of the window (relative to the root window)
131   otk::Rect    _area;
132
133   //! Width of the border on the window.
134   /*!
135     The window manager will set this to 0 while the window is being managed,
136     but needs to restore it afterwards, so it is saved here.
137   */
138   int _border_width;
139
140   //! The minimum width of the client window
141   /*!
142     If the min is > the max, then the window is not resizable
143   */
144   int _min_x;
145   //! The minimum height of the client window
146   /*!
147     If the min is > the max, then the window is not resizable
148   */
149   int _min_y;
150   //! The maximum width of the client window
151   /*!
152     If the min is > the max, then the window is not resizable
153   */
154   int _max_x;
155   //! The maximum height of the client window
156   /*!
157     If the min is > the max, then the window is not resizable
158   */
159   int _max_y;
160   //! The size of increments to resize the client window by (for the width)
161   int _inc_x;
162   //! The size of increments to resize the client window by (for the height)
163   int _inc_y;
164   //! The base width of the client window
165   /*!
166     This value should be subtracted from the window's actual width when
167     displaying its size to the user, or working with its min/max width
168   */
169   int _base_x;
170   //! The base height of the client window
171   /*!
172     This value should be subtracted from the window's actual height when
173     displaying its size to the user, or working with its min/max height
174   */
175   int _base_y;
176
177   //! Where to place the decorated window in relation to the undecorated window
178   int _gravity;
179
180   //! The state of the window, one of WithdrawnState, IconicState, or
181   //! NormalState
182   long _wmstate;
183
184   //! Was the window's position requested by the application? if not, we should
185   //! place the window ourselves when it first appears
186   bool _positioned;
187   
188   //! Can the window receive input focus?
189   bool _can_focus;
190   //! Urgency flag
191   bool _urgent;
192   //! Notify the window when it receives focus?
193   bool _focus_notify;
194
195   //! The window uses shape extension to be non-rectangular?
196   bool _shaped;
197
198   //! The window is modal, so it must be processed before any windows it is
199   //! related to can be focused
200   bool _modal;
201   //! Only the window's titlebar is displayed
202   bool _shaded;
203   //! The window is iconified
204   bool _iconic;
205   //! The window is maximized to fill the screen vertically
206   bool _max_vert;
207   //! The window is maximized to fill the screen horizontally
208   bool _max_horz;
209   //! The window is a 'fullscreen' window, and should be on top of all others
210   bool _fullscreen;
211   //! The window should be on top of other windows of the same type
212   bool _floating;
213
214   //! A bitmask of values in the OBClient::Decoration enum
215   /*!
216     The values in the variable are the decorations that the client wants to be
217     displayed around it.
218   */
219   DecorationFlags _decorations;
220
221   //! A bitmask of values in the OBClient::Function enum
222   /*!
223     The values in the variable specify the ways in which the user is allowed to
224     modify this window.
225   */
226   FunctionFlags _functions;
227
228   //! Retrieves the desktop hint's value and sets OBClient::_desktop
229   void getDesktop();
230   //! Retrieves the window's type and sets OBClient::_type
231   void getType();
232   //! Gets the MWM Hints and adjusts OBClient::_functions and
233   //! OBClient::_decorations
234   void getMwmHints();
235   //! Gets the position and size of the window and sets OBClient::_area
236   void getArea();
237   //! Gets the net_state hint and sets the boolean flags for any states set in
238   //! the hint
239   void getState();
240   //! Determines if the window uses the Shape extension and sets
241   //! OBClient::_shaped
242   void getShaped();
243
244   //! Sets the wm_state to the specified value
245   void setWMState(long state);
246   //! Sends the window to the specified desktop
247   void setDesktop(long desktop);
248   //! Adjusts the window's net_state
249   void setState(StateAction action, long data1, long data2);
250
251   //! Update the protocols that the window supports and adjusts things if they
252   //! change
253   void updateProtocols();
254   //! Updates the WMNormalHints and adjusts things if they change
255   void updateNormalHints();
256   //! Updates the WMHints and adjusts things if they change
257   void updateWMHints();
258   //! Updates the window's title
259   void updateTitle();
260   //! Updates the window's icon title
261   void updateIconTitle();
262   //! Updates the window's application name and class
263   void updateClass();
264   // XXX: updateTransientFor();
265
266 public:
267   OBClient(Window window);
268   virtual ~OBClient();
269
270   inline Window window() const { return _window; }
271
272   inline WindowType type() const { return _type; }
273   inline unsigned long desktop() const { return _desktop; }
274   inline const std::string &title() const { return _title; }
275   inline const std::string &iconTitle() const { return _title; }
276   inline const std::string &appName() const { return _app_name; }
277   inline const std::string &appClass() const { return _app_class; }
278   inline bool canFocus() const { return _can_focus; }
279   inline bool urgent() const { return _urgent; }
280   inline bool focusNotify() const { return _focus_notify; }
281   inline bool shaped() const { return _shaped; }
282   inline int gravity() const { return _gravity; }
283   inline bool positionRequested() const { return _positioned; }
284   inline DecorationFlags decorations() const { return _decorations; }
285   inline FunctionFlags funtions() const { return _functions; }
286
287   // states
288   inline bool modal() const { return _modal; }
289   inline bool shaded() const { return _shaded; }
290   inline bool iconic() const { return _iconic; }
291   inline bool maxVert() const { return _max_vert; }
292   inline bool maxHorz() const { return _max_horz; }
293   inline bool fullscreen() const { return _fullscreen; }
294   inline bool floating() const { return _floating; }
295
296   inline int borderWidth() const { return _border_width; }
297   inline int minX() const { return _min_x; }
298   inline int minY() const { return _min_y; }
299   inline int maxX() const { return _max_x; }
300   inline int maxY() const { return _max_y; }
301   inline int incrementX() const { return _inc_x; }
302   inline int incrementY() const { return _inc_y; }
303   inline int baseX() const { return _base_x; }
304   inline int baseY() const { return _base_y; }
305
306   inline const otk::Rect &area() const { return _area; }
307
308   void update(const XPropertyEvent &e);
309   void update(const XClientMessageEvent &e);
310
311   void setArea(const otk::Rect &area);
312 };
313
314 }
315
316 #endif // __client_hh