doxygen comments for undocumented drawing, clipping and color functions

added comments in fl_draw.H, fl_color.cxx and fl_rect.cxx so that the
links within drawing.dox can be simplified to allow LaTeX/PDF docs too.



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

3 files changed, 82 insertions, 6 deletions

diff --git a/FL/fl_draw.H b/FL/fl_draw.H
index 5bc370fe0..94f5b5668 100644
--- a/FL/fl_draw.H
+++ b/FL/fl_draw.H
@@ -25,6 +25,11 @@
 //     http://www.fltk.org/str.php
 //
 
+/**
+  \file fl_draw.H
+  \brief utility header to pull drawing functions together
+*/
+
 #ifndef fl_draw_H
 #define fl_draw_H
 
@@ -37,14 +42,19 @@ class Fl_Image;
 FL_EXPORT extern char fl_draw_shortcut;
 
 // Colors:
-FL_EXPORT void	fl_color(Fl_Color); // select indexed color
+FL_EXPORT void	fl_color(Fl_Color i); // select indexed color
 inline void fl_color(int c) {fl_color((Fl_Color)c);} // for back compatibility
-FL_EXPORT void	fl_color(uchar, uchar, uchar); // select actual color
+FL_EXPORT void	fl_color(uchar r, uchar g, uchar b); // select actual color
 extern FL_EXPORT Fl_Color fl_color_;
+/**
+  Returns the last fl_color() that was set.
+  This can be used for state save/restore.
+*/
 inline Fl_Color fl_color() {return fl_color_;}
 
 // clip:
 FL_EXPORT void fl_push_clip(int x, int y, int w, int h);
+/** The fl_clip() name is deprecated and will be removed from future releases */
 #define fl_clip fl_push_clip
 FL_EXPORT void fl_push_no_clip();
 FL_EXPORT void fl_pop_clip();
diff --git a/src/fl_color.cxx b/src/fl_color.cxx
index 3b827f54c..a3f82df19 100644
--- a/src/fl_color.cxx
+++ b/src/fl_color.cxx
@@ -25,6 +25,11 @@
 //     http://www.fltk.org/str.php
 //
 
+/**
+  \file fl_color.cxx
+  \brief Color handling
+*/
+
 // Implementation of fl_color(i), fl_color(r,g,b).
 
 #ifdef WIN32
@@ -137,6 +142,14 @@ ulong fl_xpixel(uchar r,uchar g,uchar b) {
      ) >> fl_extrashift;
 }
 
+/**
+  Set the color for all subsequent drawing operations.
+  The closest possible match to the RGB color is used.
+  The RGB color is used directly on TrueColor displays.
+  For colormap visuals the nearest index in the gray
+  ramp or color cube is used.
+  \param[in] r,g,b color components
+*/
 void fl_color(uchar r,uchar g,uchar b) {
   fl_color_ = fl_rgb_color(r, g, b);
   XSetForeground(fl_display, fl_gc, fl_xpixel(r,g,b));
@@ -277,6 +290,13 @@ ulong fl_xpixel(Fl_Color i) {
 
 Fl_Color fl_color_;
 
+/**
+  Sets the color for all subsequent drawing operations.
+  For colormapped displays, a color cell will be allocated out of
+  \a fl_colormap the first time you use a color. If the colormap fills up
+  then a least-squares algorithm is used to find the closest color.
+  \param[in] i color 
+*/
 void fl_color(Fl_Color i) {
   if (i & 0xffffff00) {
     unsigned rgb = (unsigned)i;
diff --git a/src/fl_rect.cxx b/src/fl_rect.cxx
index b1fce4d50..251e7751e 100644
--- a/src/fl_rect.cxx
+++ b/src/fl_rect.cxx
@@ -25,6 +25,11 @@
 //     http://www.fltk.org/str.php
 //
 
+/**
+  \file fl_rect.cxx
+  \brief Drawing and clipping routines for rectangles.
+*/
+
 // These routines from fl_draw.H are used by the standard boxtypes
 // and thus are always linked into an fltk program.
 // Also all fl_clip routines, since they are always linked in so
@@ -514,7 +519,11 @@ void fl_restore_clip() {
 #endif
 }
 
-// Replace the top of the clip stack:
+/**
+  Replace te top of the clipping stack with a clipping region of any shape.
+  Fl_Region is an operating system specific type.
+  \param[in] r clipping region
+*/
 void fl_clip_region(Fl_Region r) {
   Fl_Region oldr = rstack[rstackptr];
   if (oldr) XDestroyRegion(oldr);
@@ -522,12 +531,18 @@ void fl_clip_region(Fl_Region r) {
   fl_restore_clip();
 }
 
-// Return the current clip region...
+/**
+  \returns the current clipping region.
+*/
 Fl_Region fl_clip_region() {
   return rstack[rstackptr];
 }
 
-// Intersect & push a new clip rectangle:
+/**
+  Intersect the current clip region with a rectangle and push this
+  new region onto the stack.
+  \param[in] x,y,w,h position and size
+*/
 void fl_push_clip(int x, int y, int w, int h) {
   Fl_Region r;
   if (w > 0 && h > 0) {
@@ -566,6 +581,9 @@ void fl_push_clip(int x, int y, int w, int h) {
 }
 
 // make there be no clip (used by fl_begin_offscreen() only!)
+/**
+  Pushes an empty clip region onto the stack so nothing will be clipped.
+*/
 void fl_push_no_clip() {
   if (rstackptr < STACK_MAX) rstack[++rstackptr] = 0;
   else Fl::warning("fl_push_no_clip: clip stack overflow!\n");
@@ -573,6 +591,12 @@ void fl_push_no_clip() {
 }
 
 // pop back to previous clip:
+/**
+  Restore the previious clip region.
+  You must call fl_pop_clip() omce for every time you call fl_push_clip().
+  Unpredictable results may occur if the clip stack is not empty when
+  you return to FLTK.
+*/
 void fl_pop_clip() {
   if (rstackptr > 0) {
     Fl_Region oldr = rstack[rstackptr--];
@@ -581,7 +605,16 @@ void fl_pop_clip() {
   fl_restore_clip();
 }
 
-// does this rectangle intersect current clip?
+/**
+  Does the rectangle intersect the current clip region?
+  \param[in] x,y,w,h position and size of rectangle
+  \returns non-zero if any of the rectangle intersects the current clip
+  region, If this returns 0 you don't have to draw the object.
+
+  \note
+  Under X this returns 2 if the rectangle is partially clipped, 
+  and 1 is it is entirely inside the clip region.
+*/
 int fl_not_clipped(int x, int y, int w, int h) {
   if (x+w <= 0 || y+h <= 0) return 0;
   Fl_Region r = rstack[rstackptr];
@@ -606,6 +639,19 @@ int fl_not_clipped(int x, int y, int w, int h) {
 }
 
 // return rectangle surrounding intersection of this rectangle and clip:
+/**
+  Intersect the rectangle with the current clip region and return the
+  bounding box of the result.
+  Returns non-zero if the resulting rectangle is different to the original.
+  Ths can be used to limit the necessary drawing to a rectangle.
+  \a W and \a H are set to zero if the rectangle is completely outside
+  the region.
+  \param[in] x,y,w,h position and size of rectangle
+  \param[out] X,Y,W,H position and size of resulting bounding box.
+              \a W and \a H are set to zero if the rectangle is
+	      completely outside the region.
+  \returns Non-zero if the resulting rectangle is different to the original.
+*/
 int fl_clip_box(int x, int y, int w, int h, int& X, int& Y, int& W, int& H){
   X = x; Y = y; W = w; H = h;
   Fl_Region r = rstack[rstackptr];