From a633de6461f5f494d105c957d6efd43dadb193d4 Mon Sep 17 00:00:00 2001 From: Albrecht Schlosser Date: Sun, 24 Jul 2016 08:55:02 +0000 Subject: [PATCH] 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 --- documentation/src/drawing.dox | 21 ++++++++++++++++----- src/fl_draw.cxx | 14 +++++++++----- 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.