From 82a48229fe74b55e84988620ec92e5647dc62031 Mon Sep 17 00:00:00 2001 From: engelsman Date: Mon, 6 Oct 2008 21:16:56 +0000 Subject: added doxygen comments for undocumented functions in fl_boxtype.cxx Some of these are required in order to simplify the html headers, names and links in drawing.dox, to let doxygen do the linking and generate correct LaTeX. git-svn-id: file:///fltk/svn/fltk/branches/branch-1.3@6390 ea41ed52-d2ee-0310-a9c1-e6b18d33e121 --- src/fl_boxtype.cxx | 96 ++++++++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 86 insertions(+), 10 deletions(-) (limited to 'src') diff --git a/src/fl_boxtype.cxx b/src/fl_boxtype.cxx index 8621962e2..4a710badd 100644 --- a/src/fl_boxtype.cxx +++ b/src/fl_boxtype.cxx @@ -25,6 +25,11 @@ // http://www.fltk.org/str.php // +/** + \file fl_boxtype.cxx + \brief drawing code for common box types. +*/ + // Box drawing code for the common box types and the table of // boxtypes. Other box types are in seperate files so they are not // linked in if not used. @@ -51,12 +56,27 @@ 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. */ + +/** + 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';} +/** + Draws a series of line segments around the given box. + The string \a s must contain groups of 4 letters which specify one of 24 + standard grayscale values, where 'A' is black and 'X' is white. + The order of each set of 4 characters is: top, left, bottom, right. + The resuls of calling fl_frame() with a string that is not a multiple + of 4 characters in length is undefined. + The only difference between this function and fl_frame2() is the order + of the line segments. + \param[in] s sets of 4 grayscale values in top, left, bottom, right order + \param[in] x, y, w, h position and size +*/ void fl_frame(const char* s, int x, int y, int w, int h) { uchar *g = fl_gray_ramp(); if (h > 0 && w > 0) for (;*s;) { @@ -79,6 +99,18 @@ void fl_frame(const char* s, int x, int y, int w, int h) { } } +/** + Draws a series of line segments around the given box. + The string \a s must contain groups of 4 letters which specify one of 24 + standard grayscale values, where 'A' is black and 'X' is white. + The order of each set of 4 characters is: bottom, right, top, left. + The resuls of calling fl_frame2() with a string that is not a multiple + of 4 characters in length is undefined. + The only difference between this function and fl_frame() is the order + of the line segments. + \param[in] s sets of 4 grayscale values in bottom, right, top, left order + \param[in] x, y, w, h position and size +*/ void fl_frame2(const char* s, int x, int y, int w, int h) { uchar *g = fl_gray_ramp(); if (h > 0 && w > 0) for (;*s;) { @@ -101,28 +133,34 @@ void fl_frame2(const char* s, int x, int y, int w, int h) { } } +/** Draws a box of type FL_NO_BOX */ void fl_no_box(int, int, int, int, Fl_Color) {} +/** Draws a frame of type FL_THIN_DOWN_FRAME */ void fl_thin_down_frame(int x, int y, int w, int h, Fl_Color) { fl_frame2("WWHH",x,y,w,h); } +/** Draws a box of type FL_THIN_DOWN_BOX */ void fl_thin_down_box(int x, int y, int w, int h, Fl_Color c) { fl_thin_down_frame(x,y,w,h,c); fl_color(draw_it_active ? c : fl_inactive(c)); fl_rectf(x+1, y+1, w-2, h-2); } +/** Draws a frame of type FL_THIN_UP_FRAME */ void fl_thin_up_frame(int x, int y, int w, int h, Fl_Color) { fl_frame2("HHWW",x,y,w,h); } +/** Draws a box of type FL_THIN_UP_BOX */ void fl_thin_up_box(int x, int y, int w, int h, Fl_Color c) { fl_thin_up_frame(x,y,w,h,c); fl_color(draw_it_active ? c : fl_inactive(c)); fl_rectf(x+1, y+1, w-2, h-2); } +/** Draws a frame of type FL_UP_FRAME */ void fl_up_frame(int x, int y, int w, int h, Fl_Color) { #if BORDER_WIDTH == 1 fl_frame2("HHWW",x,y,w,h); @@ -138,12 +176,14 @@ void fl_up_frame(int x, int y, int w, int h, Fl_Color) { #define D1 BORDER_WIDTH #define D2 (BORDER_WIDTH+BORDER_WIDTH) +/** Draws a box of type FL_UP_BOX */ void fl_up_box(int x, int y, int w, int h, Fl_Color c) { fl_up_frame(x,y,w,h,c); fl_color(draw_it_active ? c : fl_inactive(c)); fl_rectf(x+D1, y+D1, w-D2, h-D2); } +/** Draws a frame of type FL_DOWN_FRAME */ void fl_down_frame(int x, int y, int w, int h, Fl_Color) { #if BORDER_WIDTH == 1 fl_frame2("WWHH",x,y,w,h); @@ -156,39 +196,51 @@ void fl_down_frame(int x, int y, int w, int h, Fl_Color) { #endif } +/** Draws a box of type FL_DOWN_BOX */ void fl_down_box(int x, int y, int w, int h, Fl_Color c) { fl_down_frame(x,y,w,h,c); fl_color(c); fl_rectf(x+D1, y+D1, w-D2, h-D2); } +/** Draws a frame of type FL_ENGRAVED_FRAME */ void fl_engraved_frame(int x, int y, int w, int h, Fl_Color) { fl_frame("HHWWWWHH",x,y,w,h); } +/** Draws a box of type FL_ENGRAVED_BOX */ void fl_engraved_box(int x, int y, int w, int h, Fl_Color c) { fl_engraved_frame(x,y,w,h,c); fl_color(draw_it_active ? c : fl_inactive(c)); fl_rectf(x+2, y+2, w-4, h-4); } +/** Draws a frame of type FL_EMBOSSED_FRAME */ void fl_embossed_frame(int x, int y, int w, int h, Fl_Color) { fl_frame("WWHHHHWW",x,y,w,h); } +/** Draws a box of type FL_EMBOSSED_BOX */ void fl_embossed_box(int x, int y, int w, int h, Fl_Color c) { fl_embossed_frame(x,y,w,h,c); fl_color(draw_it_active ? c : fl_inactive(c)); fl_rectf(x+2, y+2, w-4, h-4); } +/** + Draws a bounded rectangle with a given position, size and color, + Equivalent to drawing a box of type FL_BORDER_BOX. +*/ void fl_rectbound(int x, int y, int w, int h, Fl_Color bgcolor) { fl_color(draw_it_active ? FL_BLACK : fl_inactive(FL_BLACK)); fl_rect(x, y, w, h); fl_color(draw_it_active ? bgcolor : fl_inactive(bgcolor)); fl_rectf(x+1, y+1, w-2, h-2); } -#define fl_border_box fl_rectbound +#define fl_border_box fl_rectbound /**< allow consistent naming */ +/** + Draws a frame of type FL_BORDER_FRAME. +*/ void fl_border_frame(int x, int y, int w, int h, Fl_Color c) { fl_color(draw_it_active ? c : fl_inactive(c)); fl_rect(x, y, w, h); @@ -260,44 +312,62 @@ static struct { {fl_down_box, 3,3,6,6,0}, // FL_FREE_BOX+7 }; -/** Returns the X offset for the given boxtype. See box_dy(). */ +/** + Returns the X offset for the given boxtype. + \see box_dy() +*/ int Fl::box_dx(Fl_Boxtype t) {return fl_box_table[t].dx;} + /** Returns the Y offset for the given boxtype. -

These functions return the offset values necessary for a given + These functions return the offset values necessary for a given boxtype, useful for computing the area inside a box's borders, to prevent overdrawing the borders. -

For instance, in the case of a boxtype like FL_DOWN_BOX + For instance, in the case of a boxtype like FL_DOWN_BOX where the border width might be 2 pixels all around, the above functions would return 2, 2, 4, and 4 for box_dx, box_dy, box_dw, and box_dh respectively. -

An example to compute the area inside a widget's box(): + 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 + 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(). */ int Fl::box_dy(Fl_Boxtype t) {return fl_box_table[t].dy;} -/** Returns the width offset for the given boxtype. See box_dy(). */ + +/** + Returns the width offset for the given boxtype. + \see box_dy(). +*/ int Fl::box_dw(Fl_Boxtype t) {return fl_box_table[t].dw;} -/** Returns the height offset for the given boxtype. See box_dy(). */ + +/** + Returns the height offset for the given boxtype. + \see box_dy(). +*/ int Fl::box_dh(Fl_Boxtype t) {return fl_box_table[t].dh;} +/** + Set the drawing function for a given box type. + \param[in] t box type + \param[in] f box drawing function +*/ void fl_internal_boxtype(Fl_Boxtype t, Fl_Box_Draw_F* f) { if (!fl_box_table[t].set) { fl_box_table[t].f = f; fl_box_table[t].set = 1; } } + /** Gets the current box drawing function for the specified box type. */ Fl_Box_Draw_F *Fl::get_boxtype(Fl_Boxtype t) { return fl_box_table[t].f; @@ -317,6 +387,12 @@ void Fl::set_boxtype(Fl_Boxtype to, Fl_Boxtype from) { fl_box_table[to] = fl_box_table[from]; } +/** + Draw box using given type, position, size and color + \param[in] t box type + \param[in] x, y, w, h position and size + \param[in] c color +*/ void fl_draw_box(Fl_Boxtype t, int x, int y, int w, int h, Fl_Color c) { if (t && fl_box_table[t].f) fl_box_table[t].f(x,y,w,h,c); } -- cgit v1.2.3