From ebf71d633b39f82437f440917729767e5572a61e Mon Sep 17 00:00:00 2001
From: Greg Ercolano <erco@seriss.com>
Date: Tue, 8 May 2012 16:15:34 +0000
Subject: [PATCH] Documentation improvements: 	o Added fl_text_extents() to
 the 'Drawing things in FLTK' section 	o Added 'see also' sections to all the
 text measuring functions in that section 	o Added detail to
 fl_text_extents() docs regarding it not handling FLTK symbols, 	  as
 non-public comment for that method indicates.

git-svn-id: file:///fltk/svn/fltk/branches/branch-1.3@9463 ea41ed52-d2ee-0310-a9c1-e6b18d33e121
---
 FL/fl_draw.H                  |  2 ++
 documentation/src/drawing.dox | 32 +++++++++++++++++++++++++++++++-
 2 files changed, 33 insertions(+), 1 deletion(-)

diff --git a/FL/fl_draw.H b/FL/fl_draw.H
index 62b7f58dce..be819de338 100644
--- a/FL/fl_draw.H
+++ b/FL/fl_draw.H
@@ -528,6 +528,8 @@ inline double fl_width(unsigned int c)  {return fl_graphics_driver->width(c);}
   such that a bounding box that exactly fits around the text could be drawn with
   fl_rect(x+dx, y+dy, wo, ho). Note the dx, dy values hold the offset of the first
   "colored in" pixel of the string, from the draw origin.
+
+  No FLTK symbol expansion will be performed.
 */
 FL_EXPORT void fl_text_extents(const char*, int& dx, int& dy, int& w, int& h); // NO fltk symbol expansion will be performed
 /** Determines the minimum pixel dimensions of a sequence of \p n characters.
diff --git a/documentation/src/drawing.dox b/documentation/src/drawing.dox
index b5c69c4b17..e0981d051e 100644
--- a/documentation/src/drawing.dox
+++ b/documentation/src/drawing.dox
@@ -627,8 +627,18 @@ void fl_measure(const char *str, int& w, int& h, int draw_symbols)
 
 \par
 Measure how wide and tall the string will be when printed by
-the \p fl_draw(...align) function.
+the \p fl_draw(...align) function. This includes leading/trailing
+white space in the string, kerning, etc.
+\par
 If the incoming \p w is non-zero it will wrap to that width.
+\par
+Refer to the full documentation for fl_measure() for details
+on usage and how to avoide common pitfalls.
+
+\see fl_text_extents() -- measure the 'inked' area of a string
+\see fl_width() -- measure the pixel width of a string or single character
+\see fl_height() -- measure the pixel height of the current font
+\see fl_descent() -- the height of the descender for the current font
 
 int fl_height()
 
@@ -637,6 +647,8 @@ Recommended minimum line spacing for the current font.  You
 can also just use the value of \p size passed to
 \ref drawing_fl_font "fl_font()".
 
+\see fl_text_extents(), fl_measure(), fl_width(), fl_descent()
+
 int fl_descent()
 
 \par
@@ -651,6 +663,24 @@ double fl_width(unsigned int unicode_char)
 Return the pixel width of a nul-terminated string, a sequence of \p n
 characters, or a single character in the current font.
 
+\see fl_measure(), fl_text_extents(), fl_height(), fl_descent()
+
+void fl_text_extents(const char* txt, int& dx, int& dy, int& w, int& h)
+
+\par
+Determines the minimum pixel dimensions of a nul-terminated string,
+ie. the 'inked area'.
+\par
+Given a string "txt" drawn using fl_draw(txt, x, y) you would determine
+its pixel extents on the display using fl_text_extents(txt, dx, dy, wo, ho)
+such that a bounding box that exactly fits around the inked area of the text
+could be drawn with fl_rect(x+dx, y+dy, wo, ho). 
+\par
+Refer to the full documentation for fl_text_extents() for details
+on usage.
+
+\see fl_measure(), fl_width(), fl_height(), fl_descent()
+
 const char* fl_shortcut_label(int shortcut)
 
 \par