added doxygen comments for more font/text functions in fl_draw.{H,cxx}

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

2 files changed, 92 insertions, 12 deletions

diff --git a/FL/fl_draw.H b/FL/fl_draw.H
index 0f89c44de..4511ccc4f 100644
--- a/FL/fl_draw.H
+++ b/FL/fl_draw.H
@@ -149,31 +149,85 @@ FL_EXPORT double fl_transform_dx(double x, double y);
 FL_EXPORT double fl_transform_dy(double x, double y);
 FL_EXPORT void fl_transformed_vertex(double x, double y);
 
-// current font:
+/* NOTE: doxygen comments here to avoid triplication in os-specific sources */
+/**
+  Set the current font, which is then used in various drawing routines,
+  You may call this outside a draw context if necessary to cal fl_width(),
+  but on X this will open the display.
+
+  The font is identified by a \a face and a \a size.
+  The size of the font is measured in pixels and not "points".
+  Lines should be spaced \a size pixels apart or more.
+*/
 FL_EXPORT void fl_font(Fl_Font face, Fl_Fontsize size);
+/** current font index */
 extern FL_EXPORT Fl_Font fl_font_;
+/**
+  Returns the \a face set by the most recent call to fl_font().
+  Tgis can be used to save/restore the font.
+*/
 inline Fl_Font fl_font() {return fl_font_;}
+/** current font size */
 extern FL_EXPORT Fl_Fontsize fl_size_;
+/**
+  Returns the \a face set by the most recent call to fl_font().
+  Tgis can be used to save/restore the font.
+*/
 inline Fl_Fontsize fl_size() {return fl_size_;}
 
 // information you can get about the current font:
+/**
+  Recommended minimum line spacing for the current font.
+  You can also use the value of \a size passed to fl_font()
+*/
 FL_EXPORT int   fl_height();	// using "size" should work ok
+/**
+  Dummy passthru function called only in Fl_Text_Display that simply returns
+  the font height as given by the \a size parameter in the same call!
+
+  \todo Is fl_height(int, int size) required for Fl_Text_Dispay?
+        Why not use \a size parameter directly?
+*/
 inline int fl_height(int, int size) {return size;}
+/**
+  Recommended distance above the bottom of a fl_height() tall box to
+  draw the text at so it looks centered vertically in that box.
+*/
 FL_EXPORT int   fl_descent();
-FL_EXPORT double fl_width(const char*);
-FL_EXPORT double fl_width(const char*, int n);
+/** Return the pixel width of a nul-terminated string */
+FL_EXPORT double fl_width(const char* txt);
+/** Return the pixel width of a sequence of \a n characters */
+FL_EXPORT double fl_width(const char* txt, int n);
+/** Return the pixed width of a single character */
 FL_EXPORT double fl_width(Fl_Unichar);
 
-// draw using current font:
-FL_EXPORT void fl_draw(const char*, int x, int y);
-FL_EXPORT void fl_draw(const char*, int n, int x, int y);
+/**
+  Draw a nul-terminated string starting at the given location.
+  Text is aligned to the left and to the baseline of the font.
+  To alighn to the bottom, subtract fl_descent() from \a y.
+  To alignn to the top, subtract fl_descent() and add fl_height().
+  This version fo fl_draw provides direct access to the text drawing
+  function of the underlying OS. It does not apply any special handling
+  to control characters.
+*/
+FL_EXPORT void fl_draw(const char* str, int x, int y);
+/**
+  Draw an array of \a n characters starting at the given location.
+*/
+FL_EXPORT void fl_draw(const char* str, int n, int x, int y);
+/**
+  Draw and array of \a n characters right to left starting at given location.
+*/
 FL_EXPORT void fl_rtl_draw(const char*, int n, int x, int y);
-FL_EXPORT void fl_measure(const char*, int& x, int& y, int draw_symbols = 1);
-FL_EXPORT void fl_draw(const char*, int,int,int,int, Fl_Align, Fl_Image* img=0,
-                       int draw_symbols = 1);
-FL_EXPORT void fl_draw(const char*, int,int,int,int, Fl_Align,
-	               void (*callthis)(const char *, int n, int x, int y),
-		       Fl_Image* img=0, int draw_symbols = 1);
+FL_EXPORT void fl_measure(const char* str, int& x, int& y,
+                          int draw_symbols = 1);
+FL_EXPORT void fl_draw(const char* str, int x, int y, int w, int h,
+                       Fl_Align align,
+                       Fl_Image* img=0, int draw_symbols = 1);
+FL_EXPORT void fl_draw(const char* str, int x, int y, int w, int h,
+                       Fl_Align align,
+                       void (*callthis)(const char *,int,int,int),
+                       Fl_Image* img=0, int draw_symbols = 1);
 
 // font encoding:
 FL_EXPORT const char *fl_latin1_to_local(const char *, int n=-1);
diff --git a/src/fl_draw.cxx b/src/fl_draw.cxx
index d321a875e..e4a617b85 100644
--- a/src/fl_draw.cxx
+++ b/src/fl_draw.cxx
@@ -119,6 +119,11 @@ fl_expand_text(const char* from, char* buf, int maxbuf, double maxw, int& n,
   return p;
 }
 
+/**
+  The same as fl_draw(const char*,int,int,int,int,Fl_Align,Fl_Image*,int) with
+  the addition of the \a callthis parameter, which is a pointer to text drawing
+  function such as fl_draw(const char*, int, int, int) to do the real work
+*/
 void fl_draw(
     const char* str,	// the (multi-line) string
     int x, int y, int w, int h,	// bounding box
@@ -265,6 +270,19 @@ void fl_draw(
   }
 }
 
+/**
+  Fancy string drawing function which is used to draw all the labels.
+  The string is formatted and aligned inside the passed box.
+  Handles '\\t' and '\\n', exapands all other control characters to '^X',
+  and aligns inside or against the edges of the box.
+  See Fl_Widget::align() for values of \a align. The value FL_ALIGN_INSIDE
+  is ignored, as this functon always prints inside the box.
+  If \a img is provided and is not \a NULL, the image is drawn above or
+  below the text as specified by the \a align value.
+  The \a draw_symbols argument specifies whether or not to look for symbol
+  names starting with the '\@' character'
+  The text length is limited to 1024 characters per line.
+*/
 void fl_draw(
   const char* str,	// the (multi-line) string
   int x, int y, int w, int h,	// bounding box
@@ -278,6 +296,14 @@ void fl_draw(
   if (align & FL_ALIGN_CLIP) fl_pop_clip();
 }
 
+/**
+  Measure how wide and tall the string will be when printed by the
+  fl_draw() function with \a align parameter. If the incoming \a w
+  is non-zero it will wrap to that width.
+  \param[in] str nul-terminated string
+  \param[out] w,h width and height of string in current font
+  \param[in] draw_symbols non-zero to enable @symbol handling [default=1]
+*/
 void fl_measure(const char* str, int& w, int& h, int draw_symbols) {
   if (!str || !*str) {w = 0; h = 0; return;}
   h = fl_height();