M src/client.hh → src/client.hh

@@ -13,70 +13,93 @@ #include "otk/rect.hh"
 
 namespace ob {
 
+//! Maintains the state of a client window.
+/*!
+  OBClient maintains the state of a client window. The state consists of the
+  hints that the application sets on the window, such as the title, or window
+  gravity.
+  <p>
+  OBClient also manages client messages for the client window. When the
+  application (or any application) requests something to be changed for the
+  client, it will call the ActionHandler (for client messages) or update the
+  class' member variables and call whatever is nessary to complete the
+  change (such as causing a redraw of the titlebar after the title is changed).
+*/
 class OBClient {
 public:
-  enum Max { Max_None,
-             Max_Horz,
-             Max_Vert,
-             Max_Full };
+  //! Possible window types
+  enum WindowType { Type_Desktop, //!< A desktop (bottom-most window)
+                    Type_Dock,    //!< A dock bar/panel window
+                    Type_Toolbar, //!< A toolbar window, pulled off an app
+                    Type_Menu,    //!< A sticky menu from an app
+                    Type_Utility, //!< A small utility window such as a palette
+                    Type_Splash,  //!< A splash screen window
+                    Type_Dialog,  //!< A dialog window
+                    Type_Normal   //!< A normal application window
+  };
 
-  enum WindowType { Type_Desktop,
-                    Type_Dock,
-                    Type_Toolbar,
-                    Type_Menu,
-                    Type_Utility,
-                    Type_Splash,
-                    Type_Dialog,
-                    Type_Normal };
+  //! Possible flags for MWM Hints (defined by Motif 2.0)
+  enum MwmFlags { MwmFlag_Functions   = 1 << 0, //!< The MMW Hints define funcs
+                  MwmFlag_Decorations = 1 << 1  //!< The MWM Hints define decor
+  };
 
-  enum MwmFlags { MwmFlag_Functions   = 1 << 0,
-                  MwmFlag_Decorations = 1 << 1 };
+  //! Possible functions for MWM Hints (defined by Motif 2.0)
+  enum MwmFunctions { MwmFunc_All      = 1 << 0, //!< All functions
+                      MwmFunc_Resize   = 1 << 1, //!< Allow resizing
+                      MwmFunc_Move     = 1 << 2, //!< Allow moving
+                      MwmFunc_Iconify  = 1 << 3, //!< Allow to be iconfied
+                      MwmFunc_Maximize = 1 << 4  //!< Allow to be maximized
+                      //MwmFunc_Close    = 1 << 5 //!< Allow to be closed
+  };
 
-  enum MwmFunctions { MwmFunc_All      = 1 << 0,
-                      MwmFunc_Resize   = 1 << 1,
-                      MwmFunc_Move     = 1 << 2,
-                      MwmFunc_Iconify  = 1 << 3,
-                      MwmFunc_Maximize = 1 << 4
-                      //MwmFunc_Close    = 1 << 5
+  //! Possible decorations for MWM Hints (defined by Motif 2.0)
+  enum MemDecorations { MwmDecor_All      = 1 << 0, //!< All decorations
+                        MwmDecor_Border   = 1 << 1, //!< Show a border
+                        MwmDecor_Handle   = 1 << 2, //!< Show a handle (bottom)
+                        MwmDecor_Title    = 1 << 3, //!< Show a titlebar
+                        //MwmDecor_Menu     = 1 << 4, //!< Show a menu
+                        MwmDecor_Iconify  = 1 << 5, //!< Show an iconify button
+                        MwmDecor_Maximize = 1 << 6  //!< Show a maximize button
   };
 
-  enum MemDecorations { MwmDecor_All      = 1 << 0,
-                        MwmDecor_Border   = 1 << 1,
-                        MwmDecor_Handle   = 1 << 2,
-                        MwmDecor_Title    = 1 << 3,
-                        //MwmDecor_Menu     = 1 << 4,
-                        MwmDecor_Iconify  = 1 << 5,
-                        MwmDecor_Maximize = 1 << 6 };
-
-  // the things the user can do to the client window
-  enum Function { Func_Resize   = 1 << 0,
-                  Func_Move     = 1 << 1,
-                  Func_Iconify  = 1 << 2,
-                  Func_Maximize = 1 << 3,
-                  Func_Close    = 1 << 4 };
+  //! The things the user can do to the client window
+  enum Function { Func_Resize   = 1 << 0, //!< Allow resizing
+                  Func_Move     = 1 << 1, //!< Allow moving
+                  Func_Iconify  = 1 << 2, //!< Allow to be iconified
+                  Func_Maximize = 1 << 3, //!< Allow to be maximized
+                  Func_Close    = 1 << 4  //!< Allow to be closed
+  };
+  //! Holds a bitmask of OBClient::Function values
   typedef unsigned char FunctionFlags;
 
-  // the decorations the client window wants to be displayed on it
-  enum Decoration { Decor_Titlebar = 1 << 0,
-                    Decor_Handle   = 1 << 1,
-                    Decor_Border   = 1 << 2,
-                    Decor_Iconify  = 1 << 3,
-                    Decor_Maximize = 1 << 4,
-                    Decor_Close    = 1 << 5 };
+  //! The decorations the client window wants to be displayed on it
+  enum Decoration { Decor_Titlebar = 1 << 0, //!< Display a titlebar
+                    Decor_Handle   = 1 << 1, //!< Display a handle (bottom)
+                    Decor_Border   = 1 << 2, //!< Display a border
+                    Decor_Iconify  = 1 << 3, //!< Display an iconify button
+                    Decor_Maximize = 1 << 4, //!< Display a maximize button
+                    Decor_Close    = 1 << 5  //!< Display a close button
+  };
+  //! Holds a bitmask of OBClient::Decoration values
   typedef unsigned char DecorationFlags;
 
-  // this structure only contains 3 elements... the Motif 2.0 structure
-  // contains 5... we only need the first 3... so that is all we will define
+  //! The MWM Hints as retrieved from the window property
+  /*!
+    This structure only contains 3 elements, even though the Motif 2.0
+    structure contains 5. We only use the first 3, so that is all gets defined.
+  */
   typedef struct MwmHints {
+    //! The number of elements in the OBClient::MwmHints struct
     static const unsigned int elements = 3;
-    unsigned long flags;
-    unsigned long functions;
-    unsigned long decorations;
+    unsigned long flags;      //!< A bitmask of OBClient::MwmFlags values
+    unsigned long functions;  //!< A bitmask of OBClient::MwmFunctions values
+    unsigned long decorations;//!< A bitmask of OBClient::MwmDecorations values
   };
 
-  enum StateAction { State_Remove = 0, // _NET_WM_STATE_REMOVE
-                     State_Add,        // _NET_WM_STATE_ADD
-                     State_Toggle      // _NET_WM_STATE_TOGGLE
+  //! Possible actions that can be made with the _NET_WM_STATE client message
+  enum StateAction { State_Remove = 0, //!< _NET_WM_STATE_REMOVE
+                     State_Add,        //!< _NET_WM_STATE_ADD
+                     State_Toggle      //!< _NET_WM_STATE_TOGGLE
   };
 
 private:
@@ -114,12 +137,42 @@ but needs to restore it afterwards, so it is saved here.
   */
   int _border_width;
 
-  // size bounds
-  // if min > max, then the window is not resizable
-  int _min_x, _min_y; // minumum size
-  int _max_x, _max_y; // maximum size
-  int _inc_x, _inc_y; // resize increments
-  int _base_x, _base_y; // base size
+  //! The minimum width of the client window
+  /*!
+    If the min is > the max, then the window is not resizable
+  */
+  int _min_x;
+  //! The minimum height of the client window
+  /*!
+    If the min is > the max, then the window is not resizable
+  */
+  int _min_y;
+  //! The maximum width of the client window
+  /*!
+    If the min is > the max, then the window is not resizable
+  */
+  int _max_x;
+  //! The maximum height of the client window
+  /*!
+    If the min is > the max, then the window is not resizable
+  */
+  int _max_y;
+  //! The size of increments to resize the client window by (for the width)
+  int _inc_x;
+  //! The size of increments to resize the client window by (for the height)
+  int _inc_y;
+  //! The base width of the client window
+  /*!
+    This value should be subtracted from the window's actual width when
+    displaying its size to the user, or working with its min/max width
+  */
+  int _base_x;
+  //! The base height of the client window
+  /*!
+    This value should be subtracted from the window's actual height when
+    displaying its size to the user, or working with its min/max height
+  */
+  int _base_y;
 
   //! Where to place the decorated window in relation to the undecorated window
   int _gravity;
@@ -172,23 +225,43 @@ modify this window.
   */
   FunctionFlags _functions;
 
+  //! Retrieves the desktop hint's value and sets OBClient::_desktop
   void getDesktop();
+  //! Retrieves the window's type and sets OBClient::_type
   void getType();
+  //! Gets the MWM Hints and adjusts OBClient::_functions and
+  //! OBClient::_decorations
   void getMwmHints();
+  //! Gets the position and size of the window and sets OBClient::_area
   void getArea();
+  //! Gets the net_state hint and sets the boolean flags for any states set in
+  //! the hint
   void getState();
+  //! Determines if the window uses the Shape extension and sets
+  //! OBClient::_shaped
   void getShaped();
 
+  //! Sets the wm_state to the specified value
   void setWMState(long state);
+  //! Sends the window to the specified desktop
   void setDesktop(long desktop);
+  //! Adjusts the window's net_state
   void setState(StateAction action, long data1, long data2);
 
+  //! Update the protocols that the window supports and adjusts things if they
+  //! change
   void updateProtocols();
+  //! Updates the WMNormalHints and adjusts things if they change
   void updateNormalHints();
+  //! Updates the WMHints and adjusts things if they change
   void updateWMHints();
-  // XXX: updateTransientFor();
+  //! Updates the window's title
   void updateTitle();
+  //! Updates the window's icon title
+  void updateIconTitle();
+  //! Updates the window's application name and class
   void updateClass();
+  // XXX: updateTransientFor();
 
 public:
   OBClient(Window window);