diff --git a/docs/details/base-widget/coord.rst b/docs/details/base-widget/coord.rst index 813ed71f7..f00545ff0 100644 --- a/docs/details/base-widget/coord.rst +++ b/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. - 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 diff --git a/docs/details/main-components/display.rst b/docs/details/main-components/display.rst index c70d7a31a..c25360c08 100644 --- a/docs/details/main-components/display.rst +++ b/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) diff --git a/src/display/lv_display.h b/src/display/lv_display.h index 76ac876f2..fad80a5c7 100644 --- a/src/display/lv_display.h +++ b/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 - * 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);