mirrors/fltk
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

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

Browse Source 
git-svn-id: file:///fltk/svn/fltk/branches/branch-1.3-porting@11848 ea41ed52-d2ee-0310-a9c1-e6b18d33e121
This commit is contained in:
Albrecht Schlosser 2016-07-24 08:55:02 +00:00
parent 54dcf145fe
commit a633de6461
2 changed files with 25 additions and 10 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

21
documentation/src/drawing.dox
View File

@ -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)

14
src/fl_draw.cxx
View File

@ -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.