From 0adc1ccdaad1cc46ef232309362f88ac10ca6459 Mon Sep 17 00:00:00 2001 From: engelsman Date: Tue, 7 Oct 2008 21:07:12 +0000 Subject: [PATCH] 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 --- FL/fl_draw.H | 14 +++++++++++-- src/fl_color.cxx | 20 ++++++++++++++++++ src/fl_rect.cxx | 54 ++++++++++++++++++++++++++++++++++++++++++++---- 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];