documenting classes!
authorDana Jansens <danakj@orodu.net>
Mon, 4 Nov 2002 03:37:17 +0000 (03:37 +0000)
committerDana Jansens <danakj@orodu.net>
Mon, 4 Nov 2002 03:37:17 +0000 (03:37 +0000)
doc/doxygen/doxygen.conf.in
otk/display.hh
otk/rect.hh
otk/timer.hh
src/openbox.cc
src/openbox.hh
src/workspace.cc

index cfc6db0..d29f067 100644 (file)
@@ -11,7 +11,7 @@ EXTRACT_ALL            = YES
 EXTRACT_PRIVATE        = YES
 EXTRACT_STATIC         = YES
 EXTRACT_LOCAL_CLASSES  = YES
-HIDE_UNDOC_MEMBERS     = YES
+HIDE_UNDOC_MEMBERS     = NO
 HIDE_UNDOC_CLASSES     = NO
 HIDE_FRIEND_COMPOUNDS  = NO
 BRIEF_MEMBER_DESC      = YES
@@ -29,7 +29,7 @@ VERBATIM_HEADERS       = YES
 SHOW_INCLUDE_FILES     = YES
 JAVADOC_AUTOBRIEF      = NO
 MULTILINE_CPP_IS_BRIEF = NO
-DETAILS_AT_TOP         = NO
+DETAILS_AT_TOP         = YES
 INHERIT_DOCS           = YES
 INLINE_INFO            = YES
 SORT_MEMBER_DOCS       = YES
index 13ceaa3..e8f91ae 100644 (file)
@@ -13,42 +13,77 @@ namespace otk {
 class ScreenInfo;
 class BGCCache;
 
+//! Manages a single X11 display.
+/*!
+  This class is static, and cannot be instantiated.
+  Use the initialize() method to open the display and ready it for use.
+  Use the destroy() method to close it and clean up the class' data.
+*/
 class OBDisplay
 {
 public:
-  static Display *display;       // the X display
-
-  typedef std::vector<ScreenInfo> ScreenInfoList;
+  //! The X display
+  static Display *display;
   
+  //! A List of ScreenInfo instances
+  typedef std::vector<ScreenInfo> ScreenInfoList;
+
 private:
-  static bool _shape;          // does the display have the shape extention?
-  static int  _shape_event_basep;   // base for shape events
+  //! Does the display have the Shape extention?
+  static bool _shape;
+  //! Base for events for the Shape extention
+  static int  _shape_event_basep;
 
-  static bool _xinerama;       // does the display have the xinerama extention?
-  static int  _xinerama_event_basep;// base for xinerama events
+  //! Does the display have the Xinerama extention?
+  static bool _xinerama;
+  //! Base for events for the Xinerama extention
+  static int  _xinerama_event_basep;
 
-  static unsigned int _mask_list[8];// a list of all combinations of lock masks
+  //! A list of all possible combinations of keyboard lock masks
+  static unsigned int _mask_list[8];
 
-  static ScreenInfoList _screenInfoList; // info for all screens on the display
+  //! A list of information for all screens on the display
+  static ScreenInfoList _screenInfoList;
 
+  //! A cache for re-using GCs, used by the drawing objects
+  /*!
+    @see BPen
+    @see BFont
+    @see BImage
+    @see BImageControl
+    @see BTexture
+  */
   static BGCCache *_gccache;
 
-  static int xerrorHandler(Display *d, XErrorEvent *e); // handles X errors duh
+  //! Handles X errors on the display
+  /*!
+    Displays the error if compiled for debugging.
+  */
+  static int xerrorHandler(Display *d, XErrorEvent *e);
 
-  OBDisplay(); // this class cannot be instantiated
+  //! Prevents instantiation of the class
+  OBDisplay();
 
 public:
+  //! Initializes the class, opens the X display
+  /*!
+    @see OBDisplay::display
+    @param name The name of the X display to open. If it is null, the DISPLAY
+                environment variable is used instead.
+  */
   static void initialize(char *name);
+  //! Destroys the class, closes the X display
   static void destroy();
 
   //! Returns the GC cache for the application
   inline static BGCCache *gcCache() { return _gccache; }
 
+  //! Gets information on a specific screen
   /*!
-    Returns a ScreenInfo class, which gives information on a screen on the
+    Returns a ScreenInfo class, which contains information for a screen on the
     display.
-    \param snum The screen number of the screen to retrieve info on
-    \return Info on the requested screen, in a ScreenInfo class
+    @param snum The screen number of the screen to retrieve info on
+    @return Info on the requested screen, in a ScreenInfo class
   */
   static const ScreenInfo* screenInfo(int snum);
 
index 1ffefcb..925456a 100644 (file)
@@ -130,7 +130,7 @@ public:
   /*!
     The intersection of the rectangles will consist of just the area where the
     two rectangles overlap.
-    @param A second Rect object to form an intersection with.
+    @param A second Rect object to form an intersection with.
     @return The intersection between this Rect and the one passed to the
             function
   */
@@ -147,7 +147,7 @@ public:
   /*!
     The intersection of the rectangles will consist of just the area where the
     two rectangles overlap.
-    @param A second Rect object to form an intersection with.
+    @param A second Rect object to form an intersection with.
   */
   inline Rect &operator&=(const Rect &a) { *this = *this & a; return *this; }
 
index 2deeba5..0bc38e1 100644 (file)
@@ -102,11 +102,20 @@ struct TimerLessThan {
 typedef _timer_queue<OBTimer*,
                      std::vector<OBTimer*>, TimerLessThan> TimerQueue;
 
+//! Manages a queue of OBTimer objects
+/*!
+  All OBTimer objects add themself to an OBTimerQueueManager. The manager is
+  what fires the timers when their time has elapsed. This is done by having the
+  application call the OBTimerQueueManager::fire class in its main event loop.
+*/
 class OBTimerQueueManager {
 private:
+  //! A priority queue of all timers being managed by this class.
   TimerQueue timerList;
 public:
+  //! Constructs a new OBTimerQueueManager
   OBTimerQueueManager() {}
+  //! Destroys the OBTimerQueueManager
   virtual ~OBTimerQueueManager() {}
 
   //! Will wait for and fire the next timer in the queue.
@@ -114,8 +123,16 @@ public:
     The function will stop waiting if an event is received from the X server.
   */
   virtual void fire();
-  
+
+  //! Adds a new timer to the queue
+  /*!
+    @param timer An OBTimer to add to the queue
+  */
   virtual void addTimer(OBTimer* timer);
+  //! Removes a timer from the queue
+  /*!
+    @param timer An OBTimer already in the queue to remove
+  */
   virtual void removeTimer(OBTimer* timer);
 };
 
index 4aac9ba..2d1b030 100644 (file)
@@ -44,22 +44,6 @@ namespace ob {
 Openbox *Openbox::instance = (Openbox *) 0;
 
 
-int Openbox::xerrorHandler(Display *d, XErrorEvent *e)
-{
-#ifdef DEBUG
-  char errtxt[128];
-
-  XGetErrorText(d, e->error_code, errtxt, 128);
-  printf("X Error: %s\n", errtxt);
-#else
-  (void)d;
-  (void)e;
-#endif
-
-  return false;
-}
-
-
 void Openbox::signalHandler(int signal)
 {
   switch (signal) {
@@ -86,7 +70,7 @@ Openbox::Openbox(int argc, char **argv)
 {
   struct sigaction action;
 
-  _state = State_Starting;
+  _state = State_Starting; // initializing everything
 
   Openbox::instance = this;
 
@@ -118,6 +102,8 @@ Openbox::Openbox(int argc, char **argv)
 
 Openbox::~Openbox()
 {
+  _state = State_Exiting; // time to kill everything
+  
   // close the X display
   otk::OBDisplay::destroy();
 }
@@ -209,7 +195,7 @@ void Openbox::showHelp()
 
 void Openbox::eventLoop()
 {
-  while (_state == State_Normal) {
+  while (!_doshutdown) {
     if (XPending(otk::OBDisplay::display)) {
       XEvent e;
       XNextEvent(otk::OBDisplay::display, &e);
index 76a7d97..a479a45 100644 (file)
@@ -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; }
 };
 
 }
index 8913406..5259f3a 100644 (file)
@@ -413,7 +413,7 @@ bool Workspace::isCurrent(void) const {
 }
 
 
-bool Workspace::isLastWindow(const BlackboxWindow* const w) const {
+bool Workspace::isLastWindow(const BlackboxWindow *w) const {
   return (w == windowList.back());
 }