Doc changes: set fl_font before fl_measure() (STR #3243)

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

2 files changed, 25 insertions, 10 deletions

diff --git a/documentation/src/drawing.dox b/documentation/src/drawing.dox
index c523bd4eb..b36bd3c6a 100644
--- a/documentation/src/drawing.dox
+++ b/documentation/src/drawing.dox
@@ -659,19 +659,21 @@ white space in the string, kerning, etc.
 \par
 If the incoming \p w is non-zero it will wrap to that width.
 \par
+This will probably give unexpected values unless you have called
+\ref drawing_fl_font "fl_font()" explicitly in your own code.
 Refer to the full documentation for fl_measure() for details
 on usage and how to avoid 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
+\see fl_height() -- measure the pixel height of the \ref drawing_fl_font "current font"
+\see fl_descent() -- the height of the descender for the \ref drawing_fl_font "current font"
 
 int fl_height()
 
 \par
-Recommended minimum line spacing for the current font.  You
-can also just use the value of \p size passed to
+Recommended minimum line spacing for the \ref drawing_fl_font "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()
@@ -688,7 +690,7 @@ double fl_width(unsigned int unicode_char)
 
 \par
 Return the pixel width of a nul-terminated string, a sequence of \p n
-characters, or a single character in the current font.
+characters, or a single character in the \ref drawing_fl_font "current font".
 
 \see fl_measure(), fl_text_extents(), fl_height(), fl_descent()
 
@@ -733,6 +735,15 @@ these, and FL_SYMBOL and FL_ZAPF_DINGBATS.
 Faces greater than 255 cannot be used in Fl_Widget
 labels, since Fl_Widget stores the index as a byte.
 
+One important thing to note about 'current font' is that there
+are so many paths through the GUI event handling code as widgets
+are partially or completely hidden, exposed and then re-drawn
+and therefore you can not guarantee that 'current font' contains
+the same value that you set on the other side of the event loop.
+Your value may have been superseded when a widget was redrawn.
+You are strongly advised to set the font explicitly before you
+draw any text or query the width and height of text strings, etc.
+
 \anchor drawing_fl_font
 void fl_font(int face, int size)
 
diff --git a/src/fl_draw.cxx b/src/fl_draw.cxx
index bf02f9d8e..d6e184002 100644
--- a/src/fl_draw.cxx
+++ b/src/fl_draw.cxx
@@ -3,7 +3,7 @@
 //
 // Label drawing code for the Fast Light Tool Kit (FLTK).
 //
-// Copyright 1998-2011 by Bill Spitzak and others.
+// Copyright 1998-2016 by Bill Spitzak and others.
 //
 // This library is free software. Distribution and use rights are outlined in
 // the file "COPYING" which should have been included with this file.  If this
@@ -118,7 +118,7 @@ static const char* expand_text_(const char* from, char*& buf, int maxbuf, double
  Also word-wrap if width exceeds maxw.
  Returns a pointer to the start of the next line of characters.
  Sets n to the number of characters put into the buffer.
- Sets width to the width of the string in the current font.
+ Sets width to the width of the string in the \ref drawing_fl_font "current font".
  */
 const char*
 fl_expand_text(const char* from, char* buf, int maxbuf, double maxw, int& n,
@@ -343,9 +343,13 @@ void fl_draw(
   fl_draw() function with \p align parameter. If the incoming \p w
   is non-zero it will wrap to that width.
 
-  The 'current font' is used to do the width/height calculations,
-  so unless its value is known at the time fl_measure() is called,
-  it is advised to first set the current font with fl_font().
+  The \ref drawing_fl_font "current font" is used to do the width/height
+  calculations, so unless its value is known at the time fl_measure() is
+  called, it is advised to first set the current font with fl_font().
+  With event-driven GUI programming you can never be sure which
+  widget was exposed and redrawn last, nor which font it used.
+  If you have not called fl_font() explicitly in your own code,
+  the width and height may be set to unexpected values, even zero!
 
   \b Note: In the general use case, it's a common error to forget to set
   \p w to 0 before calling fl_measure() when wrap behavior isn't needed.