From a95a1f01a9fccfe126f4a135596e151ea4e6cd1d Mon Sep 17 00:00:00 2001 From: engelsman Date: Wed, 1 Oct 2008 22:51:30 +0000 Subject: [PATCH] added doxygen comments for undocumented features of Fl_Free - converted some HTML tags tags to doxygen \commands git-svn-id: file:///fltk/svn/fltk/branches/branch-1.3@6364 ea41ed52-d2ee-0310-a9c1-e6b18d33e121 --- FL/Fl_Free.H | 61 +++++++++++++++++++++++----------------------- src/forms_free.cxx | 58 ++++++++++++++++++++++++------------------- 2 files changed, 64 insertions(+), 55 deletions(-) diff --git a/FL/Fl_Free.H b/FL/Fl_Free.H index 313028096..6ee4192bd 100644 --- a/FL/Fl_Free.H +++ b/FL/Fl_Free.H @@ -35,32 +35,33 @@ #include "Fl_Widget.H" #endif -#define FL_NORMAL_FREE 1 -#define FL_SLEEPING_FREE 2 -#define FL_INPUT_FREE 3 -#define FL_CONTINUOUS_FREE 4 -#define FL_ALL_FREE 5 +#define FL_NORMAL_FREE 1 /**< normal event handling */ +#define FL_SLEEPING_FREE 2 /**< deactivate event handling */ +#define FL_INPUT_FREE 3 /**< accepts FL_FOCUS events */ +#define FL_CONTINUOUS_FREE 4 /**< repeated timeout handling */ +#define FL_ALL_FREE 5 /**< FL_INPUT_FREE and FL_CONTINOUS_FREE */ +/** appropriate signature for handle function */ typedef int (*FL_HANDLEPTR)(Fl_Widget *, int , float, float, char); /** - Emulation of the Forms "free" widget. This emulation allows the free - demo to run, and appears to be useful for porting programs written in - Forms which use the free widget or make subclasses of the Forms - widgets. -

There are five types of free, which determine when the handle - function is called:

- \code - #define FL_NORMAL_FREE 1 - #define FL_SLEEPING_FREE 2 - #define FL_INPUT_FREE 3 - #define FL_CONTINUOUS_FREE 4 - #define FL_ALL_FREE 5 - \endcode -

An FL_INPUT_FREE accepts FL_FOCUS events. A FL_CONTINUOUS_FREE sets - a timeout callback 100 times a second and provides a FL_STEP event, - this has obvious detrimental effects on machine performance. - FL_ALL_FREE does both. FL_SLEEPING_FREE are deactivated. + Emulation of the Forms "free" widget. + + This emulation allows the free demo to run, and appears to be useful for + porting programs written in Forms which use the free widget or make + subclasses of the Forms widgets. + + There are five types of free, which determine when the handle function + is called: + + \li \c FL_NORMAL_FREE normal event handling. + \li \c FL_SLEEPING_FREE deactivates event handling (widget is inactive). + \li \c FL_INPUT_FREE accepts FL_FOCUS events. + \li \c FL_CONTINUOUS_FREE sets a timeout callback 100 times a second and + provides an FL_STEP event. This has obvious + detrimental effects on machine performance. + \li \c FL_ALL_FREE same as FL_INPUT_FREE and FL_CONTINUOUS_FREE. + */ class FL_EXPORT Fl_Free : public Fl_Widget { FL_HANDLEPTR hfunc; @@ -68,18 +69,18 @@ class FL_EXPORT Fl_Free : public Fl_Widget { protected: void draw(); public: - int handle(int); - Fl_Free(uchar t,int x,int y,int w,int h,const char *l,FL_HANDLEPTR hdl); + int handle(int e); + Fl_Free(uchar t,int X,int Y,int W,int H,const char *L,FL_HANDLEPTR hdl); ~Fl_Free(); }; // old event names for compatibility: -#define FL_MOUSE FL_DRAG -#define FL_DRAW 100 // NOT USED -#define FL_STEP 101 -#define FL_FREEMEM 102 // NOT USED -#define FL_FREEZE 103 // NOT USED -#define FL_THAW 104 // NOT USED +#define FL_MOUSE FL_DRAG /**< for backward compatibility */ +#define FL_DRAW 100 /**< for backward compatibility [UNUSED]*/ +#define FL_STEP 101 /**< for backward compatibility */ +#define FL_FREEMEM 102 /**< for backward compatibility [UNUSED]*/ +#define FL_FREEZE 103 /**< for backward compatibility [UNUSED]*/ +#define FL_THAW 104 /**< for backward compatibility [UNUSED]*/ #endif diff --git a/src/forms_free.cxx b/src/forms_free.cxx index ccd526d01..c3aa4d299 100644 --- a/src/forms_free.cxx +++ b/src/forms_free.cxx @@ -42,32 +42,38 @@ void Fl_Free::step(void *v) { } /** - The constructor takes both the type and the handle - function. The handle function should be declared as follows: - \code - int - handle_function(Fl_Widget *w, - int event, - float event_x, - float event_y, - char key) - \endcode - This function is called from the the handle() method in - response to most events, and is called by the draw() method. - The event argument contains the event type: - \code - // old event names for compatibility: - #define FL_MOUSE FL_DRAG - #define FL_DRAW 0 - #define FL_STEP 9 - #define FL_FREEMEM 12 - #define FL_FREEZE FL_UNMAP - #define FL_THAW FL_MAP - \endcode + Create a new Fl_Free widget with type, position, size, label and handler. + \param[in] t type + \param[in] X, Y, W, H position and size + \param[in] L widget label + \param[in] hdl handler function + + The constructor takes both the type and the handle function. The handle + function should be declared as follows: + \code + int handle_function(Fl_Widget *w, + int event, + float event_x, + float event_y, + char key) + \endcode + This function is called from the the handle() method in response to most + events, and is called by the draw() method. + + The event argument contains the event type: + \code + // old event names for compatibility: + #define FL_MOUSE FL_DRAG + #define FL_DRAW 0 + #define FL_STEP 9 + #define FL_FREEMEM 12 + #define FL_FREEZE FL_UNMAP + #define FL_THAW FL_MAP + \endcode */ -Fl_Free::Fl_Free(uchar t,int X, int Y, int W, int H,const char *l, +Fl_Free::Fl_Free(uchar t,int X, int Y, int W, int H,const char *L, FL_HANDLEPTR hdl) : -Fl_Widget(X,Y,W,H,l) { +Fl_Widget(X,Y,W,H,L) { type(t); hfunc = hdl; if (t == FL_SLEEPING_FREE) set_flag(INACTIVE); @@ -75,7 +81,9 @@ Fl_Widget(X,Y,W,H,l) { Fl::add_timeout(.01,step,this); } -/** The destructor will call the handle function with the event FL_FREE_MEM. */ +/** + The destructor will call the handle function with the event FL_FREE_MEM. +*/ Fl_Free::~Fl_Free() { Fl::remove_timeout(step,this); hfunc(this,FL_FREEMEM,0,0,0);