documenting classes!

[chaz/openbox] / src / openbox.hh

diff --git a/src/openbox.hh b/src/openbox.hh
index 76a7d973786d8d9095859eb5d29385dfaa27e39c..a479a45d982238f41bbadfd748c799cb2939c119 100644 (file)
--- a/src/openbox.hh
+++ b/src/openbox.hh
@@ -14,39 +14,74 @@ extern "C" {
 
 namespace ob {
 
+//! The main class for the Openbox window manager.
+/*!
+  Only a single instance of the Openbox class may be used in the application. A
+  pointer to this instance is held in the Openbox::instance static member
+  variable.
+  Instantiation of this class begins the window manager. After instantiation,
+  the Openbox::eventLoop function should be called. The eventLoop method does
+  not exit until the window manager is ready to be destroyed. Destruction of
+  the Openbox class instance will shutdown the window manager.
+*/
 class Openbox
 {
 public:
-  static Openbox *instance;  // there can only be ONE instance of this class in
-                             // the program, and it is held in here
-
-  typedef std::vector<otk::ScreenInfo> ScreenInfoList;
+  //! The single instance of the Openbox class for the application.
+  /*!
+    Since this variable is globally available in the application, the Openbox
+    class does not need to be passed around to any of the other classes.
+  */
+  static Openbox *instance;
 
+  //! The posible running states of the window manager
   enum RunState {
+    //! The window manager is starting up (being created)
     State_Starting,
+    //! The window manager is running in its normal state
     State_Normal,
+    //! The window manager is exiting (being destroyed)
     State_Exiting
   };
   
 private:
   // stuff that can be passed on the command line
-  std::string _rcfilepath;   // path to the config file to use/in use
-  std::string _menufilepath; // path to the menu file to use/in use
-  char *_displayreq;         // display requested by the user
-  char *_argv0;              // argv[0], how the program was called
+  //! Path to the config file to use/in use
+  /*!
+    Defaults to $(HOME)/.openbox/rc3
+  */
+  std::string _rcfilepath;
+  //! Path to the menu file to use/in use
+  /*!
+    Defaults to $(HOME)/.openbox/menu3
+  */
+  std::string _menufilepath;
+  //! The display requested by the user, or null to use the DISPLAY env var
+  char *_displayreq;
+  //! The value of argv[0], i.e. how this application was executed
+  char *_argv0;
 
-  otk::OBTimerQueueManager _timermanager; // manages timers, so that they fire
-                                          // when their time elapses
+  //! Manages all timers for the application
+  /*!
+    Use of the otk::OBTimerQueueManager::fire funtion in this object ensures
+    that all timers fire when their times elapse.
+  */
+  otk::OBTimerQueueManager _timermanager;
 
-  RunState _state;           // the state of the window manager
+  //! The running state of the window manager
+  RunState _state;
 
-  ScreenInfoList _screenInfoList; // info for all screens on the display
+  //! When set to true, the Openbox::eventLoop function will stop and return
+  bool _doshutdown;
 
+  //! Parses the command line used when executing this application
   void parseCommandLine(int argv, char **argv);
+  //! Displays the version string to stdout
   void showVersion();
+  //! Displays usage information and help to stdout
   void showHelp();
 
-  static int xerrorHandler(Display *d, XErrorEvent *e);
+  //! Handles signal events for the application
   static void signalHandler(int signal);
 
 public:
@@ -59,18 +94,33 @@ public:
   //! Openbox destructor.
   virtual ~Openbox();
 
-  //! Returns the state of the window manager (starting, exiting, etc).
+  //! Returns the state of the window manager (starting, exiting, etc)
   inline RunState state() const { return _state; }
 
+  //! Returns the otk::OBTimerQueueManager for the application
+  /*!
+    All otk::OBTimer objects used in the application should be made to use this
+    otk::OBTimerQueueManager.
+  */
   inline otk::OBTimerQueueManager *timerManager() { return &_timermanager; }
 
+  //! The main function of the Openbox class
+  /*!
+    This function should be called after instantiating the Openbox class.
+    Loops indefinately while handling all events in the application.
+    The Openbox::shutdown method will cause this function to exit.
+  */
   void eventLoop();
 
   // XXX: TEMPORARY!#!@%*!^#*!#!#!
   virtual void process_event(XEvent *) = 0;
 
-  //! Requests that the window manager exit.
-  inline void shutdown() { _state = State_Exiting; }
+  //! Requests that the window manager exit
+  /*!
+    Causes the Openbox::eventLoop function to stop looping, so that the window
+    manager can be destroyed.
+  */
+  inline void shutdown() { _doshutdown = true; }
 };
 
 }