From f38d1cf42490a1719a96528143e863b3a4b9f999 Mon Sep 17 00:00:00 2001
From: ManoloFLTK <41016272+ManoloFLTK@users.noreply.github.com>
Date: Tue, 12 Dec 2023 10:08:08 +0100
Subject: Documentation: fix outdated statements of quantities being expressed
 in pixels

---
 documentation/src/basics.dox   | 11 +++++++----
 documentation/src/drawing.dox  | 14 +++++++++-----
 documentation/src/osissues.dox |  2 +-
 3 files changed, 17 insertions(+), 10 deletions(-)

(limited to 'documentation/src')

diff --git a/documentation/src/basics.dox b/documentation/src/basics.dox
index 418533ec8..e875108ab 100644
--- a/documentation/src/basics.dox
+++ b/documentation/src/basics.dox
@@ -95,14 +95,17 @@ Fl_Widget(x, y, width, height, label)
 The \p x and \p y parameters determine where the
 widget or window is placed on the screen. In FLTK the top left
 corner of the window or screen is the origin
-(i.e. <tt>x = 0, y = 0</tt>)
-and the units are in pixels.
+(i.e. <tt>x = 0, y = 0</tt>).
 
 The \p width and \p height parameters determine
-the size of the widget or window in pixels. The maximum widget
+the size of the widget or window. The maximum widget
 size is typically governed by the underlying window system or
 hardware.
 
+\ref drawing_DrawingUnit describes the unit FLTK employs for
+<tt>x, y, width</tt>, and \c height, and more generally, for
+all graphical quantities.
+
 \p label is a pointer to a character string to label
 the widget with or \p NULL. If not specified the label
 defaults to \p NULL. The label string must be in static
@@ -170,7 +173,7 @@ The \p labelfont() method sets the typeface and style
 that is used for the label, which for this example we are using
 \p FL_BOLD and \p FL_ITALIC.
 
-The \p labelsize() method sets the height of the font in pixels.
+The \p labelsize() method sets the height of the font in FLTK units.
 
 The \p labeltype()
 method sets the type of label. FLTK supports normal, embossed,
diff --git a/documentation/src/drawing.dox b/documentation/src/drawing.dox
index bf7c03717..e70f12e76 100644
--- a/documentation/src/drawing.dox
+++ b/documentation/src/drawing.dox
@@ -35,7 +35,7 @@ these will operate on the new current drawing surface;
 Fl_Surface_Device::pop_current().
 </ol>
 
-\section drawing_DrawingUnit What Drawing Units Do FLTK Drawing Functions Use?
+\section drawing_DrawingUnit What Units Do FLTK Functions Use?
 
 Before version 1.4 all graphical quantities used by FLTK were in pixel units:
 a window of width 500 units was 500 pixels wide, a line of length 10 units was
@@ -54,8 +54,11 @@ a twice higher DPI. If the first screen's scale factor is set to 1 and that of t
 second screen to 2, the GUI of any FLTK app appears equally sized on the two screens.
 
 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.
+<ul><li>All quantities used by the public FLTK API to measure graphical elements
+(e.g., window widths, line lengths, font sizes, clipping regions, image widths and heights)
+are in <b>FLTK units</b> except if it's explicitly documented another unit is used.
+FLTK units are both platform- and DPI-independent. An example of FLTK API using
+another unit is Fl_Gl_Window::pixel_w().
 <li>Just before drawing to a screen, the library internally multiplies all quantities
 expressed in FLTK units by the current value of the scale factor
 for the screen in use and obtains quantities in <b>drawing units</b>.
@@ -96,8 +99,9 @@ image type, the platform and some hardware features. The most common
 case for Fl_RGB_Image's is that FLTK uses a scaled drawing system feature that directly
 maps image data to screen pixels. An important feature of FLTK for image drawing
 is the Fl_Image::scale() member function, new in FLTK version 1.4. This function
-controls the image drawing size (in FLTK units) independently from the size
-of the image data. An image with large enough data size can thus be drawn at the
+controls the image drawing size (in FLTK units, given by Fl_Image::w() and Fl_Image::h())
+independently from the size of the image data (given by Fl_Image::data_w() and
+Fl_Image::data_h()). An image with large enough data size can thus be drawn at the
 full resolution of the screen even when the screen area covered by the image grows
 following the GUI scale factor.
 
diff --git a/documentation/src/osissues.dox b/documentation/src/osissues.dox
index 085f30b58..fa17aec7e 100644
--- a/documentation/src/osissues.dox
+++ b/documentation/src/osissues.dox
@@ -1044,7 +1044,7 @@ cannot call any FLTK functions.
 FLTK Wayland apps automatically scale according to the Wayland-defined, integer-valued
 scale factor. On a HiDPI display, it's enough to set this factor to 2 for
 any FLTK app to be drawn using twice as many pixels and thus to be as readable
-as it is on a regular display. With the gnome desktop, that is achieved in the
+as it is on a regular display. With the gnome and KDE-plasma desktops, that is achieved in the
 "Displays" section of the "Settings" application, selecting 200 % for the "Scale" parameter.
 In addition to this, FLTK apps can also be scaled up or down typing ctrl/+/-/0/
 and with the \c FLTK_SCALING_FACTOR environment variable.
-- 
cgit v1.2.3