added doxygen comments for more functions in fl_draw.H

FL/fl_draw.H: see below
src/fl_cursor.cxx: fl_cursor()
src/fl_scroll_area.cxx: fl_scroll()
src/fl_overlay.cxx: fl_overlay_clear(), fl_overlay_rect()
documentation/src/drawing.dox: updated paragraph tag links



git-svn-id: file:///fltk/svn/fltk/branches/branch-1.3@6690 ea41ed52-d2ee-0310-a9c1-e6b18d33e121

FL/fl_draw.H

@@ -435,10 +435,10 @@ FL_EXPORT int fl_measure_pixmap(const char* const* cdata, int &w, int &h);
 // other:
 FL_EXPORT void fl_scroll(int X, int Y, int W, int H, int dx, int dy,
                          void (*draw_area)(void*, int,int,int,int), void* data);
-FL_EXPORT const char* fl_shortcut_label(int);
-FL_EXPORT void fl_overlay_rect(int,int,int,int);
+FL_EXPORT const char* fl_shortcut_label(int shortcut);
+FL_EXPORT void fl_overlay_rect(int x,int y,int w,int h);
 FL_EXPORT void fl_overlay_clear();
-FL_EXPORT void fl_cursor(Fl_Cursor, Fl_Color=FL_BLACK, Fl_Color=FL_WHITE);
+FL_EXPORT void fl_cursor(Fl_Cursor, Fl_Color fg=FL_BLACK, Fl_Color bg=FL_WHITE);
 FL_EXPORT const char* fl_expand_text(const char* from, char* buf, int maxbuf,
                                      double maxw, int& n, double &width,
                                      int wrap, int draw_symbols = 0);

documentation/src/drawing.dox

@@ -373,8 +373,7 @@ extend outside the line drawn by fl_arc(); to avoid this
 use <tt>w - 1</tt> and <tt>h - 1</tt>.
 
 <A name="fl_scroll"></A> <!-- For old HTML links only ! -->
-void fl_scroll(int X, int Y, int W, int H, int dx, int dy,
-void (*draw_area)(void*, int,int,int,int), void* data)
+void fl_scroll(int X, int Y, int W, int H, int dx, int dy, void (*draw_area)(void*, int,int,int,int), void* data)
 
 \par
 Scroll a rectangle and draw the newly exposed portions. The contents
@@ -601,7 +600,7 @@ Return the pixel width of a nul-terminated string, a sequence of <tt>n</tt>
 characters, or a single character in the current font.
 
 <A NAME="fl_shortcut_label"></A> <!-- For old HTML links only ! -->
-const char *fl_shortcut_label(ulong)
+const char* fl_shortcut_label(int shortcut)
 
 \par
 Unparse a shortcut value as used by Fl_Button or Fl_Menu_Item

src/fl_cursor.cxx

@@ -39,6 +39,10 @@
 #endif
 #include <FL/fl_draw.H>
 
+/**
+  Sets the cursor for the current window to the specified shape and colors.
+  The cursors are defined in the <FL/Enumerations.H> header file. 
+  */
 void fl_cursor(Fl_Cursor c, Fl_Color fg, Fl_Color bg) {
   if (Fl::first_window()) Fl::first_window()->cursor(c,fg,bg);
 }

src/fl_overlay.cxx

@@ -103,10 +103,16 @@ static void erase_current_rect() {
 #endif
 }
 
+/**
+  Erase a selection rectangle without drawing a new one
+  */
 void fl_overlay_clear() {
   if (pw > 0) {erase_current_rect(); pw = 0;}
 }
 
+/**
+  Draws a selection rectangle, erasing a previous one by XOR'ing it first.
+  */
 void fl_overlay_rect(int x, int y, int w, int h) {
   if (w < 0) {x += w; w = -w;} else if (!w) w = 1;
   if (h < 0) {y += h; h = -h;} else if (!h) h = 1;

src/fl_scroll_area.cxx

@@ -35,8 +35,19 @@
 #include <FL/fl_draw.H>
 
 // scroll a rectangle and redraw the newly exposed portions:
+/**
+  Scroll a rectangle and draw the newly exposed portions.
+  \param[in] X,Y       position of top-left of rectangle
+  \param[in] W,H       size of rectangle
+  \param[in] dx,dy     pixel offsets for shifting rectangle
+  \param[in] draw_area callback function to draw rectangular areas
+  \param[in] data      pointer to user data for callback
+  The contents of the rectangular area is first shifted by \a dx
+  and \a dy pixels. The \a draw_area callback is then called for
+  every newly exposed rectangular area.
+  */
 void fl_scroll(int X, int Y, int W, int H, int dx, int dy,
-	       void (*draw_area)(void*, int,int,int,int), void* data)
+               void (*draw_area)(void*, int,int,int,int), void* data)
 {
   if (!dx && !dy) return;
   if (dx <= -W || dx >= W || dy <= -H || dy >= H) {

src/fl_shortcut.cxx

@@ -133,7 +133,15 @@ static Keyname table[] = {
 };
 #endif
 
-const char * fl_shortcut_label(int shortcut) {
+/**
+  Get a human-readable string from a shortcut value.
+  Unparse a shortcut value as used by Fl_Button or Fl_Menu_Item into
+  a human-readable string like "Alt+N". This only works if the shortcut
+  is a character key or a numbered function key. If the shortcut is
+  zero then an empty string is returned. The return value points at
+  a static buffer that is overwritten with each call.
+  */
+const char* fl_shortcut_label(int shortcut) {
   static char buf[20];
   char *p = buf;
   if (!shortcut) {*p = 0; return buf;}