From a99524ef2d24ce14334a171b9de29dfdf93928cd Mon Sep 17 00:00:00 2001 From: Fabien Costantini Date: Mon, 15 Sep 2008 19:21:20 +0000 Subject: Doxygen documentation. Completed Fl class, added a todo related to recent Fl API to document. Matt?. More cosmetics have been done, replaced *all*
tags by \code \endcode sequences. git-svn-id: file:///fltk/svn/fltk/branches/branch-1.3@6260 ea41ed52-d2ee-0310-a9c1-e6b18d33e121 --- src/Fl.cxx | 73 +++++++++++------------------------------------- src/Fl_File_Chooser2.cxx | 8 +++--- src/Fl_File_Icon2.cxx | 4 +-- src/Fl_Menu_add.cxx | 8 +++--- src/fl_boxtype.cxx | 7 +++-- src/fl_utf.c | 4 +-- src/forms_free.cxx | 18 +++++------- src/gl_start.cxx | 13 --------- 8 files changed, 39 insertions(+), 96 deletions(-) (limited to 'src') diff --git a/src/Fl.cxx b/src/Fl.cxx index 92183b54b..e403ab3af 100644 --- a/src/Fl.cxx +++ b/src/Fl.cxx @@ -186,57 +186,11 @@ static void elapse_timeouts() { // time interval: static double missed_timeout_by; -/** - Add a one-shot timeout callback. The function will be called by - Fl::wait() at t seconds after this function is called. - The optional void* argument is passed to the callback. - -

You can have multiple timeout callbacks. To remove an timeout - callback use Fl::remove_timeout(). - -

If you need more accurate, repeated timeouts, use Fl::repeat_timeout() to - reschedule the subsequent timeouts.

- -

The following code will print "TICK" each second on - stdout with a fair degree of accuracy:

- - 
-     void callback(void*) {
-       puts("TICK");
-       Fl::repeat_timeout(1.0, callback);
-     }
-  
-     int main() {
-       Fl::add_timeout(1.0, callback);
-       return Fl::run();
-     }
-
-*/ void Fl::add_timeout(double time, Fl_Timeout_Handler cb, void *argp) { elapse_timeouts(); repeat_timeout(time, cb, argp); } -/** - This method repeats a timeout callback from the expiration of the - previous timeout, allowing for more accurate timing. You may only call - this method inside a timeout callback. - -

The following code will print "TICK" each second on - stdout with a fair degree of accuracy:

- - 
-     void callback(void*) {
-       puts("TICK");
-       Fl::repeat_timeout(1.0, callback);
-     }
-  
-     int main() {
-       Fl::add_timeout(1.0, callback);
-       return Fl::run();
-     }
-
-*/ void Fl::repeat_timeout(double time, Fl_Timeout_Handler cb, void *argp) { time += missed_timeout_by; if (time < -.05) time = 0; Timeout* t = free_timeout; @@ -316,7 +270,7 @@ static Check *first_check, *next_check, *free_check;

Sample code: -

+ \endcode */ void Fl::add_check(Fl_Timeout_Handler cb, void *argp) { Check* t = free_check; @@ -543,13 +497,13 @@ int Fl::wait() { Same as Fl::wait(0). Calling this during a big calculation will keep the screen up to date and the interface responsive: - + \endcode

The returns non-zero if any windows are displayed, and 0 if no windows are displayed (this is likely to change in future versions of @@ -567,7 +521,7 @@ int Fl::check() { true if Fl::check() would do anything (it will continue to return true until you call Fl::check() or Fl::wait()). -

+ \endcode */ int Fl::ready() { #if ! defined( WIN32 ) && ! defined(__APPLE__) @@ -1537,9 +1491,11 @@ void Fl::delete_widget(Fl_Widget *wi) { num_dwidgets ++; } - -void -Fl::do_widget_deletion() { +/** + Deletes widgets previously scheduled for deletion. + See void Fl::delete_widget(Fl_Widget *wi) +*/ +void Fl::do_widget_deletion() { if (!num_dwidgets) return; for (int i = 0; i < num_dwidgets; i ++) @@ -1551,7 +1507,9 @@ Fl::do_widget_deletion() { static Fl_Widget ***widget_watch = 0; static int num_widget_watch = 0; static int max_widget_watch = 0; - +/** Adds a widget pointer to the watch list. + \todo explain the role of the watch list, + it may be related to invalid widget deletion crash fixes... */ void Fl::watch_widget_pointer(Fl_Widget *&w) { Fl_Widget **wp = &w; @@ -1572,6 +1530,7 @@ void Fl::watch_widget_pointer(Fl_Widget *&w) widget_watch[num_widget_watch++] = wp; } +/** Releases a widget pointer to the watch list */ void Fl::release_widget_pointer(Fl_Widget *&w) { Fl_Widget **wp = &w; @@ -1583,7 +1542,7 @@ void Fl::release_widget_pointer(Fl_Widget *&w) } } } - +/** Clears a widget pointer in the watch list */ void Fl::clear_widget_pointer(Fl_Widget const *w) { if (w==0L) return; diff --git a/src/Fl_File_Chooser2.cxx b/src/Fl_File_Chooser2.cxx index 8447ab080..be0c8ebd4 100644 --- a/src/Fl_File_Chooser2.cxx +++ b/src/Fl_File_Chooser2.cxx @@ -118,9 +118,9 @@ "Description text (patterns)" or just "patterns". A file chooser that provides filters for HTML and image files might look like: - + \endcode

The file chooser will automatically add the "All Files (*)" pattern to the end of the string you pass if you do not provide @@ -253,13 +253,13 @@ Fl_File_Chooser::count().

This sample code loops through all selected files: - 

+  \code
   // Get list of filenames user selected from a MULTI chooser
   for ( int t=1; t<=chooser->count(); t++ ) {
      const char *filename = chooser->value(t);
      ..
   }
-
+ \endcode */ /** \fn const char *Fl_File_Chooser::value(int file) diff --git a/src/Fl_File_Icon2.cxx b/src/Fl_File_Icon2.cxx index 303c0e1f5..119954949 100644 --- a/src/Fl_File_Icon2.cxx +++ b/src/Fl_File_Icon2.cxx @@ -581,9 +581,9 @@ int Fl_File_Icon::load_image(const char *ifile) // I - File to read from FileChooser widget and should be used when the application starts: - + \endcode */ void Fl_File_Icon::load_system_icons(void) { diff --git a/src/Fl_Menu_add.cxx b/src/Fl_Menu_add.cxx index 1edb61394..9265fe7b5 100644 --- a/src/Fl_Menu_add.cxx +++ b/src/Fl_Menu_add.cxx @@ -207,19 +207,19 @@ int Fl_Menu_Item::add(

Shortcut can be 0L, or either a modifier/key combination (for example FL_CTRL+'A') or a string describing the shortcut in one of two ways:

- 
+  \code
    [#+^]<ascii_value>    eg. "97", "^97", "+97", "#97"
    [#+^]<ascii_char>     eg. "a", "^a", "+a", "#a"
-
+ \endcode ..where <ascii_value> is a decimal value representing an ascii character (eg. 97 is the ascii for 'a'), and the optional prefixes enhance the value that follows. Multiple prefixes must appear in the above order. - 
+  \code
    # - Alt
    + - Shift
    ^ - Control
-
+ \endcode Text shortcuts are converted to integer shortcut by calling int fl_old_shortcut(const char*). diff --git a/src/fl_boxtype.cxx b/src/fl_boxtype.cxx index ec7490e30..e98a203ec 100644 --- a/src/fl_boxtype.cxx +++ b/src/fl_boxtype.cxx @@ -51,7 +51,8 @@ static uchar inactive_ramp[24] = { 49, 49, 50, 50, 51, 51, 52, 52}; static int draw_it_active = 1; - +/** Determines if the current draw box is active or inactive. + If inactive, the box color is changed by the inactive color. */ int Fl::draw_box_active() { return draw_it_active; } uchar *fl_gray_ramp() {return (draw_it_active?active_ramp:inactive_ramp)-'A';} @@ -275,12 +276,12 @@ int Fl::box_dx(Fl_Boxtype t) {return fl_box_table[t].dx;} respectively.

An example to compute the area inside a widget's box(): - 

+    \code
          int X = yourwidget->x() + Fl::box_dx(yourwidget->box());
          int Y = yourwidget->y() + Fl::box_dy(yourwidget->box());
          int W = yourwidget->w() - Fl::box_dw(yourwidget->box());
          int H = yourwidget->h() - Fl::box_dh(yourwidget->box());
-
+ \endcode

These functions are mainly useful in the draw() code for deriving custom widgets, where one wants to avoid drawing over the widget's own border box(). diff --git a/src/fl_utf.c b/src/fl_utf.c index c3e80f7f2..95b4e37c6 100644 --- a/src/fl_utf.c +++ b/src/fl_utf.c @@ -81,7 +81,7 @@ static unsigned short cp1252[32] = { standards recommend), adding a test to see if the length is unexpectedly 1 will work: -\code + \code if (*p & 0x80) { // what should be a multibyte encoding code = fl_utf8decode(p,end,&len); if (len<2) code = 0xFFFD; // Turn errors into REPLACEMENT CHARACTER @@ -89,7 +89,7 @@ static unsigned short cp1252[32] = { code = *p; len = 1; } -\endcode + \endcode Direct testing for the 1-byte case (as shown above) will also speed up the scanning of strings where the majority of characters diff --git a/src/forms_free.cxx b/src/forms_free.cxx index ec5346299..950fe4730 100644 --- a/src/forms_free.cxx +++ b/src/forms_free.cxx @@ -44,30 +44,26 @@ void Fl_Free::step(void *v) { /** The constructor takes both the type and the handle function. The handle function should be declared as follows: -

+ \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: - + #define FL_THAW FL_MAP + \endcode */ Fl_Free::Fl_Free(uchar t,int X, int Y, int W, int H,const char *l, FL_HANDLEPTR hdl) : diff --git a/src/gl_start.cxx b/src/gl_start.cxx index 868a0d894..8275399a1 100644 --- a/src/gl_start.cxx +++ b/src/gl_start.cxx @@ -109,19 +109,6 @@ void gl_finish() { glXWaitGL(); #endif } -/** - This does the same thing as - Fl::visual(int) but also - requires OpenGL drawing to work. This must be done if - you want to draw in normal windows with OpenGL with gl_start() and - gl_end(). It may be useful to call this so your X - windows use the same visual as an - Fl_Gl_Window, which on - some servers will reduce colormap flashing. - -

See Fl_Gl_Window - for a list of additional values for the argument. -*/ int Fl::gl_visual(int mode, int *alist) { Fl_Gl_Choice *c = Fl_Gl_Choice::find(mode,alist); if (!c) return 0; -- cgit v1.2.3