github-code/lvgl
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source
This commit is contained in:
Victor Wheeler
2024-12-03 08:46:19 -07:00
committed by GitHub
parent 4a7c0de1c6
commit 5bccba9946
3 changed files with 75 additions and 26 deletions
Download Patch File Download Diff File Expand all files Collapse all files

62
docs/details/base-widget/coord.rst
View File

@@ -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.
E.g. :cpp:expr:`lv_obj_set_x(btn, 10)`
- percentage: The percentage of the size of the Widget or its parent
(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))`
- :c:macro:`LV_SIZE_CONTENT`: Special value to set the width/height of an
Widget to involve all the children. It's similar to ``auto`` in CSS.
E.g. :cpp:expr:`lv_obj_set_width(btn, LV_SIZE_CONTENT)`.
When passing "length units" (a.k.a. "distance units" or "size units") as arguments to
functions that modify position, size, etc., to make layout of your UI convenient, you
have a choice of several different types of units you can use.
:pixels: Specify size as pixels: an integer value <
:c:macro:`LV_COORD_MAX` always means pixels. E.g.
:cpp:expr:`lv_obj_set_x(btn, 10)`.
: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

2
docs/details/main-components/display.rst
View File

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

37
src/display/lv_display.h
View File

@@ -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
* https://stackoverflow.com/questions/2025282/what-is-the-difference-between-px-dip-dp-and-sp
*
* - 40 dip is 40 px on a 160 DPI screen (distance = 1/4 inch).
* - 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
* considering the DPI of the default display.
* It ensures that e.g. `lv_dpx(100)` will have the same physical size regardless to the
* DPI of the display.
* @param n the number of pixels to scale
* @return `n x current_dpi/160`
* For default display, computes the number of pixels (a distance or size) as if the
* display had 160 DPI. This allows you to specify 1/160-th fractions of an inch to
* get real distance on the display that will be consistent regardless of its current
* DPI. It ensures `lv_dpx(100)`, for example, will have the same physical size
* regardless to the DPI of the display.
* @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
* considering the DPI of the given display.
* It ensures that e.g. `lv_dpx(100)` will have the same physical size regardless to the
* DPI of the display.
* @param disp a display whose dpi should be considered
* @param n the number of pixels to scale
* @return `n x current_dpi/160`
* For specified display, computes the number of pixels (a distance or size) as if the
* display had 160 DPI. This allows you to specify 1/160-th fractions of an inch to
* get real distance on the display that will be consistent regardless of its current
* DPI. It ensures `lv_dpx(100)`, for example, will have the same physical size
* regardless to the DPI of the display.
* @param disp pointer to display whose dpi should be considered
* @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);