feat(docs): document LV_DPX(n) (#7374)

docs/details/base-widget/coord.rst

@@ -22,19 +22,57 @@ In short this means:
 - width/height means the full size, the "content area" is smaller with padding and border width
 - a subset of flexbox and grid layouts are supported
 
+
+
 .. _coord_units:
 
-Units
+Length Units
-*****
+************
 
--  pixel: Simply a position in pixels. An integer always means pixels.
+When passing "length units" (a.k.a. "distance units" or "size units") as arguments to
-   E.g. :cpp:expr:`lv_obj_set_x(btn, 10)`
+functions that modify position, size, etc., to make layout of your UI convenient, you
--  percentage: The percentage of the size of the Widget or its parent
+have a choice of several different types of units you can use.
-   (depending on the property). :cpp:expr:`lv_pct(value)` converts a value to
+
-   percentage. E.g. :cpp:expr:`lv_obj_set_width(btn, lv_pct(50))`
+:pixels:             Specify size as pixels:  an integer value <
--  :c:macro:`LV_SIZE_CONTENT`: Special value to set the width/height of an
+                     :c:macro:`LV_COORD_MAX` always means pixels.  E.g.
-   Widget to involve all the children. It's similar to ``auto`` in CSS.
+                     :cpp:expr:`lv_obj_set_x(btn, 10)`.
-   E.g. :cpp:expr:`lv_obj_set_width(btn, LV_SIZE_CONTENT)`.
+
+:percentage:         Specify size as a percentage of the size of the Widget's
+                     parent or of itself, depending on the property.
+                     :cpp:expr:`lv_pct(value)` converts ``value`` to a percentage.
+                     E.g. :cpp:expr:`lv_obj_set_width(btn, lv_pct(50))`.  If you want
+                     to avoid the overhead of the call to :cpp:func:`lv_pct`, you can
+                     also use the macro :c:macro:`LV_PCT(x)` to mean the same thing.
+                     Note that when you use this feature, your value is *stored as a
+                     percent* so that if/when the size of the parent container (or
+                     other positioning factor) changes, this style value dynamically
+                     retains its meaning.
+
+:contained content:  Specify size as a function of the Widget's children.  The macro
+                     :c:macro:`LV_SIZE_CONTENT`: passed as a size value has special
+                     meaning:  it means to set the width and/or height of a Widget
+                     just large enough to include all of its children.  This is
+                     similar to ``auto`` in CSS.  E.g.
+                     :cpp:expr:`lv_obj_set_width(btn, LV_SIZE_CONTENT)`.
+
+:inches:             Specify size as 1/160-th portion of an inch as if it were pixels
+                     on a 160-DPI display, even though a display may have a different
+                     DPI.  Use :cpp:expr:`lv_dpx(n)` or :c:macro:`LV_DPX(n)` to do
+                     this.  Examples:
+
+                     +----+-----+----------------------------+
+                     | n  | DPI | Computed Pixels            |
+                     +====+=====+============================+
+                     | 40 | 320 | 80 pixels to make 1/4 inch |
+                     +----+-----+----------------------------+
+                     | 40 | 160 | 40 pixels to make 1/4 inch |
+                     +----+-----+----------------------------+
+                     | 40 | 130 | 33 pixels to make 1/4 inch |
+                     +----+-----+----------------------------+
+                     | 80 | 130 | 66 pixels to make 1/2 inch |
+                     +----+-----+----------------------------+
+
+                     See DPI under :ref:`display_features`.
 
 
 
@@ -60,6 +98,8 @@ keeps a "padding margin" when placing a Widget's children.
 
 The outline is drawn outside the bounding box.
 
+
+
 .. _coord_notes:
 
 Important Notes
@@ -86,6 +126,8 @@ The size and position might depend on the parent or layout. Therefore
 :cpp:func:`lv_obj_update_layout` recalculates the coordinates of all Widgets on
 the screen of ``obj``.
 
+
+
 .. _coord_removing styles:
 
 Removing styles

docs/details/main-components/display.rst

@@ -52,6 +52,8 @@ it is representing, as well as other things relevant to its lifetime:
 - Resolution (width and height in pixels)
 - Color Depth (bits per pixel)
 - Color Format (how colors in pixels are laid out)
+- DPI (default is configured :c:macro:`LV_DPI_DEF` in ``lv_conf.h``, but can be
+  modified with :cpp:expr:`lv_display_set_dpi(disp, new_dpi)`).
 - 4 :ref:`screen_layers` automatically created with each display
 - All :ref:`screens` created in association with this display (and not yet deleted---only
   one is dislayed at any given time)

src/display/lv_display.h

@@ -593,32 +593,37 @@ void lv_display_rotate_area(lv_display_t * disp, lv_area_t * area);
 #endif
 
 /**
+ * See `lv_dpx()` and `lv_display_dpx()`.
  * Same as Android's DIP. (Different name is chosen to avoid mistype between LV_DPI and LV_DIP)
- * 1 dip is 1 px on a 160 DPI screen
+ *
- * 1 dip is 2 px on a 320 DPI screen
+ * - 40 dip is 40 px on a 160 DPI screen (distance = 1/4 inch).
- * https://stackoverflow.com/questions/2025282/what-is-the-difference-between-px-dip-dp-and-sp
+ * - 40 dip is 80 px on a 320 DPI screen (distance still = 1/4 inch).
+ *
+ * @sa https://stackoverflow.com/questions/2025282/what-is-the-difference-between-px-dip-dp-and-sp
  */
 #define LV_DPX_CALC(dpi, n)   ((n) == 0 ? 0 :LV_MAX((( (dpi) * (n) + 80) / 160), 1)) /*+80 for rounding*/
 #define LV_DPX(n)   LV_DPX_CALC(lv_display_get_dpi(NULL), n)
 
 /**
- * Scale the given number of pixels (a distance or size) relative to a 160 DPI display
+ * For default display, computes the number of pixels (a distance or size) as if the
- * considering the DPI of the default display.
+ * display had 160 DPI.  This allows you to specify 1/160-th fractions of an inch to
- * It ensures that e.g. `lv_dpx(100)` will have the same physical size regardless to the
+ * get real distance on the display that will be consistent regardless of its current
- * DPI of the display.
+ * DPI.  It ensures `lv_dpx(100)`, for example, will have the same physical size
- * @param n     the number of pixels to scale
+ * regardless to the DPI of the display.
- * @return      `n x current_dpi/160`
+ * @param n     number of 1/160-th-inch units to compute with
+ * @return      number of pixels to use to make that distance
  */
 int32_t lv_dpx(int32_t n);
 
 /**
- * Scale the given number of pixels (a distance or size) relative to a 160 DPI display
+ * For specified display, computes the number of pixels (a distance or size) as if the
- * considering the DPI of the given display.
+ * display had 160 DPI.  This allows you to specify 1/160-th fractions of an inch to
- * It ensures that e.g. `lv_dpx(100)` will have the same physical size regardless to the
+ * get real distance on the display that will be consistent regardless of its current
- * DPI of the display.
+ * DPI.  It ensures `lv_dpx(100)`, for example, will have the same physical size
- * @param disp   a display whose dpi should be considered
+ * regardless to the DPI of the display.
- * @param n     the number of pixels to scale
+ * @param disp  pointer to display whose dpi should be considered
- * @return      `n x current_dpi/160`
+ * @param n     number of 1/160-th-inch units to compute with
+ * @return      number of pixels to use to make that distance
  */
 int32_t lv_display_dpx(const lv_display_t * disp, int32_t n);