From d4d89ce0bbd3dd0c556a593accb5e48f7ae09d9e Mon Sep 17 00:00:00 2001 From: Dana Jansens Date: Mon, 4 Nov 2002 03:37:17 +0000 Subject: [PATCH] documenting classes! --- doc/doxygen/doxygen.conf.in | 4 +- otk/display.hh | 63 +++++++++++++++++++++------- otk/rect.hh | 4 +- otk/timer.hh | 19 ++++++++- src/openbox.cc | 22 ++-------- src/openbox.hh | 82 +++++++++++++++++++++++++++++-------- src/workspace.cc | 2 +- 7 files changed, 142 insertions(+), 54 deletions(-) diff --git a/doc/doxygen/doxygen.conf.in b/doc/doxygen/doxygen.conf.in index cfc6db0b..d29f0674 100644 --- a/doc/doxygen/doxygen.conf.in +++ b/doc/doxygen/doxygen.conf.in @@ -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 diff --git a/otk/display.hh b/otk/display.hh index 13ceaa36..e8f91ae9 100644 --- a/otk/display.hh +++ b/otk/display.hh @@ -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 ScreenInfoList; + //! The X display + static Display *display; + //! A List of ScreenInfo instances + typedef std::vector 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); diff --git a/otk/rect.hh b/otk/rect.hh index 1ffefcba..925456a1 100644 --- a/otk/rect.hh +++ b/otk/rect.hh @@ -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 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 A second Rect object to form an intersection with. */ inline Rect &operator&=(const Rect &a) { *this = *this & a; return *this; } diff --git a/otk/timer.hh b/otk/timer.hh index 2deeba58..0bc38e1b 100644 --- a/otk/timer.hh +++ b/otk/timer.hh @@ -102,11 +102,20 @@ struct TimerLessThan { typedef _timer_queue, 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); }; diff --git a/src/openbox.cc b/src/openbox.cc index 4aac9ba5..2d1b0307 100644 --- a/src/openbox.cc +++ b/src/openbox.cc @@ -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); diff --git a/src/openbox.hh b/src/openbox.hh index 76a7d973..a479a45d 100644 --- 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 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; } }; } diff --git a/src/workspace.cc b/src/workspace.cc index 89134062..5259f3a5 100644 --- a/src/workspace.cc +++ b/src/workspace.cc @@ -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()); }