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

Documentation: describe the new GUI scaling feature of FLTK 1.4

Browse Source 
git-svn-id: file:///fltk/svn/fltk/branches/branch-1.4@12731 ea41ed52-d2ee-0310-a9c1-e6b18d33e121
This commit is contained in:
Manolo Gouy 2018-03-10 17:29:25 +00:00
parent 1cf4371b69
commit 329f43eaf7
1 changed files with 61 additions and 9 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

70
documentation/src/drawing.dox
View File

@ -37,18 +37,70 @@ Fl_Surface_Device::pop_current().
\subsection ssect_DrawingUnit What Drawing Unit do FLTK drawing functions use?
When drawing to the display or to instances of Fl_Copy_Surface and Fl_Image_Surface,
the unit of drawing functions corresponds
generally to one pixel. The so-called 'retina' displays of some recent
Apple computers are an exception to this rule: one drawing unit corresponds
to the width or the height of 2 display pixels on a retina display.
Before version 1.4, all graphical quantities used by FLTK are in pixel units:
a window of width 500 units is 500-pixel wide, a line of length 10 units is
10-pixel long, lines of text written using a 14-point font are 14 pixels below
each other. This organization is not sufficient to support GUI apps that can be drawn on
displays of varying pixel density, especially on High-DPI displays, because
widgets become very small and text becomes unreadable.
When drawing to surfaces that are instances of Fl_Paged_Device
derived classes (i.e., Fl_Printer or Fl_PostScript_File_Device), the drawing unit
is initially one point, that is, 1/72 of an inch. But this unit is changed
after calls to Fl_Paged_Device::scale().
FLTK version 1.4 introduces a new feature, a display-specific <b>scale factor</b> which is
a float number with a typical value in the 1-2.5 range and is used as follows: any graphical
element with an FLTK value of \e v units is drawn on the display with \e v * \e scale units.
Thus, a window with width 500 units is 500*scale-pixel wide, a line of length 10 units is
10*scale-pixel long, lines of text written using a 14-point font are 14*scale pixels below
each other. Consider a system with two displays, one with regular DPI and one with
a twice higher DPI. If the first display's scale factor is set to 1 and that of the
second display to 2, the GUI of any FLTK app appears equally sized on the two displays.
FLTK uses several units to measure graphical elements:
<ul><li>All data visible by the public API (e.g., window widths, line lengths, font sizes,
clipping regions) are in <b>FLTK units</b> which are both system- and DPI-independent.
<li>Just before drawing to a display, the library internally multiplies all quantities
expressed in FLTK units by the current value of the scale factor
for the display in use and obtains quantities in <b>drawing units</b>.
The current scale factor value, for an Fl_Window named \e window, is given by
\code
int nscreen = window->driver()->screen_num(); // the screen where window is mapped
float s = Fl::screen_driver()->scale(nscreen); // this screen's scale factor
\endcode
One drawing unit generally corresponds to one display pixel...
<li>...but not on Mac OS X and for retina displays, where drawing units correspond
to two pixels.
</ul>
At application start time, FLTK attempts to detect the adequate scale factor value for
each display of the system. If this attempt fails, it's possible to set the
<tt>FLTK_SCALING_FACTOR</tt> environmental variable to the desired numerical value
(e.g., 1.75) and any FLTK app will start scaled with that value. Furthermore,
it's possible to change the scale factor value of any display at run time
with ctrl/+/-/0/ keystrokes which enlarge, shrink, and reset, respectively,
the GUI of all FLTK windows on a display.
Under Mac OS X, the corresponding GUI scaling shortcuts are cmd/+/-/0/.
When drawing images to a display whose scale value is > 1, the image pixel data
are mapped to the larger number of pixels present in
a display area sized (in FLTK units) as the image. This operation is done internally
by the library using diverse scaling methods that vary with the image type
(Fl_Pixmap, Fl_Bitmap or Fl_RGB_Image) and the platform.
A situation of special interest arises when drawing Fl_Shared_Image's. The
Fl_Shared_Image::scale() member function allows to set the image drawing size
(in FLTK units) independently of its pixel size. Image pixels are mapped to the
pixels of the image drawing area on the display which is determined by the scale
factor value. Therefore, the image data can fill the drawing area of the display at
full physical resolution even for high scale values if the original image is large enough.
The Fl_Image_Surface class is intended to create an Fl_RGB_Image from a series
of FLTK drawing operations. The Fl_Image_Surface constructor allows to control
whether the size in pixels of the resulting image matches the FLTK units used when
performing drawing operations, or matches the number of pixels corresponding to
these FLTK units given the current scale factor value. The first result is obtained
with <tt>new Fl_Image_Surface(w, h)</tt>, the second with
<tt>new Fl_Image_Surface(w, h, 1)</tt>.
When drawing to Fl_Printer or Fl_PostScript_File_Device, the drawing unit
is initially one point, that is, 1/72 of an inch. This unit is changed
by calls to Fl_Paged_Device::scale().
\section sect_DrawingFunctions Drawing Functions