diff --git a/docs/CHANGELOG.rst b/docs/CHANGELOG.rst index bd24c2e5f..45e921b29 100644 --- a/docs/CHANGELOG.rst +++ b/docs/CHANGELOG.rst @@ -39,7 +39,7 @@ Main new features - `lv_observer `__ allows to bind data to UI elements and create a uniform and easy to maintain API - GitHub CodeSpace integration makes possible to run LVGL in an Online VSCode editor with 3 click. See more `here `__ - Add vector graphics support via ThorVG. It can be used to draw vector graphics to a `Canvas `__ -- `lv_image `__ supports aligning, stretching or tiling the image source if the widget is larger or smaller. +- :ref:`lv_image` supports aligning, stretching or tiling the image source if the widget is larger or smaller. General API changes ------------------- diff --git a/docs/ROADMAP.rst b/docs/ROADMAP.rst index 971c344e3..311212f70 100644 --- a/docs/ROADMAP.rst +++ b/docs/ROADMAP.rst @@ -155,7 +155,7 @@ Others - |uncheck| Scene support. See `this comment `__ - |uncheck| Circle layout. #2871 - |uncheck| Consider `stagger animations `__. -- |uncheck| Add custom indev type. See [here](https://github.com/lvgl/lvgl/issues/3298#issuecomment-1616706654). +- |uncheck| Add custom indev type. See `here `__. - |uncheck| Automatically recalculate the layout if a coordinate is obtained using `lv_obj_get_width/height/x/y/etc` Ideas diff --git a/docs/get-started/index.rst b/docs/get-started/index.rst index 2606f929e..bd17f3956 100644 --- a/docs/get-started/index.rst +++ b/docs/get-started/index.rst @@ -1,3 +1,5 @@ +.. _get_started: + =========== Get started =========== diff --git a/docs/get-started/quick-overview.rst b/docs/get-started/quick-overview.rst index b84515467..34a080a0c 100644 --- a/docs/get-started/quick-overview.rst +++ b/docs/get-started/quick-overview.rst @@ -108,6 +108,8 @@ section. Learn the basics ---------------- +.. _quick-overview_widgets: + Widgets ~~~~~~~ @@ -160,6 +162,8 @@ To see the full API visit the documentation of the widgets or the related header file (e.g. `lvgl/src/widgets/slider/lv_slider.h `__). +.. _quick-overview_events: + Events ~~~~~~ @@ -197,12 +201,14 @@ The object that triggered the event can be retrieved with: To learn all features of the events go to the :ref:`events` section. +.. _quick-overview_parts: + Parts ~~~~~ Widgets might be built from one or more *parts*. For example, a button has only one part called :cpp:enumerator:`LV_PART_MAIN`. However, a -:ref:`slider` has :cpp:enumerator:`LV_PART_MAIN`, :cpp:enumerator:`LV_PART_INDICATOR` +:ref:`lv_slider` has :cpp:enumerator:`LV_PART_MAIN`, :cpp:enumerator:`LV_PART_INDICATOR` and :cpp:enumerator:`LV_PART_KNOB`. By using parts you can apply different styles to sub-elements of a @@ -210,6 +216,8 @@ widget. (See below) Read the widgets' documentation to learn which parts each uses. +.. _quick-overview_states: + States ~~~~~~ @@ -241,6 +249,8 @@ To manually add or remove states use: lv_obj_add_state(obj, LV_STATE_...); lv_obj_remove_state(obj, LV_STATE_...); +.. _quick-overview_styles: + Styles ~~~~~~ @@ -260,7 +270,7 @@ configure the style. For example: lv_style_set_bg_color(&style1, lv_color_hex(0xa03080)) lv_style_set_border_width(&style1, 2)) -See the full list of properties here :ref:`style_properties`. +See the full list of properties here :ref:`styles_properties`. Styles are assigned using the ORed combination of an object's part and state. For example to use this style on the slider's indicator when the @@ -316,6 +326,8 @@ style which resides inside the object and is used only by the object: To learn all the features of styles see the :ref:`styles` section. +.. _quick-overview_themes: + Themes ~~~~~~ @@ -325,11 +337,15 @@ applied automatically when objects are created. The theme for your application is a compile time configuration set in ``lv_conf.h``. +.. _quick-overview_examples: + Examples -------- .. include:: ../examples/get_started/index.rst +.. _quick-overview_micropython: + Micropython ----------- diff --git a/docs/intro/index.rst b/docs/intro/index.rst index 29f37985b..345716389 100644 --- a/docs/intro/index.rst +++ b/docs/intro/index.rst @@ -41,7 +41,7 @@ Basically, every modern controller which is able to drive a display is suitable * Static RAM usage: ~2 kB depending on the used features and object types * stack: > 2kB (> 8 kB is recommended) * Dynamic data (heap): > 2 KB (> 48 kB is recommended if using several objects). - Set by :c:macro:`LV_MEM_SIZE` in `lv_conf.h`. + Set by :c:macro:`LV_MEM_SIZE` in ``lv_conf.h``. * Display buffer: > *"Horizontal resolution"* pixels (> 10 *"Horizontal resolution"* is recommended) * One frame buffer in the MCU or in an external display controller * C99 or newer compiler @@ -196,7 +196,7 @@ LVGL doesn't start, randomly crashes or nothing is drawn on the display. What ca * Be sure :cpp:type:`lv_disp_t`, :cpp:type:`lv_indev_t` and :cpp:type:`lv_fs_drv_t` are global or `static`. * Be sure your display works without LVGL. E.g. paint it to red on start up. * Enable :ref:`logging` -* Enable asserts in `lv_conf.h` (`LV_USE_ASSERT_...`) +* Enable asserts in ``lv_conf.h`` (`LV_USE_ASSERT_...`) * If you use an RTOS * increase the stack size of the task which calls :cpp:func:`lv_timer_handler` * Be sure you used a mutex as described here: :ref:`os_interrupt` diff --git a/docs/layouts/flex.rst b/docs/layouts/flex.rst index c3fb8937e..b3eebabd7 100644 --- a/docs/layouts/flex.rst +++ b/docs/layouts/flex.rst @@ -1,3 +1,5 @@ +.. _flex: + ==== Flex ==== @@ -13,7 +15,7 @@ the item(s) fill the remaining space with respect to min/max width and height. To make an object flex container call -:c:expr:`lv_obj_set_layout(obj, LV_LAYOUT_FLEX)`. +:cpp:expr:`lv_obj_set_layout(obj, LV_LAYOUT_FLEX)`. Note that the flex layout feature of LVGL needs to be globally enabled with :c:macro:`LV_USE_FLEX` in ``lv_conf.h``. @@ -36,30 +38,34 @@ Simple interface With the following functions you can set a Flex layout on any parent. +.. _flex_flow: + Flex flow --------- -:c:expr:`lv_obj_set_flex_flow(obj, flex_flow)` +:cpp:expr:`lv_obj_set_flex_flow(obj, flex_flow)` The possible values for ``flex_flow`` are: -- :c:enumerator:`LV_FLEX_FLOW_ROW`: Place the children in a row without wrapping -- :c:enumerator:`LV_FLEX_FLOW_COLUMN`: Place the children in a column without wrapping -- :c:enumerator:`LV_FLEX_FLOW_ROW_WRAP`: Place the children in a row with wrapping -- :c:enumerator:`LV_FLEX_FLOW_COLUMN_WRAP`: Place the children in a column with wrapping -- :c:enumerator:`LV_FLEX_FLOW_ROW_REVERSE`: Place the children in a row without wrapping but in reversed order -- :c:enumerator:`LV_FLEX_FLOW_COLUMN_REVERSE`: Place the children in a column without wrapping but in reversed order -- :c:enumerator:`LV_FLEX_FLOW_ROW_WRAP_REVERSE`: Place the children in a row with wrapping but in reversed order -- :c:enumerator:`LV_FLEX_FLOW_COLUMN_WRAP_REVERSE`: Place the children in a column with wrapping but in reversed order +- :cpp:enumerator:`LV_FLEX_FLOW_ROW`: Place the children in a row without wrapping +- :cpp:enumerator:`LV_FLEX_FLOW_COLUMN`: Place the children in a column without wrapping +- :cpp:enumerator:`LV_FLEX_FLOW_ROW_WRAP`: Place the children in a row with wrapping +- :cpp:enumerator:`LV_FLEX_FLOW_COLUMN_WRAP`: Place the children in a column with wrapping +- :cpp:enumerator:`LV_FLEX_FLOW_ROW_REVERSE`: Place the children in a row without wrapping but in reversed order +- :cpp:enumerator:`LV_FLEX_FLOW_COLUMN_REVERSE`: Place the children in a column without wrapping but in reversed order +- :cpp:enumerator:`LV_FLEX_FLOW_ROW_WRAP_REVERSE`: Place the children in a row with wrapping but in reversed order +- :cpp:enumerator:`LV_FLEX_FLOW_COLUMN_WRAP_REVERSE`: Place the children in a column with wrapping but in reversed order + +.. _flex_align: Flex align ---------- To manage the placement of the children use -:c:expr:`lv_obj_set_flex_align(obj, main_place, cross_place, track_cross_place)` +:cpp:expr:`lv_obj_set_flex_align(obj, main_place, cross_place, track_cross_place)` - ``main_place`` determines how to distribute the items in their track - on the main axis. E.g. flush the items to the right on :c:enumerator:`LV_FLEX_FLOW_ROW_WRAP`. (It's called + on the main axis. E.g. flush the items to the right on :cpp:enumerator:`LV_FLEX_FLOW_ROW_WRAP`. (It's called ``justify-content`` in CSS) - ``cross_place`` determines how to distribute the items in their track on the cross axis. E.g. if the items have different height place them @@ -69,37 +75,44 @@ To manage the placement of the children use The possible values are: -- :c:enumerator:`LV_FLEX_ALIGN_START`: means left on a horizontally and top vertically. (default) -- :c:enumerator:`LV_FLEX_ALIGN_END`: means right on a horizontally and bottom vertically -- :c:enumerator:`LV_FLEX_ALIGN_CENTER`: simply center -- :c:enumerator:`LV_FLEX_ALIGN_SPACE_EVENLY`: items are distributed so +- :cpp:enumerator:`LV_FLEX_ALIGN_START`: means left on a horizontally and top vertically. (default) +- :cpp:enumerator:`LV_FLEX_ALIGN_END`: means right on a horizontally and bottom vertically +- :cpp:enumerator:`LV_FLEX_ALIGN_CENTER`: simply center +- :cpp:enumerator:`LV_FLEX_ALIGN_SPACE_EVENLY`: items are distributed so that the spacing between any two items (and the space to the edges) is equal. Does not apply to ``track_cross_place``. -- :c:enumerator:`LV_FLEX_ALIGN_SPACE_AROUND`: items are evenly +- :cpp:enumerator:`LV_FLEX_ALIGN_SPACE_AROUND`: items are evenly distributed in the track with equal space around them. Note that visually the spaces aren't equal, since all the items have equal space on both sides. The first item will have one unit of space against the container edge, but two units of space between the next item because that next item has its own spacing that applies. Not applies to ``track_cross_place``. -- :c:enumerator:`LV_FLEX_ALIGN_SPACE_BETWEEN`: items are evenly distributed in +- :cpp:enumerator:`LV_FLEX_ALIGN_SPACE_BETWEEN`: items are evenly distributed in the track: first item is on the start line, last item on the end line. Not applies to ``track_cross_place``. +.. _flex_grow: + Flex grow --------- Flex grow can be used to make one or more children fill the available space on the track. When more children have grow parameters, the available space will be distributed proportionally to the grow values. -For example, there is 400 px remaining space and 4 objects with grow: - -``A`` with grow = 1 - ``B`` with grow = 1 - ``C`` with grow = 2 +For example, there is 400 px remaining space and 4 objects with grow: + +- ``A`` with grow = 1 +- ``B`` with grow = 1 +- ``C`` with grow = 2 ``A`` and ``B`` will have 100 px size, and ``C`` will have 200 px size. Flex grow can be set on a child with -:c:expr:`lv_obj_set_flex_grow(child, value)`. ``value`` needs to be > +:cpp:expr:`lv_obj_set_flex_grow(child, value)`. ``value`` needs to be > 1 or 0 to disable grow on the child. +.. _flex_style: + Style interface *************** @@ -107,11 +120,13 @@ All the Flex-related values are style properties under the hood and you can use them similarly to any other style property. The following flex related style properties exist: -- :c:enumerator:`FLEX_FLOW` -- :c:enumerator:`FLEX_MAIN_PLACE` -- :c:enumerator:`FLEX_CROSS_PLACE` -- :c:enumerator:`FLEX_TRACK_PLACE` -- :c:enumerator:`FLEX_GROW` +- :cpp:enumerator:`FLEX_FLOW` +- :cpp:enumerator:`FLEX_MAIN_PLACE` +- :cpp:enumerator:`FLEX_CROSS_PLACE` +- :cpp:enumerator:`FLEX_TRACK_PLACE` +- :cpp:enumerator:`FLEX_GROW` + +.. _flex_padding: Internal padding ---------------- @@ -124,7 +139,9 @@ following properties can be set on the flex container style: - ``pad_column`` Sets the padding between the columns. These can for example be used if you don't want any padding between your -objects: :c:expr:`lv_style_set_pad_column(&row_container_style,0)` +objects: :cpp:expr:`lv_style_set_pad_column(&row_container_style,0)` + +.. _flex_other: Other features ************** @@ -133,9 +150,9 @@ RTL --- If the base direction of the container is set the -:c:enumerator:`LV_BASE_DIR_RTL` the meaning of -:c:enumerator:`LV_FLEX_ALIGN_START` and -:c:enumerator:`LV_FLEX_ALIGN_END` is swapped on ``ROW`` layouts. I.e. +:cpp:enumerator:`LV_BASE_DIR_RTL` the meaning of +:cpp:enumerator:`LV_FLEX_ALIGN_START` and +:cpp:enumerator:`LV_FLEX_ALIGN_END` is swapped on ``ROW`` layouts. I.e. ``START`` will mean right. The items on ``ROW`` layouts, and tracks of ``COLUMN`` layouts will be @@ -145,12 +162,16 @@ New track --------- You can force Flex to put an item into a new line with -:c:expr:`lv_obj_add_flag(child, LV_OBJ_FLAG_FLEX_IN_NEW_TRACK)`. +:cpp:expr:`lv_obj_add_flag(child, LV_OBJ_FLAG_FLEX_IN_NEW_TRACK)`. + +.. _flex_example: Example ******* .. include:: ../examples/layouts/flex/index.rst +.. _flex_api: + API *** diff --git a/docs/layouts/grid.rst b/docs/layouts/grid.rst index e944b97b4..2715f9d0d 100644 --- a/docs/layouts/grid.rst +++ b/docs/layouts/grid.rst @@ -1,3 +1,5 @@ +.. _grid: + ==== Grid ==== @@ -13,7 +15,7 @@ track's size can be set in pixel, to the largest item (:c:macro:`LV_GRID_CONTENT`) or in "Free unit" (FR) to distribute the free space proportionally. -To make an object a grid container call :c:expr:`lv_obj_set_layout(obj, LV_LAYOUT_GRID)`. +To make an object a grid container call :cpp:expr:`lv_obj_set_layout(obj, LV_LAYOUT_GRID)`. Note that the grid layout feature of LVGL needs to be globally enabled with :c:macro:`LV_USE_GRID` in ``lv_conf.h``. @@ -32,6 +34,8 @@ Simple interface With the following functions you can easily set a Grid layout on any parent. +.. _grid_descriptors: + Grid descriptors ---------------- @@ -47,15 +51,17 @@ For example: static int32_t row_dsc[] = {100, 100, 100, LV_GRID_TEMPLATE_LAST}; /*3 100 px tall rows*/ To set the descriptors on a parent use -:c:expr:`lv_obj_set_grid_dsc_array(obj, col_dsc, row_dsc)`. +:cpp:expr:`lv_obj_set_grid_dsc_array(obj, col_dsc, row_dsc)`. Besides simple settings the size in pixel you can use two special values: - :c:macro:`LV_GRID_CONTENT` set the size to fit the largest child on this track -- :c:expr:`LV_GRID_FR(X)` tell what portion of the remaining space +- :cpp:expr:`LV_GRID_FR(X)` tell what portion of the remaining space should be used by this track. Larger value means larger space. +.. _grid_items: + Grid items ---------- @@ -63,42 +69,45 @@ By default, the children are not added to the grid. They need to be added manually to a cell. To do this call -:c:expr:`lv_obj_set_grid_cell(child, column_align, column_pos, column_span, row_align, row_pos, row_span)`. +:cpp:expr:`lv_obj_set_grid_cell(child, column_align, column_pos, column_span, row_align, row_pos, row_span)`. ``column_align`` and ``row_align`` determine how to align the children in its cell. The possible values are: -- :c:enumerator:`LV_GRID_ALIGN_START`: means left on a horizontally and top vertically. (default) -- :c:enumerator:`LV_GRID_ALIGN_END`: means right on a horizontally and bottom vertically -- :c:enumerator:`LV_GRID_ALIGN_CENTER`: simply center ``column_pos`` and ``row_pos`` +- :cpp:enumerator:`LV_GRID_ALIGN_START`: means left on a horizontally and top vertically. (default) +- :cpp:enumerator:`LV_GRID_ALIGN_END`: means right on a horizontally and bottom vertically +- :cpp:enumerator:`LV_GRID_ALIGN_CENTER`: simply center ``column_pos`` and ``row_pos`` means the zero based index of the cell into the item should be placed. ``column_span`` and ``row_span`` means how many tracks should the item involve from the start cell. Must be >= 1. +.. _grid_align: + Grid align ---------- If there are some empty space the track can be aligned several ways: -- :c:enumerator:`LV_GRID_ALIGN_START`: means left on a horizontally and top vertically. (default) -- :c:enumerator:`LV_GRID_ALIGN_END`: means right on a horizontally and bottom vertically -- :c:enumerator:`LV_GRID_ALIGN_CENTER`: simply center -- :c:enumerator:`LV_GRID_ALIGN_SPACE_EVENLY`: items are distributed so that the spacing +- :cpp:enumerator:`LV_GRID_ALIGN_START`: means left on a horizontally and top vertically. (default) +- :cpp:enumerator:`LV_GRID_ALIGN_END`: means right on a horizontally and bottom vertically +- :cpp:enumerator:`LV_GRID_ALIGN_CENTER`: simply center +- :cpp:enumerator:`LV_GRID_ALIGN_SPACE_EVENLY`: items are distributed so that the spacing between any two items (and the space to the edges) is equal. Not applies to ``track_cross_place``. -- :c:enumerator:`LV_GRID_ALIGN_SPACE_AROUND`: items are +- :cpp:enumerator:`LV_GRID_ALIGN_SPACE_AROUND`: items are evenly distributed in the track with equal space around them. Note that visually the spaces aren't equal, since all the items have equal space on both sides. The first item will have one unit of space against the container edge, but two units of space between the next item because that next item has its own spacing that applies. Not applies to ``track_cross_place``. -- :c:enumerator:`LV_GRID_ALIGN_SPACE_BETWEEN`: items are +- :cpp:enumerator:`LV_GRID_ALIGN_SPACE_BETWEEN`: items are evenly distributed in the track: first item is on the start line, last item on the end line. Not applies to ``track_cross_place``. To set the track's alignment use -:c:expr:`lv_obj_set_grid_align(obj, column_align, row_align)`. +:cpp:expr:`lv_obj_set_grid_align(obj, column_align, row_align)`. +.. _grid_subgrid: Sub grid -------- @@ -116,6 +125,7 @@ Limitations: The sub grid feature works the same as in CSS. For further reference see `this description `__. +.. _grid_style: Style interface *************** @@ -124,16 +134,18 @@ All the Grid related values are style properties under the hood and you can use them similarly to any other style properties. The following Grid related style properties exist: -- :c:enumerator:`GRID_COLUMN_DSC_ARRAY` -- :c:enumerator:`GRID_ROW_DSC_ARRAY` -- :c:enumerator:`GRID_COLUMN_ALIGN` -- :c:enumerator:`GRID_ROW_ALIGN` -- :c:enumerator:`GRID_CELL_X_ALIGN` -- :c:enumerator:`GRID_CELL_COLUMN_POS` -- :c:enumerator:`GRID_CELL_COLUMN_SPAN` -- :c:enumerator:`GRID_CELL_Y_ALIGN` -- :c:enumerator:`GRID_CELL_ROW_POS` -- :c:enumerator:`GRID_CELL_ROW_SPAN` +- :cpp:enumerator:`GRID_COLUMN_DSC_ARRAY` +- :cpp:enumerator:`GRID_ROW_DSC_ARRAY` +- :cpp:enumerator:`GRID_COLUMN_ALIGN` +- :cpp:enumerator:`GRID_ROW_ALIGN` +- :cpp:enumerator:`GRID_CELL_X_ALIGN` +- :cpp:enumerator:`GRID_CELL_COLUMN_POS` +- :cpp:enumerator:`GRID_CELL_COLUMN_SPAN` +- :cpp:enumerator:`GRID_CELL_Y_ALIGN` +- :cpp:enumerator:`GRID_CELL_ROW_POS` +- :cpp:enumerator:`GRID_CELL_ROW_SPAN` + +.. _grid_padding: Internal padding ---------------- @@ -144,22 +156,28 @@ properties can be set on the Grid container style: - ``pad_row`` Sets the padding between the rows. - ``pad_column`` Sets the padding between the columns. +.. _grid_other: + Other features ************** RTL --- -If the base direction of the container is set to :c:enumerator:`LV_BASE_DIR_RTL`, -the meaning of :c:enumerator:`LV_GRID_ALIGN_START` and :c:enumerator:`LV_GRID_ALIGN_END` is +If the base direction of the container is set to :cpp:enumerator:`LV_BASE_DIR_RTL`, +the meaning of :cpp:enumerator:`LV_GRID_ALIGN_START` and :cpp:enumerator:`LV_GRID_ALIGN_END` is swapped. I.e. ``START`` will mean right-most. The columns will be placed from right to left. +.. _grid_examples: + Example ******* .. include:: ../examples/layouts/grid/index.rst +.. _grid_api: + API *** diff --git a/docs/layouts/index.rst b/docs/layouts/index.rst index 4ab3bb995..e790468d8 100644 --- a/docs/layouts/index.rst +++ b/docs/layouts/index.rst @@ -1,3 +1,5 @@ +.. _layouts: + ======= Layouts ======= diff --git a/docs/libs/barcode.rst b/docs/libs/barcode.rst index 2ffd6c73f..72569faf3 100644 --- a/docs/libs/barcode.rst +++ b/docs/libs/barcode.rst @@ -1,3 +1,5 @@ +.. _barcode: + ======= Barcode ======= @@ -6,17 +8,20 @@ Barcode generation with LVGL. Uses `code128 `__ by `fhunleth `__. +.. _barcode_usage: + Usage ----- Enable :c:macro:`LV_USE_BARCODE` in ``lv_conf.h``. -Use :c:expr:`lv_barcode_create()` to create a barcode object, and use -:c:expr:`lv_barcode_update()` to generate a barcode. +Use :cpp:func:`lv_barcode_create` to create a barcode object, and use +:cpp:func:`lv_barcode_update` to generate a barcode. -Call :c:expr:`lv_barcode_set_scale()` or :c:expr:`lv_barcode_set_dark/light_color()` -to adjust scaling and color, call :c:expr:`lv_barcode_set_direction()` will set -direction to display, and call :c:expr:`lv_barcode_update()` again to regenerate +Call :cpp:func:`lv_barcode_set_scale` to adjust scaling, +call :cpp:func:`lv_barcode_set_dark_color` and :cpp:func:`lv_barcode_set_light_color` +adjust color, call :cpp:func:`lv_barcode_set_direction` will set +direction to display, and call :cpp:func:`lv_barcode_update` again to regenerate the barcode. Notes @@ -26,14 +31,18 @@ Notes the width of the object is lower than the width of the barcode, the display will be incomplete due to truncation. - The scale adjustment can only be an integer multiple, for example, - :c:expr:`lv_barcode_set_scale(barcode, 2)` means 2x scaling. -- The direction adjustment can be `LV_DIR_HOR` or `LV_DIR_VER` + :cpp:expr:`lv_barcode_set_scale(barcode, 2)` means 2x scaling. +- The direction adjustment can be :cpp:enumerator:`LV_DIR_HOR` or :cpp:enumerator:`LV_DIR_VER` + +.. _barcode_example: Example ------- .. include:: ../examples/libs/barcode/index.rst +.. _barcode_api: + API --- diff --git a/docs/libs/bmp.rst b/docs/libs/bmp.rst index f6114a342..be3a189de 100644 --- a/docs/libs/bmp.rst +++ b/docs/libs/bmp.rst @@ -1,3 +1,5 @@ +.. _bmp: + =========== BMP decoder =========== @@ -16,9 +18,11 @@ sources. For example: lv_image_set_src(my_img, "S:path/to/picture.bmp"); Note that, a file system driver needs to registered to open images from -files. Read more about it :ref:`file-system` or just +files. Read more about it :ref:`overview_file_system` or just enable one in ``lv_conf.h`` with ``LV_USE_FS_...`` +.. _bmp_limitations: + Limitations ----------- @@ -34,11 +38,15 @@ Limitations - Palette is not supported. - Because not the whole image is read in can not be zoomed or rotated. +.. _bmp_example: + Example ------- .. include:: ../examples/libs/bmp/index.rst +.. _bmp_api: + API --- diff --git a/docs/libs/ffmpeg.rst b/docs/libs/ffmpeg.rst index 9aff4993f..0853dc576 100644 --- a/docs/libs/ffmpeg.rst +++ b/docs/libs/ffmpeg.rst @@ -1,9 +1,12 @@ +.. _ffmpeg: + ============== FFmpeg support ============== -`FFmpeg `__ A complete, cross-platform solution -to record, convert and stream audio and video. +A complete, cross-platform solution to record, convert and stream audio and video. + +Detailed introduction: `FFmpeg `__ Install FFmpeg -------------- @@ -18,6 +21,8 @@ Add FFmpeg to your project - Add library: ``FFmpeg`` (for GCC: ``-lavformat -lavcodec -lavutil -lswscale -lm -lz -lpthread``) +.. _ffmpeg_usage: + Usage ----- @@ -29,11 +34,15 @@ Note that, the FFmpeg extension doesn't use LVGL's file system. You can simply pass the path to the image or video as usual on your operating system or platform. +.. _ffmpeg_example: + Example ------- .. include:: ../examples/libs/ffmpeg/index.rst +.. _ffmpeg_api: + API --- diff --git a/docs/libs/freetype.rst b/docs/libs/freetype.rst index b81c98760..b32e4c29b 100644 --- a/docs/libs/freetype.rst +++ b/docs/libs/freetype.rst @@ -1,3 +1,5 @@ +.. _freetype: + ================ FreeType support ================ @@ -16,6 +18,7 @@ For UNIX ~~~~~~~~ For UNIX systems, it is recommended to use the way of compiling and installing libraries. + - Enter the FreeType source code directory. - ``make`` - ``sudo make install`` @@ -56,6 +59,8 @@ FLASH space. FT_CSRCS += freetype/src/truetype/truetype.c CSRCS += $(FT_CSRCS) +.. _freetype_usage: + Usage ----- @@ -79,17 +84,19 @@ interface, you can enable :c:macro:`LV_FREETYPE_USE_LVGL_PORT` in The font style supports *Italic* and **Bold** fonts processed by software, and can be set with reference to the following values: -- :c:enumerator:`LV_FREETYPE_FONT_STYLE_NORMAL`: Default style. -- :c:enumerator:`LV_FREETYPE_FONT_STYLE_ITALIC`: Italic style. -- :c:enumerator:`LV_FREETYPE_FONT_STYLE_BOLD`: Bold style. +- :cpp:enumerator:`LV_FREETYPE_FONT_STYLE_NORMAL`: Default style. +- :cpp:enumerator:`LV_FREETYPE_FONT_STYLE_ITALIC`: Italic style. +- :cpp:enumerator:`LV_FREETYPE_FONT_STYLE_BOLD`: Bold style. They can be combined.eg: -:c:expr:`LV_FREETYPE_FONT_STYLE_BOLD | LV_FREETYPE_FONT_STYLE_ITALIC`. +:cpp:expr:`LV_FREETYPE_FONT_STYLE_BOLD | LV_FREETYPE_FONT_STYLE_ITALIC`. -Use the :c:expr:`lv_freetype_font_create()` function to create a font. To -delete a font, use :c:expr:`lv_freetype_font_delete()`. For more detailed usage, +Use the :cpp:func:`lv_freetype_font_create` function to create a font. To +delete a font, use :cpp:func:`lv_freetype_font_delete`. For more detailed usage, please refer to example code. +.. _freetype_example: + Example ------- @@ -101,6 +108,8 @@ Learn more - FreeType`tutorial `__ - LVGL's :ref:`add_font` +.. _freetype_api: + API --- diff --git a/docs/libs/fs.rst b/docs/libs/fs.rst index 0435da83f..06e3d94c5 100644 --- a/docs/libs/fs.rst +++ b/docs/libs/fs.rst @@ -1,8 +1,10 @@ +.. _libs_filesystem: + ====================== File System Interfaces ====================== -LVGL has a :ref:`file-system` module +LVGL has a :ref:`overview_file_system` module to provide an abstraction layer for various file system drivers. LVG has built in support for: @@ -16,6 +18,8 @@ LVG has built in support for: You still need to provide the drivers and libraries, this extension provides only the bridge between FATFS, STDIO, POSIX, WIN32 and LVGL. +.. _libs_filesystem_usage: + Usage ***** @@ -28,11 +32,11 @@ The work directory can be set with ``LV_FS_..._PATH``. E.g. appended to it. Cached reading is also supported if ``LV_FS_..._CACHE_SIZE`` is set to -not ``0`` value. :c:func:`lv_fs_read` caches this size of data to lower the +not ``0`` value. :cpp:func:`lv_fs_read` caches this size of data to lower the number of actual reads from the storage. To use the memory-mapped file emulation an ``lv_fs_path_ex_t`` object must be -created and initialized. This object can be passed to :c:func:`lv_fs_open()` as +created and initialized. This object can be passed to :cpp:func:`lv_fs_open` as the file name: .. code:: c @@ -48,6 +52,8 @@ the file name: lv_fs_make_path_from_buffer(&mempath, LV_FS_MEMFS_LETTER, (void*)buffer, size); lv_fs_res_t res = lv_fs_open(&file, (const char *)&mempath, LV_FS_MODE_RD); +.. _libs_filesystem_api: + API *** diff --git a/docs/libs/gif.rst b/docs/libs/gif.rst index 064b2f755..8e5dda51f 100644 --- a/docs/libs/gif.rst +++ b/docs/libs/gif.rst @@ -1,14 +1,17 @@ +.. _gif: + =========== GIF decoder =========== -Allow using GIF images in LVGL. Based on -https://github.com/lecram/gifdec +Allow using GIF images in LVGL. + +Detailed introduction: `GIFdec `__ When enabled in ``lv_conf.h`` with :c:macro:`LV_USE_GIF` -:c:expr:`lv_gif_create(parent)` can be used to create a gif widget. +:cpp:expr:`lv_gif_create(parent)` can be used to create a gif widget. -:c:expr:`lv_gif_set_src(obj, src)` works very similarly to :c:func:`lv_image_set_src`. +:cpp:expr:`lv_gif_set_src(obj, src)` works very similarly to :cpp:func:`lv_image_set_src`. As source, it also accepts images as variables (:c:struct:`lv_image_dsc_t`) or files. @@ -29,7 +32,7 @@ For example: lv_gif_set_src(obj, "S:path/to/example.gif"); Note that, a file system driver needs to be registered to open images -from files. Read more about it :ref:`file-system` or just +from files. Read more about it :ref:`overview_file_system` or just enable one in ``lv_conf.h`` with ``LV_USE_FS_...`` Memory requirements @@ -42,11 +45,15 @@ required: - :c:macro:`LV_COLOR_DEPTH` ``16``: 4 x image width x image height - :c:macro:`LV_COLOR_DEPTH` ``32``: 5 x image width x image height +.. _gif_example: + Example ------- .. include:: ../examples/libs/gif/index.rst +.. _gif_api: + API --- diff --git a/docs/libs/index.rst b/docs/libs/index.rst index 6f1db56fe..8e983dcb2 100644 --- a/docs/libs/index.rst +++ b/docs/libs/index.rst @@ -1,3 +1,5 @@ +.. _3rd_party_libraries: + =================== 3rd party libraries =================== diff --git a/docs/libs/libjpeg_turbo.rst b/docs/libs/libjpeg_turbo.rst index 56af25e64..ca227c756 100644 --- a/docs/libs/libjpeg_turbo.rst +++ b/docs/libs/libjpeg_turbo.rst @@ -1,10 +1,15 @@ +.. _libjpeg: + ===================== -libjpge-turbo decoder +libjpeg-turbo decoder ===================== -libjpeg-turbo is a JPEG image codec that uses SIMD instructions to accelerate baseline JPEG compression and decompression on x86, +`libjpeg-turbo `__ is a JPEG image codec that uses SIMD instructions to accelerate baseline JPEG compression and decompression on x86, x86-64, Arm, PowerPC, and MIPS systems, as well as progressive JPEG compression on x86, x86-64, and Arm systems. -Detailed introduction: `libjpeg-turbo `__. + +Detailed introduction: `libjpeg-turbo `__ + +.. _libjpeg_install: Install ------- @@ -22,6 +27,8 @@ Add libjpge-turbo to your project include_directories(${JPEG_INCLUDE_DIR}) target_link_libraries(${PROJECT_NAME} PRIVATE ${JPEG_LIBRARIES}) +.. _libjpeg_usage: + Usage ----- @@ -29,13 +36,17 @@ Enable :c:macro:`LV_USE_LIBJEPG_TURBO` in ``lv_conf.h``. See the examples below. It should be noted that each image of this decoder needs to consume ``image width x image height x 3`` bytes of RAM, -and it needs to be combined with the ref:`image-caching` feature to ensure that the memory usage is within a reasonable range. +and it needs to be combined with the ref:`overview_image_caching` feature to ensure that the memory usage is within a reasonable range. + +.. _libjpeg_example: Example ------- .. include:: ../examples/libs/libjpeg_turbo/index.rst +.. _libjpeg_api: + API --- diff --git a/docs/libs/libpng.rst b/docs/libs/libpng.rst index b8bb0d0ec..7f59be499 100644 --- a/docs/libs/libpng.rst +++ b/docs/libs/libpng.rst @@ -1,9 +1,12 @@ +.. _libpng: + ============== libpng decoder ============== libpng is the official PNG reference library. It supports almost all PNG features, is extensible, and has been extensively tested for over 28 years. -Detailed introduction: `libpng `__. + +Detailed introduction: `libpng `__ Install ------- @@ -21,20 +24,27 @@ Add libpng to your project include_directories(${PNG_INCLUDE_DIR}) target_link_libraries(${PROJECT_NAME} PRIVATE ${PNG_LIBRARIES}) +.. _libpng_usage: + Usage ----- Enable :c:macro:`LV_USE_LIBPNG` in ``lv_conf.h``. See the examples below. -It should be noted that each image of this decoder needs to consume ``image width x image height x 4`` bytes of RAM, -and it needs to be combined with the ref:`image-caching` feature to ensure that the memory usage is within a reasonable range. +It should be noted that each image of this decoder needs to consume ``width x height x 4`` bytes of RAM, +and it needs to be combined with the :ref:`overview_image_caching` feature to ensure that the memory usage is within a reasonable range. +The decoded image is stored in RGBA pixel format. + +.. _libpng_example: Example ------- .. include:: ../examples/libs/libpng/index.rst +.. _libpng_api: + API --- diff --git a/docs/libs/lodepng.rst b/docs/libs/lodepng.rst index f79df3285..fdeadc293 100644 --- a/docs/libs/lodepng.rst +++ b/docs/libs/lodepng.rst @@ -1,28 +1,51 @@ +.. _lodepng: + =============== -LODEPNG decoder +LodePNG decoder =============== -Allow the use of PNG images in LVGL. This implementation uses -`lodepng `__ library. +Allow the use of PNG images in LVGL. + +Detailed introduction: `lodepng `__ If enabled in ``lv_conf.h`` by :c:macro:`LV_USE_LODEPNG` LVGL will register a new image decoder automatically so PNG files can be directly used as any other image sources. -Note that, a file system driver needs to registered to open images from -files. Read more about it :ref:`file-system` or just +Note that, a file system driver needs to be registered to open images from +files. Read more about it :ref:`overview_file_system` or just enable one in ``lv_conf.h`` with ``LV_USE_FS_...`` -The whole PNG image is decoded so during decoding RAM equals to -``image width x image height x 4`` bytes are required. +The whole PNG image is decoded, so ``width x height x 4`` bytes free RAM space is required. +The decoded image is stored in RGBA pixel format. -As it might take significant time to decode PNG images LVGL's :ref:`image-caching` feature can be useful. +As it might take significant time to decode PNG images LVGL's :ref:`overview_image_caching` feature can be useful. + +Compress PNG files +------------------ + +PNG file format supports True color (24/32 bit), and 8-bit palette colors. +Usually cliparts, drawings, icons and simple graphics are stored in PNG format, +that do not use the whole color space, so it is possible to compress further +the image by using 8-bit palette colors, instead of 24/32 bit True color format. +Because embedded devices have limited (flash) storage, it is recommended +to compress images. + +There is a very good and free online PNG compressor site, in which the number +of colors can be reduced, and in the same time preview the result. +A batch of PNG files can be uploaded also. + +Compress PNG site: https://compresspng.com/ + +.. _lodepng_example: Example ------- .. include:: ../examples/libs/lodepng/index.rst +.. _lodepng_api: + API --- diff --git a/docs/libs/qrcode.rst b/docs/libs/qrcode.rst index add866340..55c1bde45 100644 --- a/docs/libs/qrcode.rst +++ b/docs/libs/qrcode.rst @@ -1,3 +1,5 @@ +.. _qrcode: + ======= QR code ======= @@ -6,17 +8,20 @@ QR code generation with LVGL. Uses `QR-Code-generator `__ by `nayuki `__. +.. _qrcode_usage: + Usage ----- Enable :c:macro:`LV_USE_QRCODE` in ``lv_conf.h``. -Use :c:expr:`lv_qrcode_create()` to create a qrcode object, and use -:c:expr:`lv_qrcode_update()` to generate a QR code. +Use :cpp:func:`lv_qrcode_create` to create a qrcode object, and use +:cpp:func:`lv_qrcode_update` to generate a QR code. If you need to re-modify the size and color, use -:c:expr:`lv_qrcode_set_size()` and :c:expr:`lv_qrcode_set_dark/light_color()`, and -call :c:expr:`lv_qrcode_update()` again to regenerate the QR code. +:cpp:func:`lv_qrcode_set_size` and :cpp:func:`lv_qrcode_set_dark_color` or +:cpp:func:`lv_qrcode_set_light_color`, and +call :cpp:func:`lv_qrcode_update` again to regenerate the QR code. Notes ----- @@ -24,11 +29,15 @@ Notes - QR codes with less data are smaller, but they scaled by an integer number to best fit to the given size. +.. _qrcode_example: + Example ------- .. include:: ../examples/libs/qrcode/index.rst +.. _qrcode_api: + API --- diff --git a/docs/libs/rle.rst b/docs/libs/rle.rst index 9de9dbb40..7b64ff9a0 100644 --- a/docs/libs/rle.rst +++ b/docs/libs/rle.rst @@ -1,5 +1,8 @@ +.. _rle: + +============ RLE Compress -=========== +============ LVGL provides a custom RLE compression method. It can be used to reduce binary image size. The RLE compression is a lossless compression method. @@ -29,7 +32,7 @@ the for many pixels, the color is the same. The algorithm simply counts how many repeated data are there and store the count value and the color value. If the coming pixels are not repeated, it stores the non-repeat count value and original color value. For more details, the script used to compress the image -can be found from `lvgl/script/LVGLImage.py`. +can be found from ``lvgl/script/LVGLImage.py``. .. code:: python @@ -60,11 +63,12 @@ can be found from `lvgl/script/LVGLImage.py`. return b"".join(compressed_data) +.. _rle_usage: Usage ----- -To use the RLE Decoder, ensure that `LV_USE_RLE` is defined and set to `1`. +To use the RLE Decoder, enable it in ``lv_conf.h`` configuration file by setting :c:macro:`LV_USE_RLE` to `1`. The RLE image can be used same as other images. .. code:: c diff --git a/docs/libs/rlottie.rst b/docs/libs/rlottie.rst index 23cdfbcf1..c6a32dbb1 100644 --- a/docs/libs/rlottie.rst +++ b/docs/libs/rlottie.rst @@ -1,8 +1,10 @@ +.. _rlottie: + ============= Lottie player ============= -Allows to use Lottie animations in LVGL. Taken from this `base repository `__ +Allows playing Lottie animations in LVGL. Taken from `lv_rlottie `__. LVGL provides the interface to `Samsung/rlottie `__ library's C API. That is the actual Lottie player is not part of LVGL, it needs to @@ -37,6 +39,8 @@ given build system. ESP-IDF example at bottom ~~~~~~~~~~~~~~~~~~~~~~~~~ +.. _rlottie_usage: + Usage ----- @@ -62,9 +66,11 @@ Use Rlottie from raw string data ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ``lv_example_rlottie_approve.c`` contains an example animation in raw -format. Instead storing the JSON string a hex array is stored for the -following reasons: - avoid escaping ``"`` in the JSON file - some -compilers don't support very long strings +format. Instead storing the JSON string, a hex array is stored for the +following reasons: + +- avoid escaping ``"`` in the JSON file +- some compilers don't support very long strings ``lvgl/scripts/filetohex.py`` can be used to convert a Lottie file a hex array. E.g.: @@ -93,7 +99,7 @@ Controlling animations ---------------------- LVGL provides two functions to control the animation mode: -:c:func:`lv_rlottie_set_play_mode` and :c:func:`lv_rlottie_set_current_frame`. +:cpp:func:`lv_rlottie_set_play_mode` and :cpp:func:`lv_rlottie_set_current_frame`. You'll combine your intentions when calling the first method, like in these examples: @@ -113,7 +119,7 @@ these examples: The default animation mode is **play forward with loop**. -If you don't enable looping, a :c:enumerator:`LV_EVENT_READY` is sent when the +If you don't enable looping, a :cpp:enumerator:`LV_EVENT_READY` is sent when the animation can not make more progress without looping. To get the number of frames in an animation or the current frame index, @@ -129,9 +135,11 @@ Background Rlottie can be expensive to render on embedded hardware. Lottie animations tend to use a large amount of CPU time and can use large portions of RAM. This will vary from lottie to lottie but in general for -best performance: \* Limit total # of frames in the animation \* Where -possible, try to avoid bezier type animations \* Limit animation render -size +best performance: + +- Limit total # of frames in the animation +- Where possible, try to avoid bezier type animations +- Limit animation render size If your ESP32 chip does not have SPIRAM you will face severe limitations in render size. @@ -163,13 +171,14 @@ wonderful utility to LVGL on embedded LCDs and can look really good when done properly. When picking/designing a lottie animation consider the following -limitations: - Build the lottie animation to be sized for the intended -size - it can scale/resize, but performance will be best when the base -lottie size is as intended - Limit total number of frames, the longer -the lottie animation is, the more memory it will consume for rendering -(rlottie consumes IRAM for rendering) - Build the lottie animation for -the intended frame rate - default lottie is 60fps, embedded LCDs likely -won't go above 30fps +limitations: + +- Build the lottie animation to be sized for the intended size +- it can scale/resize, but performance will be best when the base lottie size is as intended +- Limit total number of frames, the longer the lottie animation is, +the more memory it will consume for rendering (rlottie consumes IRAM for rendering) +- Build the lottie animation for the intended frame rate +- default lottie is 60fps, embedded LCDs likely won't go above 30fps IDF Setup ~~~~~~~~~ @@ -243,13 +252,13 @@ The Esp-box devkit meets this spec and https://github.com/espressif/esp-box is a great starting point to adding lottie animations. -you'll need to enable:c:macro:`LV_USE_RLOTTIE` through idf.py menuconfig under +You will need to enable :c:macro:`LV_USE_RLOTTIE` through **idf.py** menuconfig under LVGL component settings. Additional changes to make use of SPIRAM ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -lv_alloc/realloc do not make use of SPIRAM. Given the high memory usage +:cpp:expr:`lv_alloc/realloc` do not make use of SPIRAM. Given the high memory usage of lottie animations, it is recommended to shift as much out of internal DRAM into SPIRAM as possible. In order to do so, SPIRAM will need to be enabled in the menuconfig options for your given espressif chip. @@ -257,19 +266,22 @@ enabled in the menuconfig options for your given espressif chip. There may be a better solution for this, but for the moment the recommendation is to make local modifications to the lvgl component in your espressif project. This is as simple as swapping -lv_alloc/lv_realloc calls in lv_rlottie.c with heap_caps_malloc (for -IDF) with the appropriate :c:expr:`MALLOC_CAP` call - for SPIRAM usage this is -:c:expr:`MALLOC_CAP_SPIRAM`. +:cpp:expr:`lv_alloc/lv_realloc` calls in `lv_rlottie.c`` with :cpp:expr:`heap_caps_malloc` (for +IDF) with the appropriate :cpp:expr:`MALLOC_CAP` call - for SPIRAM usage this is +:cpp:expr:`MALLOC_CAP_SPIRAM`. .. code:: c rlottie->allocated_buf = heap_caps_malloc(allocated_buf_size+1, MALLOC_CAP_SPIRAM); +.. _rlottie_example: + Example ------- .. include:: ../examples/libs/rlottie/index.rst +.. _rlottie_api: API --- diff --git a/docs/libs/tiny_ttf.rst b/docs/libs/tiny_ttf.rst index 573ca2bab..ba7d0201c 100644 --- a/docs/libs/tiny_ttf.rst +++ b/docs/libs/tiny_ttf.rst @@ -1,15 +1,20 @@ +.. _tiny_ttf: + ==================== Tiny TTF font engine ==================== +.. _tiny_ttf_usage: + Usage ----- -Allow using TrueType fonts LVGL. Based on -https://github.com/nothings/stb +Allow using TrueType fonts LVGL. + +Detailed introduction: `stb `__ When enabled in ``lv_conf.h`` with :c:macro:`LV_USE_TINY_TTF` -:c:expr:`lv_tiny_ttf_create_data(data, data_size, font_size)` can be used to +:cpp:expr:`lv_tiny_ttf_create_data(data, data_size, font_size)` can be used to create a TTF font instance at the specified line height. You can then use that font anywhere :c:struct:`lv_font_t` is accepted. @@ -17,24 +22,28 @@ By default, the TTF or OTF file must be embedded as an array, either in a header, or loaded into RAM in order to function. However, if :c:macro:`LV_TINY_TTF_FILE_SUPPORT` is enabled, -:c:expr:`lv_tiny_ttf_create_file(path, font_size)` will also be available, +:cpp:expr:`lv_tiny_ttf_create_file(path, font_size)` will also be available, allowing tiny_ttf to stream from a file. The file must remain open the entire time the font is being used. After a font is created, you can change the font size in pixels by using -:c:expr:`lv_tiny_ttf_set_size(font, font_size)`. +:cpp:expr:`lv_tiny_ttf_set_size(font, font_size)`. By default, a font will use up to 4KB of cache to speed up rendering glyphs. This maximum can be changed by using -:c:expr:`lv_tiny_ttf_create_data_ex(data, data_size, font_size, cache_size)` -or :c:expr:`lv_tiny_ttf_create_file_ex(path, font_size, cache_size)` (when +:cpp:expr:`lv_tiny_ttf_create_data_ex(data, data_size, font_size, cache_size)` +or :cpp:expr:`lv_tiny_ttf_create_file_ex(path, font_size, cache_size)` (when available). The cache size is indicated in bytes. +.. _tiny_ttf_example: + Example ------- .. include:: ../examples/libs/tiny_ttf/index.rst +.. _tiny_ttf_api: + API --- diff --git a/docs/libs/tjpgd.rst b/docs/libs/tjpgd.rst index b746c82e9..a5f3c0ade 100644 --- a/docs/libs/tjpgd.rst +++ b/docs/libs/tjpgd.rst @@ -1,17 +1,27 @@ -============= -TJPGD decoder -============= +.. _tjpgd: +================================ +Tiny JPEG Decompressor (TJpgDec) +================================ + +TJpgDec - Tiny JPEG Decompressor. Allow the use of JPG (JPEG) images in LVGL. +Detailed introduction: `TJpgDec `__ + +.. _tjpgd_overview: + Overview -------- - JPG is decoded in 8x8 tiles. +- Only baseline JPG files are supported (no progressive JPG support). - Read from file and C array are implemented. - Only the required portions of the JPG images are decoded, therefore they can't be zoomed or rotated. +.. _tjpgd_usage: + Usage ----- @@ -24,7 +34,7 @@ as image sources. For example: lv_image_set_src(my_img, "S:path/to/picture.jpg"); Note that a file system driver needs to be registered to open images from -files. Read more about it :ref:`file-system` or just +files. Read more about it :ref:`overview_file_system` or just enable one in ``lv_conf.h`` with ``LV_USE_FS_...`` Converter @@ -36,11 +46,14 @@ Converting JPG to C array - Use lvgl online tool https://lvgl.io/tools/imageconverter - Color format = RAW, output format = C Array +.. _tjpgd_example: + Example ------- .. include:: ../examples/libs/tjpgd/index.rst +.. _tjpgd_api: API --- diff --git a/docs/others/file_explorer.rst b/docs/others/file_explorer.rst index 33a392a36..fc353989c 100644 --- a/docs/others/file_explorer.rst +++ b/docs/others/file_explorer.rst @@ -1,3 +1,5 @@ +.. _file_explorer: + ============= File Explorer ============= @@ -11,86 +13,22 @@ currently clicked file. The file operation function needs to be implemented by the user. The file list in ``lv_file_explorer`` is based on -`lv_table `__, and the quick access bar is based on -`lv_list `__. Therefore, care should be taken to ensure -that `lv_table `__ and `lv_list `__ are +:ref:`lv_table`, and the quick access bar is based on +:ref:`lv_list`. Therefore, care should be taken to ensure +that :ref:`lv_table` and :ref:`lv_list` are enabled. -.. raw:: html - -
- -.. raw:: html - - - -中文 - -.. raw:: html - - - -.. raw:: html - -

- -``lv_file_explorer`` -提供API让我们可以浏览文件系统中的内容。\ ``lv_file_explorer`` -只提供了文件浏览功能，并不提供实际的文件操作功能，也就是说，不能像PC那样点击一个图片文件就可以打开查看该图片。\ ``lv_file_explorer`` -会告诉您当前点击的文件的完整路径和名称，文件操作功能需要用户自己实现。 - -``lv_file_explorer`` 中的文件列表基于 `lv_table `__ -实现，快速访问栏基于 `lv_list `__ -实现。因此，要注意确保使能了 ``lv_table`` 和 ``lv_list``\ 。 - -.. raw:: html - -

- -.. raw:: html - -
+.. _file_explorer_usage: Usage ----- Enable :c:macro:`LV_USE_FILE_EXPLORER` in ``lv_conf.h``. -First use :c:expr:`lv_file_explorer_create(lv_screen_active())` to create a file +First use :cpp:expr:`lv_file_explorer_create(lv_screen_active())` to create a file explorer, The default size is the screen size. After that, you can customize the style like widget. -.. raw:: html - -
- -.. raw:: html - - - -中文 - -.. raw:: html - - - -.. raw:: html - -

- -在 ``lv_conf.h`` 中打开 :c:macro:`LV_USE_FILE_EXPLORER`\ 。 - -首先，使用 :c:expr:`lv_file_explorer_create(lv_screen_active())` -函数创建一个文件浏览器，默认大小为屏幕大小，之后可以像组件那样自定义样式。 - -.. raw:: html - -

- -.. raw:: html - -
- Quick access ~~~~~~~~~~~~ @@ -102,121 +40,46 @@ button at the top left corner of the browsing area, which is very useful for small screen devices. You can use -:c:expr:`lv_file_explorer_set_quick_access_path(file_explorer, LV_FILE_EXPLORER_QA_XX, "path")` +:cpp:expr:`lv_file_explorer_set_quick_access_path(file_explorer, LV_FILE_EXPLORER_QA_XX, "path")` to set the path of the quick access bar. The items of the quick access bar are fixed. Currently, there are the following items: -- :c:enumerator:`LV_FILE_EXPLORER_QA_HOME` -- :c:enumerator:`LV_FILE_EXPLORER_QA_MUSIC` -- :c:enumerator:`LV_FILE_EXPLORER_QA_PICTURES` -- :c:enumerator:`LV_FILE_EXPLORER_QA_VIDEO` -- :c:enumerator:`LV_FILE_EXPLORER_QA_DOCS` -- :c:enumerator:`LV_FILE_EXPLORER_QA_MNT` -- :c:enumerator:`LV_FILE_EXPLORER_QA_FS` +- :cpp:enumerator:`LV_FILE_EXPLORER_QA_HOME` +- :cpp:enumerator:`LV_FILE_EXPLORER_QA_MUSIC` +- :cpp:enumerator:`LV_FILE_EXPLORER_QA_PICTURES` +- :cpp:enumerator:`LV_FILE_EXPLORER_QA_VIDEO` +- :cpp:enumerator:`LV_FILE_EXPLORER_QA_DOCS` +- :cpp:enumerator:`LV_FILE_EXPLORER_QA_MNT` +- :cpp:enumerator:`LV_FILE_EXPLORER_QA_FS` -.. raw:: html - -
- -.. raw:: html - - - -中文 - -.. raw:: html - - - -.. raw:: html - -

- -快速访问栏是可选的，您可以在 ``lv_conf.h`` 中关闭 -:c:macro:`LV_FILE_EXPLORER_QUICK_ACCESS`\ ，这样快速访问栏就不会被创建出来，这能节省一些内存，但并不是很多。快速访问栏被创建出来之后，可以通过点击浏览区域顶部左上角的按钮隐藏起来，这对于小屏幕设备非常有用。 - -可以通过 -:c:expr:`lv_file_explorer_set_quick_access_path(file_explorer, LV_FILE_EXPLORER_QA_XX, "path")` -设置快速访问栏的路径，快速访问栏的项目是固定的，目前有以下项目： - -- :c:enumerator:`LV_FILE_EXPLORER_QA_HOME` -- :c:enumerator:`LV_FILE_EXPLORER_QA_MUSIC` -- :c:enumerator:`LV_FILE_EXPLORER_QA_PICTURES` -- :c:enumerator:`LV_FILE_EXPLORER_QA_VIDEO` -- :c:enumerator:`LV_FILE_EXPLORER_QA_DOCS` -- :c:enumerator:`LV_FILE_EXPLORER_QA_MNT` -- :c:enumerator:`LV_FILE_EXPLORER_QA_FS` - -.. raw:: html - -

- -.. raw:: html - -
+.. _file_explorer_sort: Sort ~~~~ You can use -:c:expr:`lv_file_explorer_set_sort(file_explorer, LV_EXPLORER_SORT_XX)` to set +:cpp:expr:`lv_file_explorer_set_sort(file_explorer, LV_EXPLORER_SORT_XX)` to set sorting method. There are the following sorting methods: -- :c:enumerator:`LV_EXPLORER_SORT_NONE` -- :c:enumerator:`LV_EXPLORER_SORT_KIND` +- :cpp:enumerator:`LV_EXPLORER_SORT_NONE` +- :cpp:enumerator:`LV_EXPLORER_SORT_KIND` You can customize the sorting. Before custom sort, please set the -default sorting to :c:enumerator:`LV_EXPLORER_SORT_NONE`. The default is -:c:enumerator:`LV_EXPLORER_SORT_NONE`. +default sorting to :cpp:enumerator:`LV_EXPLORER_SORT_NONE`. The default is +:cpp:enumerator:`LV_EXPLORER_SORT_NONE`. -.. raw:: html +.. _file_explorer_events: -
+Events +------ -.. raw:: html - - - -中文 - -.. raw:: html - - - -.. raw:: html - -

- -可以通过 -:c:expr:`lv_file_explorer_set_sort(file_explorer, LV_EXPLORER_SORT_XX)` -设置排序方式，有以下排序方式： - -- :c:enumerator:`LV_EXPLORER_SORT_NONE` -- :c:enumerator:`LV_EXPLORER_SORT_KIND` - -您可以自定义排序规则，在这之前请先将排序规则设置为 -:c:enumerator:`LV_EXPLORER_SORT_NONE` 然后在 :c:enumerator:`LV_EVENT_READY` -事件中处理。默认的排序规则是 :c:enumerator:`LV_EXPLORER_SORT_NONE` - -.. raw:: html - -

- -.. raw:: html - -
- -Event ------ - -- :c:enumerator:`LV_EVENT_READY` sent when a directory is opened. You can customize +- :cpp:enumerator:`LV_EVENT_READY` sent when a directory is opened. You can customize the sort. - -- :c:enumerator:`LV_EVENT_VALUE_CHANGED` sent when an item(file) in the file list +- :cpp:enumerator:`LV_EVENT_VALUE_CHANGED` sent when an item(file) in the file list is clicked. -You can use :c:func:`lv_file_explorer_get_cur_path` to get the current path -and :c:func:`lv_file_explorer_get_sel_fn` to get the name of the currently +You can use :cpp:func:`lv_file_explorer_get_cur_path` to get the current path +and :cpp:func:`lv_file_explorer_get_sel_fn` to get the name of the currently selected file in the event processing function. For example: .. code:: c @@ -234,65 +97,17 @@ selected file in the event processing function. For example: } You can also save the obtained **path** and **file** name into an array -through functions such as *strcpy* and *strcat* for later use. +through functions such as :cpp:func:`strcpy` and :cpp:func:`strcat` for later use. -.. raw:: html - -
- -.. raw:: html - - - -中文 - -.. raw:: html - - - -.. raw:: html - -

- -- 当打开一个目录后会发送 :c:enumerator:`LV_EVENT_READY` - 事件。您可以在这里自定义排序规则。 -- 当文件列表中的项目（文件）被点击时会发送 :c:enumerator:`LV_EVENT_VALUE_CHANGED` - 事件。 - -可以在事件处理函数中通过 :c:func:`lv_file_explorer_get_cur_path` -获取当前所在的路径，通过 :c:func:`lv_file_explorer_get_sel_fn` -获取当前选中的文件的名称。比如： - -.. code:: c - - static void file_explorer_event_handler(lv_event_t * e) - { - lv_event_code_t code = lv_event_get_code(e); - lv_obj_t * obj = lv_event_get_target(e); - - if(code == LV_EVENT_VALUE_CHANGED) { - char * cur_path = lv_file_explorer_get_cur_path(obj); - char * sel_fn = lv_file_explorer_get_sel_fn(obj); - LV_LOG_USER("%s%s", cur_path, sel_fn); - } - } - -您还可以将获取到的 **路径** 和 **文件名称** 通过例如 strcpy 和 strcat -函数保存到一个数组中，方便后续使用。 - -.. raw:: html - -

- -.. raw:: html - -
+.. _file_explorer_example: Example ------- .. include:: ../examples/others/file_explorer/index.rst +.. _file_explorer_api: + API --- diff --git a/docs/others/fragment.rst b/docs/others/fragment.rst index ed4e0440f..f6feb6570 100644 --- a/docs/others/fragment.rst +++ b/docs/others/fragment.rst @@ -1,3 +1,5 @@ +.. _fragment: + ======== Fragment ======== @@ -20,6 +22,8 @@ to it, and has an internal stack to achieve navigation. You can use fragment manager to build navigation stack, or multi pane application easily. +.. _fragment_usage: + Usage ----- @@ -69,11 +73,15 @@ Fragment Based Navigation /* Remove the top most fragment from the stack, and bring back previous one. */ lv_fragment_manager_pop(manager); +.. _fragment_example: + Example ------- .. include:: ../examples/others/fragment/index.rst +.. _fragment_api: + API --- diff --git a/docs/others/gridnav.rst b/docs/others/gridnav.rst index 41a20c572..9d9a2b00f 100644 --- a/docs/others/gridnav.rst +++ b/docs/others/gridnav.rst @@ -1,3 +1,5 @@ +.. _gridnav: + =============== Grid navigation =============== @@ -24,43 +26,51 @@ gridnav is focused, the arrow key presses are automatically forwarded to the object so that gridnav can process the arrow keys. To move the focus to the next widget of the group use -:c:expr:`LV_KEY_NEXT/PREV` or :c:expr:`lv_group_focus_next/prev()` or the ``TAB`` +:cpp:enumerator:`LV_KEY_NEXT` or :cpp:enumerator:`LV_KEY_PREV`. +Optionally you can also use :cpp:func:`lv_group_focus_next` +or :cpp:func:`lv_group_focus_prev` or the ``TAB`` key on keyboard as usual. If the container is scrollable and the focused child is out of the view, gridnav will automatically scroll the child into view. +.. _gridnav_usage: + Usage ----- To add the gridnav feature to an object use -:c:expr:`lv_gridnav_add(cont, flags)`. +:cpp:expr:`lv_gridnav_add(cont, flags)`. ``flags`` control the behavior of gridnav: -- :c:enumerator:`LV_GRIDNAV_CTRL_NONE`: Default settings -- :c:enumerator:`LV_GRIDNAV_CTRL_ROLLOVER`: If there is no next/previous object in a +- :cpp:enumerator:`LV_GRIDNAV_CTRL_NONE`: Default settings +- :cpp:enumerator:`LV_GRIDNAV_CTRL_ROLLOVER`: If there is no next/previous object in a direction, the focus goes to the object in the next/previous row (on left/right keys) or first/last row (on up/down keys) -- :c:enumerator:`LV_GRIDNAV_CTRL_SCROLL_FIRST`: If an arrow is pressed and the focused +- :cpp:enumerator:`LV_GRIDNAV_CTRL_SCROLL_FIRST`: If an arrow is pressed and the focused object can be scrolled in that direction then it will be scrolled instead of going to the next/previous object. If there is no more room for scrolling the next/previous object will be focused normally -:c:expr:`lv_gridnav_remove(cont)` Removes gridnav from an object. +:cpp:expr:`lv_gridnav_remove(cont)` Removes gridnav from an object. Focusable objects ----------------- An object needs to be clickable or click focusable -(:c:enumerator:`LV_OBJ_FLAG_CLICKABLE` or :c:enumerator:`LV_OBJ_FLAG_CLICK_FOCUSABLE`) and not -hidden (:c:enumerator:`LV_OBJ_FLAG_HIDDEN`) to be focusable by gridnav. +(:cpp:enumerator:`LV_OBJ_FLAG_CLICKABLE` or :cpp:enumerator:`LV_OBJ_FLAG_CLICK_FOCUSABLE`) and not +hidden (:cpp:enumerator:`LV_OBJ_FLAG_HIDDEN`) to be focusable by gridnav. + +.. _gridnav_example: Example ------- .. include:: ../examples/others/gridnav/index.rst +.. _gridnav_api: + API --- diff --git a/docs/others/ime_pinyin.rst b/docs/others/ime_pinyin.rst index cd492d2a3..d28afa5b0 100644 --- a/docs/others/ime_pinyin.rst +++ b/docs/others/ime_pinyin.rst @@ -1,3 +1,5 @@ +.. _ime_pinyin: + ========== Pinyin IME ========== @@ -7,52 +9,22 @@ input) for keyboard object, which supports 26 key and 9 key input modes. You can think of ``lv_ime_pinyin`` as a Pinyin input method plug-in for keyboard objects. -Normally, an environment where `lv_keyboard `__ can +Normally, an environment where :ref:`lv_keyboard` can run can also run ``lv_ime_pinyin``. There are two main influencing factors: the size of the font file and the size of the dictionary. -.. raw:: html - -
- -.. raw:: html - - - -中文 - -.. raw:: html - - - -.. raw:: html - -

- -``lv_ime_pinyin``\ 为\ `键盘 `__\ 组件提供汉语拼音输入法（中文输入）的功能(后文简称为拼音输入法)，支持26键和9键输入模式。您可以将 -``lv_ime_pinyin`` 看成是键盘组件的汉语拼音输入法插件。 - -一般情况下，只要是\ `键盘 `__\ 组件能运行的环境 -``lv_ime_pinyin`` 也能运行。有两个影响因素：字库的大小和词库的大小。 - -.. raw:: html - -

- -.. raw:: html - -
+.. _ime_pinyin_example: Usage ----- Enable :c:macro:`LV_USE_IME_PINYIN` in ``lv_conf.h``. -First use :c:expr:`lv_ime_pinyin_create(lv_screen_active())` to create a Pinyin +First use :cpp:expr:`lv_ime_pinyin_create(lv_screen_active())` to create a Pinyin input method plug-in, then use -:c:expr:`lv_ime_pinyin_set_keyboard(pinyin_ime, kb)` to add the ``keyboard`` +:cpp:expr:`lv_ime_pinyin_set_keyboard(pinyin_ime, kb)` to add the ``keyboard`` you created to the Pinyin input method plug-in. You can use -:c:expr:`lv_ime_pinyin_set_dict(pinyin_ime, your_dict)` to use a custom +:cpp:expr:`lv_ime_pinyin_set_dict(pinyin_ime, your_dict)` to use a custom dictionary (if you don't want to use the built-in dictionary at first, you can disable :c:macro:`LV_IME_PINYIN_USE_DEFAULT_DICT` in ``lv_conf.h``, which can save a lot of memory space). @@ -65,48 +37,6 @@ custom fonts and thesaurus. In the process of using the Pinyin input method plug-in, you can change the keyboard and dictionary at any time. -.. raw:: html - -
- -.. raw:: html - - - -中文 - -.. raw:: html - - - -.. raw:: html - -

- -在 ``lv_conf.h`` 中打开 :c:macro:`LV_USE_IME_PINYIN`\ 。 - -首先，使用 :c:expr:`lv_ime_pinyin_create(lv_screen_active())` -函数创建一个拼音输入法插件， 然后使用 -:c:expr:`lv_ime_pinyin_set_keyboard(pinyin_ime, kb)` -函数将您创建的键盘组件添加到插件中。 - -内置的词库是基于 LVGL 的 **LV_FONT_SIMSUN_16_CJK** -字库定制，这个字库目前只有 ``1000`` 多个最常见的 CJK -部首，所以建议使用自定义字库和词库。 - -您可以使用 :c:expr:`lv_ime_pinyin_set_dict(pinyin_ime, your_dict)` -函数来设置使用自定义的词库，如果您一开始就不打算使用内置的词库，建议您在 -``lv_conf.h`` 中将 :c:macro:`LV_IME_PINYIN_USE_DEFAULT_DICT` -关闭，这可以节省一些内存空间。 - -.. raw:: html - -

- -.. raw:: html - -
- Custom dictionary ----------------- @@ -120,37 +50,6 @@ First, set :c:macro:`LV_IME_PINYIN_USE_DEFAULT_DICT` to ``0`` in ``lv_conf.h`` Then, write a dictionary in the following format. -.. raw:: html - -
- -.. raw:: html - - - -中文 - -.. raw:: html - - - -.. raw:: html - -

- -如果您不想使用内置的词库，可以通过下面的方法自定义词库。 - -自定义词典非常简单。 首先，在 ``lv_conf.h`` 将 -:c:macro:`LV_IME_PINYIN_USE_DEFAULT_DICT` 设置为 0。 -然后按照下面的格式编写词库。 - -.. raw:: html - -

- -.. raw:: html - -
Dictionary format ~~~~~~~~~~~~~~~~~ @@ -163,36 +62,6 @@ to learn about the Hanyu Pinyin syllables and the syllable table. Then, write your own dictionary according to the following format: -.. raw:: html - -
- -.. raw:: html - - - -中文 - -.. raw:: html - - - -.. raw:: html - -

- -**注意**\ ，各个拼音音节的排列顺序非常重要，您需要按照汉语拼音音节表定制自己的词库，可以阅读\ `这里 `__\ 了解\ `汉语拼音音节 `__\ 以及\ `音节表 `__\ 。 - -然后，根据下面的格式编写自己的词库： - -.. raw:: html - -

- -.. raw:: html - -
- .. code:: c lv_100ask_pinyin_dict_t your_pinyin_dict[] = { @@ -207,107 +76,47 @@ Then, write your own dictionary according to the following format: { "zuo", "昨左佐做作坐座撮琢柞"}, {NULL, NULL} -**The last item** must end with ``{null, null}`` , or it will not work +**The last item** must end with ``{null, null}``, or it will not work properly. +.. _ime_pinyin_apply_new_dictionary: + Apply new dictionary ~~~~~~~~~~~~~~~~~~~~ After writing a dictionary according to the above dictionary format, you only need to call this function to set up and use your dictionary: -.. raw:: html - -
- -.. raw:: html - - - -中文 - -.. raw:: html - - - -.. raw:: html - -

- -按照上面的词库格式编写好自己的词库之后，参考下面的用法，调用 -:c:expr:`lv_100ask_pinyin_ime_set_dict(pinyin_ime, your_pinyin_dict)` -函数即可设置和使用新词库： - -.. raw:: html - -

- -.. raw:: html - -
- .. code:: c lv_obj_t * pinyin_ime = lv_100ask_pinyin_ime_create(lv_screen_active()); lv_100ask_pinyin_ime_set_dict(pinyin_ime, your_pinyin_dict); +.. _ime_pinyin_modes: + Modes ----- The lv_ime_pinyin have the following modes: -- :c:enumerator:`LV_IME_PINYIN_MODE_K26`: Pinyin 26 key input mode -- :c:enumerator:`LV_IME_PINYIN_MODE_K9`: Pinyin 9 key input mode -- :c:enumerator:`LV_IME_PINYIN_MODE_K9_NUMBER`: Numeric keypad mode +- :cpp:enumerator:`LV_IME_PINYIN_MODE_K26`: Pinyin 26 key input mode +- :cpp:enumerator:`LV_IME_PINYIN_MODE_K9`: Pinyin 9 key input mode +- :cpp:enumerator:`LV_IME_PINYIN_MODE_K9_NUMBER`: Numeric keypad mode The ``TEXT`` modes' layout contains buttons to change mode. -To set the mode manually, use -:c:expr:`lv_ime_pinyin_set_mode(pinyin_ime, mode)` . The default mode is -:c:enumerator:`LV_IME_PINYIN_MODE_K26` . +To set the mode manually, use :cpp:expr:`lv_ime_pinyin_set_mode(pinyin_ime, mode)`. +The default mode is :cpp:enumerator:`LV_IME_PINYIN_MODE_K26`. -.. raw:: html - -
- -.. raw:: html - - - -中文 - -.. raw:: html - - - -.. raw:: html - -

- -lv_ime_pinyin 有以下模式： - -- :c:enumerator:`LV_IME_PINYIN_MODE_K26`: 拼音26键 -- :c:enumerator:`LV_IME_PINYIN_MODE_K9`: 拼音9键(九宫格) -- :c:enumerator:`LV_IME_PINYIN_MODE_K9_NUMBER`: 九宫格布局的数字键盘 - -每个模式的布局中都包含有更改到其他模式的按钮。 - -您可以通过 :c:expr:`lv_keyboard_set_mode(kb, mode)` -函数手动设置模式。默认的模式是 :c:enumerator:`LV_IME_PINYIN_MODE_K26` 。 - -.. raw:: html - -

- -.. raw:: html - -
+.. _ime_pinyin_example: Example ------- .. include:: ../examples/others/ime/index.rst +.. _ime_pinyin_api: + API --- diff --git a/docs/others/imgfont.rst b/docs/others/imgfont.rst index 44591257d..8b8c273a9 100644 --- a/docs/others/imgfont.rst +++ b/docs/others/imgfont.rst @@ -1,28 +1,41 @@ -==================== -Image font (imgfont) -==================== +.. _lv_imgfont: -Draw image in label or span obj with imgfont. This is often used to -display Unicode emoji icons in text. Supported image formats: determined -by LVGL image decoder. +======================= +Image font (lv_imgfont) +======================= + +Draw image in label or span obj with :cpp:type:`lv_imgfont`. This is often used to +display Unicode emoji icons in text. + +Supported image formats: determined by enabled LVGL image decoders. + +.. _lv_imgfont_usage: Usage ----- Enable :c:macro:`LV_USE_IMGFONT` in ``lv_conf.h``. -To create a new imgfont use :c:expr:`lv_imgfont_create(height, path_cb)`. +To create a new *imgfont* use :cpp:expr:`lv_imgfont_create(height, path_cb, user_data)`. -``height`` used to indicate the size of a imgfont. ``path_cb`` Used to -get the image path of the specified unicode. +- ``height`` Font size. +- ``path_cb`` A function to get the image path of a character. + Return ``NULL`` if no image should be shown, but the character itself. +- ``user_data`` Pointer to user data. -Use :c:expr:`lv_imgfont_destroy(imgfont)` to destroy a imgfont that is no -longer used. +To use the *imgfont* in a label, reference it: +:cpp:expr:`lv_obj_set_style_text_font(label, imgfont, LV_PART_MAIN)` + +To destroy the *imgfont* that is no longer used, use :cpp:expr:`lv_imgfont_destroy(imgfont)`. + +.. _lv_imgfont_example: Example ------- .. include:: ../examples/others/imgfont/index.rst +.. _lv_imgfont_api: + API --- diff --git a/docs/others/index.rst b/docs/others/index.rst index d185e68af..7383c5422 100644 --- a/docs/others/index.rst +++ b/docs/others/index.rst @@ -1,3 +1,5 @@ +.. _others: + ====== Others ====== diff --git a/docs/others/monkey.rst b/docs/others/monkey.rst index af79575c3..597969c6c 100644 --- a/docs/others/monkey.rst +++ b/docs/others/monkey.rst @@ -1,9 +1,13 @@ +.. _monkey: + ====== Monkey ====== A simple monkey test. Use random input to stress test the application. +.. _monkey_usage: + Usage ----- @@ -13,27 +17,31 @@ First configure monkey, use :c:struct:`lv_monkey_config_t` to define the configuration structure, set the ``type`` (check `input devices `__ for the supported types), and then set the range of ``period_range`` and ``input_range``, the monkey will output random operations at random times within this range. Call -:c:func:`lv_monkey_create` to create monkey. Finally call -:c:expr:`lv_monkey_set_enable(monkey, true)` to enable monkey. +:cpp:func:`lv_monkey_create` to create monkey. Finally call +:cpp:expr:`lv_monkey_set_enable(monkey, true)` to enable monkey. If you want to pause the monkey, call -:c:expr:`lv_monkey_set_enable(monkey, false)`. To delete the monkey, call -:c:expr:`lv_monkey_delete(monkey)`. +:cpp:expr:`lv_monkey_set_enable(monkey, false)`. To delete the monkey, call +:cpp:expr:`lv_monkey_delete(monkey)`. Note that ``input_range`` has different meanings in different ``type``: -- :c:enumerator:`LV_INDEV_TYPE_POINTER`: No effect, click randomly within the pixels of the screen resolution. -- :c:enumerator:`LV_INDEV_TYPE_ENCODER`: The minimum and maximum values of ``enc_diff``. -- :c:enumerator:`LV_INDEV_TYPE_BUTTON`: The minimum and maximum values of ``btn_id``. - Use :c:expr:`lv_monkey_get_indev()` to get the input device, and use - :c:expr:`lv_indev_set_button_points()` to map the key ID to the coordinates. -- :c:enumerator:`LV_INDEV_TYPE_KEYPAD`: No effect, Send random :ref:`indev_keys`. +- :cpp:enumerator:`LV_INDEV_TYPE_POINTER`: No effect, click randomly within the pixels of the screen resolution. +- :cpp:enumerator:`LV_INDEV_TYPE_ENCODER`: The minimum and maximum values of ``enc_diff``. +- :cpp:enumerator:`LV_INDEV_TYPE_BUTTON`: The minimum and maximum values of ``btn_id``. + Use :cpp:func:`lv_monkey_get_indev` to get the input device, and use + :cpp:func:`lv_indev_set_button_points` to map the key ID to the coordinates. +- :cpp:enumerator:`LV_INDEV_TYPE_KEYPAD`: No effect, Send random :ref:`indev_keys`. + +.. _monkey_example: Example ------- .. include:: ../examples/others/monkey/index.rst +.. _monkey_api: + API --- diff --git a/docs/others/obj_id.rst b/docs/others/obj_id.rst index c932eac33..ffceae263 100644 --- a/docs/others/obj_id.rst +++ b/docs/others/obj_id.rst @@ -1,28 +1,32 @@ +.. _obj_id: + ====== OBJ ID ====== -LVGL provides an optional field in `lv_obj_t` to store the object ID. +LVGL provides an optional field in :cpp:type:`lv_obj_t` to store the object ID. Object ID can be used in many cases, for example, to identify the object. Or we can store a program backtrace to where the object is created. +.. _obj_id_usage: + Usage ----- -Enable this feature by setting ``LV_USE_OBJ_ID`` to 1 in `lv_conf.h`. -Use the builtin obj ID generator by setting ``LV_USE_OBJ_ID_BUILTIN`` to 1. +Enable this feature by setting :c:macro:`LV_USE_OBJ_ID` to `1` in ``lv_conf.h``. +Use the builtin obj ID generator by setting :c:macro:`LV_USE_OBJ_ID_BUILTIN` to `1`. Otherwise provide your own custom implementation. -The ID is automatically generated and assigned to `obj->id` during obj's -construction by calling API `lv_obj_assign_id(obj)` from ``lv_obj_constructor``. +The ID is automatically generated and assigned to :cpp:expr:`obj->id` during obj's +construction by calling API :cpp:expr:`lv_obj_assign_id(obj)` from :cpp:func:`lv_obj_constructor`. -You can directly access the ID by `obj->id` or use API ``lv_obj_stringify_id(obj, buf, len)`` +You can directly access the ID by :cpp:expr:`obj->id` or use API :cpp:expr:`lv_obj_stringify_id(obj, buf, len)` to get a string representation of the ID. Use custom ID generator ~~~~~~~~~~~~~~~~~~~~~~~ -Set `LV_USE_OBJ_ID_BUILTIN` to 0 in `lv_conf.h`. Below APIs needed to be implemented and +Set :c:macro:`LV_USE_OBJ_ID_BUILTIN` to `0` in ``lv_conf.h``. Below APIs needed to be implemented and linked to lvgl. .. code:: c @@ -32,21 +36,21 @@ linked to lvgl. const char * lv_obj_stringify_id(lv_obj_t * obj, char * buf, uint32_t len); -:c:func:``lv_obj_assign_id`` is called when an object is created. The object final class is passed from -parameter ``class_p``. Note it may be different than ``obj->class_p`` which is the class +:cpp:func:`lv_obj_assign_id` is called when an object is created. The object final class is passed from +parameter ``class_p``. Note it may be different than :cpp:expr:`obj->class_p` which is the class currently being constructed. -:c:func:``lv_obj_free_id`` is called when object is deconstructed. Free any resource allocated in ``lv_obj_assign_id``. +:cpp:func:`lv_obj_free_id` is called when object is deconstructed. Free any resource allocated in :cpp:func:`lv_obj_assign_id`. -:c:func:``lv_obj_stringify_id`` converts id to a string representation. The string is stored in ``buf``. +:cpp:func:`lv_obj_stringify_id` converts id to a string representation. The string is stored in ``buf``. Dump obj tree ~~~~~~~~~~~~~ -Use API ``lv_obj_dump_tree(lv_obj_t * obj, int depth)`` to dump the object tree. +Use API :cpp:expr:`lv_obj_dump_tree(lv_obj_t * obj, int depth)` to dump the object tree. It will walk through all children and print the object ID together with object address. This is useful to debug UI crash. From log we can rebuilt UI the moment before crash. -For example, if the obj is stored to a timer->user_data, but obj is deleted when timer expired. +For example, if the obj is stored to a :cpp:expr:`timer->user_data`, but obj is deleted when timer expired. Timer callback will crash because of accessing wild pointer. From the dump log we can clearly see that the obj does not exist. diff --git a/docs/others/obj_property.rst b/docs/others/obj_property.rst index 02c6de00a..ed5ba4260 100644 --- a/docs/others/obj_property.rst +++ b/docs/others/obj_property.rst @@ -1,3 +1,5 @@ +.. _obj_property: + =============== Widget Property =============== @@ -6,11 +8,13 @@ Widgets have many properties that can decide what they look like and how they be For example, the size, position, color, font, etc. are properties of a widget. Specially, widget local style is also a property of a widget. +.. _obj_property_usage: + Usage ----- Two APIs are provided to get/set widget properties. It can be enabled by setting -``LV_USE_OBJ_PROPERTY`` to 1 in `lv_conf.h`. +:c:macro:`LV_USE_OBJ_PROPERTY` to `1` in ``lv_conf.h``. .. code:: c @@ -27,20 +31,23 @@ Two APIs are provided to get/set widget properties. It can be enabled by setting lv_result_t lv_obj_set_property(lv_obj_t * obj, const lv_property_t * value); lv_property_t lv_obj_get_property(lv_obj_t * obj, lv_prop_id_t id); +.. _obj_property_id: Property ID ~~~~~~~~~~~ -``lv_prop_id_t`` identifies which property to get/set. ``lv_property_t`` is an enum value -defined in `lv_obj_property.h` that are grouped by widget class. You can add your own -widget property ID following same rule and using helper macro ``LV_PROPERTY_ID``. +:cpp:type:`lv_prop_id_t` identifies which property to get/set. :cpp:type:`lv_property_t` is an enum value +defined in ``lv_obj_property.h`` that are grouped by widget class. You can add your own +widget property ID following same rule and using helper macro :c:macro:`LV_PROPERTY_ID`. Do make sure the ID is unique across all widgets. Property ID is a 32-bit value. The higher 4bits indicates the property value type. The lower 28bits is the property ID. -Note that ``lv_style_prop_t`` is also valid property ID. +Note that :cpp:type:`lv_style_prop_t` is also valid property ID. + +.. _obj_property_value: Property Value ~~~~~~~~~~~~~~ diff --git a/docs/others/observer.rst b/docs/others/observer.rst index 45b801979..04acb7d6f 100644 --- a/docs/others/observer.rst +++ b/docs/others/observer.rst @@ -1,15 +1,20 @@ +.. _observer: + ======== Observer ======== +.. _observer_overview: + Overview ******** The ``lv_observer`` module implements a standard `Observer pattern `__. + It consists of -- subjects: each containing a value -- observers: attached to subjects to be notified on value change +- **subjects**: each containing a value +- **observers**: attached to subjects to be notified on value change A typical use case looks like this: @@ -65,6 +70,7 @@ A typical use case looks like this: } +.. _observer_subject: Subject ******* @@ -72,16 +78,16 @@ Subject Subject initialization ---------------------- -Subjects have to be static or global :c:expr:`lv_subject_t` type variables. +Subjects have to be static or global :cpp:expr:`lv_subject_t` type variables. -To initialize a subject use :c:expr:`lv_subject_init_(&subject, , init_value)`. +To initialize a subject use :cpp:expr:`lv_subject_init_(&subject, params, init_value)`. The following initializations exist for types: -- **Integer** :c:expr:`void lv_subject_init_int(lv_subject_t * subject, int32_t value)` -- **String** :c:expr:`void lv_subject_init_string(lv_subject_t * subject, char * buf, char * prev_buf, size_t size, const char * value)` -- **Pointer** :c:expr:`void lv_subject_init_pointer(lv_subject_t * subject, void * value)` -- **Color** :c:expr:`void lv_subject_init_color(lv_subject_t * subject, lv_color_t color)` -- **Group** :c:expr:`void lv_subject_init_group(lv_subject_t * subject, lv_subject_t * list[], uint32_t list_len)` +- **Integer** :cpp:expr:`void lv_subject_init_int(lv_subject_t * subject, int32_t value)` +- **String** :cpp:expr:`void lv_subject_init_string(lv_subject_t * subject, char * buf, char * prev_buf, size_t size, const char * value)` +- **Pointer** :cpp:expr:`void lv_subject_init_pointer(lv_subject_t * subject, void * value)` +- **Color** :cpp:expr:`void lv_subject_init_color(lv_subject_t * subject, lv_color_t color)` +- **Group** :cpp:expr:`void lv_subject_init_group(lv_subject_t * subject, lv_subject_t * list[], uint32_t list_len)` Set subject value @@ -89,10 +95,10 @@ Set subject value The following functions can be used to set a subject's value: -- **Integer** :c:expr:`void lv_subject_set_int(lv_subject_t * subject, int32_t value)` -- **String** :c:expr:`void lv_subject_copy_string(lv_subject_t * subject, char * buf)` -- **Pointer** :c:expr:`void lv_subject_set_pointer(lv_subject_t * subject, void * ptr)` -- **Color** :c:expr:`void lv_subject_set_color(lv_subject_t * subject, lv_color_t color)` +- **Integer** :cpp:expr:`void lv_subject_set_int(lv_subject_t * subject, int32_t value)` +- **String** :cpp:expr:`void lv_subject_copy_string(lv_subject_t * subject, char * buf)` +- **Pointer** :cpp:expr:`void lv_subject_set_pointer(lv_subject_t * subject, void * ptr)` +- **Color** :cpp:expr:`void lv_subject_set_color(lv_subject_t * subject, lv_color_t color)` Get subject's value ------------------- @@ -100,10 +106,10 @@ Get subject's value The following functions can be used to get a subject's value: -- **Integer** :c:expr:`int32_t lv_subject_get_int(lv_subject_t * subject)` -- **String** :c:expr:`const char * lv_subject_get_string(lv_subject_t * subject)` -- **Pointer** :c:expr:`const void * lv_subject_get_pointer(lv_subject_t * subject)` -- **Color** :c:expr:`lv_color_t lv_subject_get_color(lv_subject_t * subject)` +- **Integer** :cpp:expr:`int32_t lv_subject_get_int(lv_subject_t * subject)` +- **String** :cpp:expr:`const char * lv_subject_get_string(lv_subject_t * subject)` +- **Pointer** :cpp:expr:`const void * lv_subject_get_pointer(lv_subject_t * subject)` +- **Color** :cpp:expr:`lv_color_t lv_subject_get_color(lv_subject_t * subject)` Get subject's previous value @@ -112,11 +118,12 @@ Get subject's previous value The following functions can be used to get a subject's previous value: -- **Integer** :c:expr:`int32_t lv_subject_get_previous_int(lv_subject_t * subject)` -- **String** :c:expr:`const char * lv_subject_get_previous_string(lv_subject_t * subject)` -- **Pointer** :c:expr:`const void * lv_subject_get_previous_pointer(lv_subject_t * subject)` -- **Color** :c:expr:`lv_color_t lv_subject_get_previous_color(lv_subject_t * subject)` +- **Integer** :cpp:expr:`int32_t lv_subject_get_previous_int(lv_subject_t * subject)` +- **String** :cpp:expr:`const char * lv_subject_get_previous_string(lv_subject_t * subject)` +- **Pointer** :cpp:expr:`const void * lv_subject_get_previous_pointer(lv_subject_t * subject)` +- **Color** :cpp:expr:`lv_color_t lv_subject_get_previous_color(lv_subject_t * subject)` +.. _observer_observer: Observer ******** @@ -144,7 +151,7 @@ Where the observer callback should look like this: It's also possible to save a target widget when subscribing to a subject. In this case when widget is deleted, it will automatically unsubscribe from the subject. -In the observer callback ``lv_observer_get_target(observer)`` can be used to get the saved widget. +In the observer callback :cpp:expr:`lv_observer_get_target(observer)` can be used to get the saved widget. .. code:: c @@ -172,6 +179,7 @@ To unsubscribe from a subject with all widgets you can use: lv_subject_remove_obj(subject, obj) +.. _observer_subject_groups: Subject groups ************** @@ -232,6 +240,7 @@ The above Voltage/Current measurement example looks like this in the practice: lv_label_set_text_fmt(label, "%s: %d %s", mode ? "Current" : "Voltage", value, unit); } +.. _observer_widget_binding: Widget binding ************** @@ -320,11 +329,14 @@ Bind an integer subject to a drop-down's value observer = lv_dropdown_bind_value(obj, &subject); +.. _observer_example: Example ******* .. include:: ../examples/others/observer/index.rst +.. _observer_api: + API *** diff --git a/docs/others/snapshot.rst b/docs/others/snapshot.rst index 7ec19c5af..d6dcf2d84 100644 --- a/docs/others/snapshot.rst +++ b/docs/others/snapshot.rst @@ -1,3 +1,5 @@ +.. _snapshot: + ======== Snapshot ======== @@ -5,29 +7,32 @@ Snapshot Snapshot provides API to take snapshot image for LVGL object together with its children. The image will look exactly like the object on display. +.. _snapshot_usage: + Usage ----- -Simply call API :c:func:`lv_snapshot_take` to generate the image descriptor -which can be set as image object src using :c:func:`lv_image_set_src`. +Simply call API :cpp:func:`lv_snapshot_take` to generate the image descriptor +which can be set as image object src using :cpp:func:`lv_image_set_src`. Note, only following color formats are supported for now: -- LV_COLOR_FORMAT_RGB565 -- LV_COLOR_FORMAT_RGB888 -- LV_COLOR_FORMAT_XRGB8888 -- LV_COLOR_FORMAT_ARGB8888 + +- :cpp:enumerator:`LV_COLOR_FORMAT_RGB565` +- :cpp:enumerator:`LV_COLOR_FORMAT_RGB888` +- :cpp:enumerator:`LV_COLOR_FORMAT_XRGB8888` +- :cpp:enumerator:`LV_COLOR_FORMAT_ARGB8888` Free the Image ~~~~~~~~~~~~~~ -The memory :c:func:`lv_snapshot_take` uses are dynamically allocated using -:c:func:`lv_malloc`. Use API :c:func:`lv_snapshot_free` to free the memory it +The memory :cpp:func:`lv_snapshot_take` uses are dynamically allocated using +:cpp:func:`lv_malloc`. Use API :cpp:func:`lv_snapshot_free` to free the memory it takes. This will firstly free memory the image data takes, then the image descriptor. Take caution to free the snapshot but not delete the image object. Before free the memory, be sure to firstly unlink it from image object, -using :c:expr:`lv_image_set_src(NULL)` and :c:expr:`lv_cache_invalidate(lv_cache_find(src, LV_CACHE_SRC_TYPE_PTR, 0, 0));`. +using :cpp:expr:`lv_image_set_src(NULL)` and :cpp:expr:`lv_cache_invalidate(lv_cache_find(src, LV_CACHE_SRC_TYPE_PTR, 0, 0));`. Below code snippet explains usage of this API. @@ -55,14 +60,18 @@ and image data will be stored to provided ``buf``. Note that snapshot may fail if provided buffer is not enough, which may happen when object size changes. It's recommended to use API -:c:func:`lv_snapshot_buf_size_needed` to check the needed buffer size in byte +:cpp:func:`lv_snapshot_buf_size_needed` to check the needed buffer size in byte firstly and resize the buffer accordingly. +.. _snapshot_example: + Example ------- .. include:: ../examples/others/snapshot/index.rst +.. _snapshot_api: + API --- diff --git a/docs/overview/anim.rst b/docs/overview/animations.rst similarity index 97% rename from docs/overview/anim.rst rename to docs/overview/animations.rst index 8efda7bfd..26fbe7e2e 100644 --- a/docs/overview/anim.rst +++ b/docs/overview/animations.rst @@ -1,3 +1,5 @@ +.. _animations: + ========== Animations ========== @@ -16,6 +18,8 @@ This prototype is compatible with the majority of the property *set* functions in LVGL. For example :cpp:expr:`lv_obj_set_x(obj, value)` or :cpp:expr:`lv_obj_set_width(obj, value)` +.. _animations_create: + Create an animation ******************* @@ -89,6 +93,8 @@ same time. For example, animate the x and y coordinates with exist with a given variable and function pair and :cpp:func:`lv_anim_start` will remove any existing animations for such a pair. +.. _animations_path: + Animation path ************** @@ -107,6 +113,8 @@ the following built-in path functions: - :cpp:func:`lv_anim_path_bounce`: bounce back a little from the end value (like hitting a wall) +.. _animations_speed_vs_time: + Speed vs time ************* @@ -120,12 +128,16 @@ For example, :cpp:expr:`lv_anim_speed_to_time(20, 0, 100)` will yield 5000 milliseconds. For example, in the case of :cpp:func:`lv_obj_set_x` *unit* is pixels so *20* means *20 px/sec* speed. +.. _animations_delete: + Delete animations ***************** You can delete an animation with :cpp:expr:`lv_anim_delete(var, func)` if you provide the animated variable and its animator function. +.. _animations_timeline: + Timeline ******** @@ -168,10 +180,14 @@ anim timeline before deleting the object. Otherwise, the program may crash or be .. image:: /misc/anim-timeline.png +.. _animations_example: + Examples ******** .. include:: ../examples/anim/index.rst +.. _animations_api: + API *** diff --git a/docs/overview/color.rst b/docs/overview/color.rst index f67f01920..8b735209d 100644 --- a/docs/overview/color.rst +++ b/docs/overview/color.rst @@ -1,3 +1,5 @@ +.. _color: + ====== Colors ====== @@ -7,8 +9,9 @@ depth, creating colors from hex code, converting between color depths, mixing colors, etc. The type :cpp:type:`lv_color_t` is used to store a color in RGB888 format. -This type and format is used in almost all APIs regardless to -:cpp:expr`LV_COLOR_DEPTH`. +This type and format is used in almost all APIs regardless to :cpp:expr:`LV_COLOR_DEPTH`. + +.. _color_create: Creating colors *************** @@ -50,6 +53,8 @@ Create colors from Hue, Saturation and Value values: //From lv_color_t variable lv_color_hsv_t c_hsv = lv_color_to_hsv(color); +.. _color_palette: + Palette ------- @@ -88,6 +93,8 @@ For the lighter variants of a palette color use ``lv_color_t c = lv_palette_darken(LV_PALETTE_..., v)``. ``v`` can be 1..4. +.. _color_modify_and_mix: + Modify and mix colors --------------------- @@ -108,12 +115,16 @@ The following functions can modify a color: // Mix two colors with a given ratio 0: full c2, 255: full c1, 128: half c1 and half c2 lv_color_t c = lv_color_mix(c1, c2, ratio); +.. _color_builtin: + Built-in colors --------------- :cpp:func:`lv_color_white` and :cpp:func:`lv_color_black` return ``0xFFFFFF`` and ``0x000000`` respectively. +.. _color_opacity: + Opacity ******* @@ -131,7 +142,7 @@ Some special purpose defines are also introduced: You can also use the ``LV_OPA_*`` defines in :cpp:func:`lv_color_mix` as a mixing *ratio*. - +.. _color_api: API *** diff --git a/docs/overview/coord.rst b/docs/overview/coord.rst index b99c08131..d7c09c2f8 100644 --- a/docs/overview/coord.rst +++ b/docs/overview/coord.rst @@ -1,3 +1,5 @@ +.. _coord: + ============================= Positions, sizes, and layouts ============================= @@ -19,6 +21,8 @@ In short this means: - Explicitly set coordinates are stored in styles - 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_unites: + Units ----- @@ -31,6 +35,8 @@ Units object to involve all the children. It's similar to ``auto`` in CSS. E.g. :cpp:expr:`lv_obj_set_width(btn, LV_SIZE_CONTENT)`. +.. _coord_boxing_model: + Boxing model ------------ @@ -51,12 +57,16 @@ keeps a "padding margin" when placing an object's children. The outline is drawn outside the bounding box. +.. _coord_notes: + Important notes --------------- This section describes special cases in which LVGL's behavior might be unexpected. +.. _coord_postponed_coordinate_calculation: + Postponed coordinate calculation ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -73,6 +83,8 @@ The size and position might depend on the parent or layout. Therefore :cpp:func:`lv_obj_update_layout` recalculates the coordinates of all objects on the screen of ``obj``. +.. _coord_removing styles: + Removing styles ^^^^^^^^^^^^^^^ @@ -111,6 +123,8 @@ For example: lv_obj_remove_style_all(obj2); lv_obj_set_size(obj2, 200, 100); +.. _coord_position: + Position ******** @@ -213,6 +227,8 @@ Note that, unlike with :cpp:func:`lv_obj_align`, :cpp:func:`lv_obj_align_to` can realign the object if its coordinates or the reference object's coordinates change. +.. _coord_size: + Size **** @@ -262,6 +278,8 @@ the following functions: int32_t content_w = lv_obj_get_content_width(obj); int32_t content_h = lv_obj_get_content_height(obj); +.. _coord_using_styles: + Using styles ************ @@ -291,7 +309,7 @@ Here are some examples to set an object's size using a style: lv_style_init(&style); lv_style_set_width(&style, 100); - lv_obj_t * btn = lv_btn_create(lv_screen_active()); + lv_obj_t * btn = lv_button_create(lv_screen_active()); lv_obj_add_style(btn, &style, LV_PART_MAIN); As you will see below there are some other great features of size and @@ -299,6 +317,8 @@ position setting. However, to keep the LVGL API lean, only the most common coordinate setting features have a "simple" version and the more complex features can be used via styles. +.. _coord_translation: + Translation *********** @@ -365,6 +385,8 @@ The translation actually moves the object. That means it makes the scrollbars and :c:macro:`LV_SIZE_CONTENT` sized objects react to the position change. +.. _coord_transformation: + Transformation ************** @@ -389,6 +411,8 @@ This code enlarges a button when it's pressed: lv_obj_add_style(btn, &style_pressed, LV_STATE_PRESSED); +.. _coord_min_max_size: + Min and Max size ---------------- @@ -419,6 +443,8 @@ the parent's content area. lv_obj_set_height(obj, lv_pct(100)); lv_obj_add_style(obj, &style_max_height, LV_STATE_DEFAULT); //Limit the height to half parent height +.. _coord_layout: + Layout ****** @@ -499,8 +525,12 @@ the update callback. For example: lv_style_set_prop(style, LV_STYLE_MY_PROP, v); } +.. _coord_example: + Examples ******** +.. _coord_api: + API *** diff --git a/docs/overview/disp.rst b/docs/overview/display.rst similarity index 89% rename from docs/overview/disp.rst rename to docs/overview/display.rst index f30957441..e2be28f81 100644 --- a/docs/overview/disp.rst +++ b/docs/overview/display.rst @@ -1,8 +1,12 @@ +.. _display: + ======== Displays ======== -:important: The basic concept of a *display* in LVGL is explained in the [Porting](/porting/display) section. So before reading further, please read the [Porting](/porting/display) section first. +:important: The basic concept of a *display* in LVGL is explained in the :ref:`porting` section. So before reading further, please read that section first. + +.. _display_multi_display_support: Multiple display support ************************ @@ -23,6 +27,8 @@ Why would you want multi-display support? Here are some examples: - Have some smaller and simple displays in a large instrument or technology. - Have two large TFT displays: one for a customer and one for the shop assistant. +.. _display_one_display: + Using only one display ---------------------- @@ -36,7 +42,7 @@ hidden if you register only one display. By default, the last created on the most recently created (default) display. If you pass ``NULL`` as ``disp`` parameter to display related functions the default display will usually be used. E.g. :cpp:expr:`lv_display_trig_activity(NULL)` will trigger a -user activity on the default display. (See below in `Inactivity <#Inactivity>`__). +user activity on the default display. (See below in :ref:`Inactivity `). Mirror display -------------- @@ -54,10 +60,12 @@ large display's resolution. 2. In ``flush_cb``, truncate and modify the ``area`` parameter for each display. 3. Send the buffer's content to each real display with the truncated area. +.. _display_screens: + Screens ******* -Every display has its own set of `screens `__ and the +Every display has its own set of :ref:`screens ` and the objects on each screen. Be sure not to confuse displays and screens: @@ -70,11 +78,11 @@ Be sure not to confuse displays and screens: Screens can be considered the highest level containers which have no parent. A screen's size is always equal to its display and their origin is (0;0). Therefore, a screen's coordinates can't be changed, -i.e. :cpp:expr:`lv_obj_set_pos()`, :cpp:expr:`lv_obj_set_size()` or similar functions +i.e. :cpp:func:`lv_obj_set_pos`, :cpp:func:`lv_obj_set_size` or similar functions can't be used on screens. A screen can be created from any object type but the two most typical -types are `Base object `__ and `Image `__ +types are :ref:`Base object ` and :ref:`Image ` (to create a wallpaper). To create a screen, use @@ -85,7 +93,7 @@ use :cpp:expr:`lv_screen_active()`. These functions work on the default display. you want to specify which display to work on, use :cpp:expr:`lv_display_get_screen_active(disp)` and :cpp:expr:`lv_display_load_scr(disp, scr)`. A screen can be loaded with animations too. Read more -`here `__. +:ref:`here `. Screens can be deleted with :cpp:expr:`lv_obj_delete(scr)`, but ensure that you do not delete the currently loaded screen. @@ -118,14 +126,18 @@ UIs: - Set a color format with alpha channel. E.g. :cpp:expr:`lv_display_set_color_format(disp, LV_COLOR_FORMAT_ARGB8888)` +.. _display_features: + Features of displays ******************** +.. _display_inactivity: + Inactivity ---------- A user's inactivity time is measured on each display. Every use of an -`Input device `__ (if `associated with the display `__) counts as an activity. To +:ref:`Input device ` (if :ref:`associated with the display `) counts as an activity. To get time elapsed since the last activity, use :cpp:expr:`lv_display_get_inactive_time(disp)`. If ``NULL`` is passed, the lowest inactivity time among all displays will be returned (**NULL isn't just @@ -157,5 +169,7 @@ The opacity of the background color or image can be adjusted with The ``disp`` parameter of these functions can be ``NULL`` to select the default display. +.. _display_api: + API *** diff --git a/docs/overview/draw.rst b/docs/overview/draw.rst index 6a0dd19fe..b6477dd8b 100644 --- a/docs/overview/draw.rst +++ b/docs/overview/draw.rst @@ -37,6 +37,8 @@ finished. The main difference is that with LVGL you don't have to store two frame buffers (which usually requires external RAM) but only smaller draw buffer(s) that can easily fit into internal RAM. +.. _drawing_screen_refresh: + Mechanism of screen refreshing ****************************** @@ -80,6 +82,8 @@ is the following: flushing should be done by DMA (or similar hardware) in the background. 3. **Double buffering** - ``flush_cb`` should only swap the addresses of the frame buffers. +.. _drawing_masking: + Masking ******* @@ -167,6 +171,8 @@ to be freed when not required anymore. :cpp:func:`lv_draw_mask_add` saves only the pointer of the mask so the parameter needs to be valid while in use. +.. _drawing_hooks: + Hook drawing ************ @@ -177,7 +183,7 @@ that tell what LVGL is about to draw. Some fields of these parameters can be modified to draw something else or any custom drawing operations can be added manually. -A good use case for this is the `Button matrix `__ +A good use case for this is the :ref:`Button matrix ` widget. By default, its buttons can be styled in different states, but you can't style the buttons one by one. However, an event is sent for every button and you can, for example, tell LVGL to use different colors @@ -185,6 +191,8 @@ on a specific button or to manually draw an image on some buttons. Each of these events is described in detail below. +.. _drawing_hooks_main: + Main drawing ------------ @@ -195,8 +203,6 @@ drawing of buttons, texts, etc. happens here. and in that structure is the clip area. The clip area is required in draw functions to make them draw only on a limited area. - - LV_EVENT_DRAW_MAIN_BEGIN ^^^^^^^^^^^^^^^^^^^^^^^^ @@ -219,6 +225,8 @@ Called when the main drawing is finished. You can draw anything here as well and it's also a good place to remove any masks created in :cpp:enumerator:`LV_EVENT_DRAW_MAIN_BEGIN`. +.. _drawing_hooks_post: + Post drawing ------------ @@ -247,6 +255,8 @@ LV_EVENT_DRAW_POST_END Called when post drawing has finished. If masks were not removed in :cpp:enumerator:`LV_EVENT_DRAW_MAIN_END` they should be removed here. +.. _drawing_hooks_parts: + Part drawing ------------ @@ -307,6 +317,8 @@ LV_EVENT_DRAW_PART_END Finish the drawing of a part. This is a good place to draw extra content on the part or remove masks added in :cpp:enumerator:`LV_EVENT_DRAW_PART_BEGIN`. +.. _drawing_hooks_others: + Others ------ @@ -359,5 +371,7 @@ required for the text. You can simply set the required draw area with :cpp:expr:`lv_event_set_ext_draw_size(e, size)`. +.. _drawing_api: + API *** diff --git a/docs/overview/event.rst b/docs/overview/event.rst index e5b6878ea..55a42e32a 100644 --- a/docs/overview/event.rst +++ b/docs/overview/event.rst @@ -94,7 +94,7 @@ All objects (such as Buttons/Labels/Sliders etc.) regardless their type receive the *Input device*, *Drawing* and *Other* events. However, the *Special events* are specific to a particular widget type. -See the `widgets' documentation `__ to learn when they +See the :ref:`widgets' documentation ` to learn when they are sent, *Custom events* are added by the user and are never sent by LVGL. @@ -167,16 +167,16 @@ Other events Display events -------------- -- :cpp:enumerator:`LV_EVENT_INVALIDATE_AREA, -- :cpp:enumerator:`LV_EVENT_RESOLUTION_CHANGED, -- :cpp:enumerator:`LV_EVENT_COLOR_FORMAT_CHANGED, -- :cpp:enumerator:`LV_EVENT_REFR_REQUEST, -- :cpp:enumerator:`LV_EVENT_REFR_START, -- :cpp:enumerator:`LV_EVENT_REFR_READY, -- :cpp:enumerator:`LV_EVENT_RENDER_START, -- :cpp:enumerator:`LV_EVENT_RENDER_READY, -- :cpp:enumerator:`LV_EVENT_FLUSH_START, -- :cpp:enumerator:`LV_EVENT_FLUSH_FINISH, +- :cpp:enumerator:`LV_EVENT_INVALIDATE_AREA` +- :cpp:enumerator:`LV_EVENT_RESOLUTION_CHANGED` +- :cpp:enumerator:`LV_EVENT_COLOR_FORMAT_CHANGED` +- :cpp:enumerator:`LV_EVENT_REFR_REQUEST` +- :cpp:enumerator:`LV_EVENT_REFR_START` +- :cpp:enumerator:`LV_EVENT_REFR_READY` +- :cpp:enumerator:`LV_EVENT_RENDER_START` +- :cpp:enumerator:`LV_EVENT_RENDER_READY` +- :cpp:enumerator:`LV_EVENT_FLUSH_START` +- :cpp:enumerator:`LV_EVENT_FLUSH_FINISH` Custom events @@ -242,10 +242,14 @@ The *target* parameter of the event is always the current target object, not the original object. To get the original target call :cpp:expr:`lv_event_get_target_obj(e)` in the event handler. +.. _events_examples: + Examples ******** .. include:: ../examples/event/index.rst +.. _events_api: + API *** diff --git a/docs/overview/font.rst b/docs/overview/font.rst index d2daeabf6..b4ee78218 100644 --- a/docs/overview/font.rst +++ b/docs/overview/font.rst @@ -1,3 +1,5 @@ +.. _fonts: + ===== Fonts ===== @@ -42,7 +44,11 @@ Built-in fonts ************** There are several built-in fonts in different sizes, which can be -enabled in ``lv_conf.h`` with *LV_FONT\_…* defines. ### Normal fonts +enabled in ``lv_conf.h`` with *LV_FONT\_…* defines. + +Normal fonts +------------ + Containing all the ASCII characters, the degree symbol (U+00B0), the bullet symbol (U+2022) and the built-in symbols (see below). @@ -86,6 +92,8 @@ In addition to the ASCII range, the following symbols are also added to the built-in fonts from the `FontAwesome `__ font. +.. _fonts_symbols: + .. image:: /misc/symbols.png The symbols can be used singly as: @@ -146,10 +154,10 @@ This list summarizes the effect of RTL base direction on objects: - Create objects by default on the right - ``lv_tabview``: Displays tabs from right to left - ``lv_checkbox``: Shows the box on the right -- ``lv_btnmatrix``: Shows buttons from right to left +- ``lv_buttonmatrix``: Shows buttons from right to left - ``lv_list``: Shows icons on the right - ``lv_dropdown``: Aligns options to the right -- The texts in ``lv_table``, ``lv_btnmatrix``, ``lv_keyboard``, ``lv_tabview``, ``lv_dropdown``, ``lv_roller`` are "BiDi processed" to be displayed correctly +- The texts in ``lv_table``, ``lv_buttonmatrix``, ``lv_keyboard``, ``lv_tabview``, ``lv_dropdown``, ``lv_roller`` are "BiDi processed" to be displayed correctly Arabic and Persian support -------------------------- @@ -285,7 +293,7 @@ to have a special binary format. (Not TTF or WOFF). Use `lv_font_conv `__ with the ``--format bin`` option to generate an LVGL compatible font file. -:note: To load a font `LVGL's filesystem `__ +:note: To load a font :ref:`LVGL's filesystem ` needs to be enabled and a driver must be added. Example @@ -308,7 +316,7 @@ Load a font from a memory buffer at run-time This function may be useful to load a font from an external file system, which is not supported by LVGL. The font needs to be in the same format as if it were loaded from a file. -:note: To load a font from a buffer `LVGL's filesystem `__ +:note: To load a font from a buffer :ref:`LVGL's filesystem ` needs to be enabled and the MEMFS driver must be added. Example @@ -408,5 +416,7 @@ font from ``fallback`` to handle. /* So now we can display Roboto for supported characters while having wider characters set support */ roboto->fallback = droid_sans_fallback; +.. _fonts_api: + API *** diff --git a/docs/overview/fs.rst b/docs/overview/fs.rst index bc908e450..de6d7746d 100644 --- a/docs/overview/fs.rst +++ b/docs/overview/fs.rst @@ -1,4 +1,4 @@ -.. _file-system: +.. _overview_file_system: =========== File system @@ -14,7 +14,7 @@ Ready to use drivers LVGL contains prepared drivers for the API of POSIX, standard C, Windows, and `FATFS `__. -Learn more `here `__. +Learn more :ref:`here `. Adding a driver *************** @@ -109,8 +109,8 @@ The example below shows how to read from a file: lv_fs_close(&f); -*The mode in :cpp:func:`lv_fs_open` can be :cpp:enumerator:`LV_FS_MODE_WR` to open for writes -only or :cpp:enumerator:`LV_FS_MODE_RD` ``|`` :cpp:enumerator:`LV_FS_MODE_WR` for both* +The mode in :cpp:func:`lv_fs_open` can be :cpp:enumerator:`LV_FS_MODE_WR` to open for writes +only or :cpp:enumerator:`LV_FS_MODE_RD` ``|`` :cpp:enumerator:`LV_FS_MODE_WR` for both This example shows how to read a directory's content. It's up to the driver how to mark directories in the result but it can be a good @@ -144,7 +144,7 @@ practice to insert a ``'/'`` in front of each directory name. Use drives for images ********************* -`Image `__ objects can be opened from files too (besides +:ref:`Image ` objects can be opened from files too (besides variables stored in the compiled program). To use files in image widgets the following callbacks are required: @@ -155,5 +155,7 @@ To use files in image widgets the following callbacks are required: - seek - tell +.. _overview_file_system_api: + API *** diff --git a/docs/overview/img.rst b/docs/overview/image.rst similarity index 98% rename from docs/overview/img.rst rename to docs/overview/image.rst index 4112bbe85..2a0bdd02e 100644 --- a/docs/overview/img.rst +++ b/docs/overview/image.rst @@ -1,3 +1,5 @@ +.. _overview_image: + ====== Images ====== @@ -41,13 +43,15 @@ registered in LVGL to make file operations. You can add an interface to a standard file system (FAT32 on SD card) or you create your simple file system to read data from an SPI Flash memory. In every case, a *Drive* is just an abstraction to read and/or write data to memory. See the -`File system `__ section to learn more. +:ref:`File system ` section to learn more. Images stored as files are not linked into the resulting executable, and must be read into RAM before being drawn. As a result, they are not as resource-friendly as images linked at compile time. However, they are easier to replace without needing to rebuild the main program. +.. _overview_image_color_formats: + Color formats ************* @@ -79,7 +83,7 @@ The bytes of :cpp:enumerator:`LV_COLOR_FORMAT_NATIVE` images are stored in the f - **Byte 2**: Alpha byte (only with :cpp:enumerator:`LV_COLOR_FORMAT_NATIVE_WITH_ALPHA`) You can store images in a *Raw* format to indicate that it's not encoded -with one of the built-in color formats and an external `Image decoder <#image-decoder>`__ +with one of the built-in color formats and an external :ref:`Image decoder ` needs to be used to decode the image. - :cpp:enumerator:`LV_COLOR_FORMAT_RAW`: Indicates a basic raw image (e.g. a PNG or JPG image). @@ -143,13 +147,13 @@ variable to display it using LVGL. For example: }; Another (possibly simpler) option to create and display an image at -run-time is to use the `Canvas `__ object. +run-time is to use the :ref:`Canvas ` object. Use images ---------- The simplest way to use an image in LVGL is to display it with an -`lv_image `__ object: +:ref:`lv_image` object: .. code:: c @@ -165,6 +169,8 @@ If the image was converted with the online converter, you should use :cpp:expr:`LV_IMAGE_DECLARE(my_icon_dsc)` to declare the image in the file where you want to use it. +.. _overview_image_decoder: + Image decoder ************* @@ -436,7 +442,7 @@ See the detailed code below: ... } -.. _image-caching: +.. _overview_image_caching: Image caching ************* @@ -576,5 +582,7 @@ following code to replace the LVGL built-in cache manager: lv_cache_unlock(); } +.. _overview_image_api: + API *** diff --git a/docs/overview/indev.rst b/docs/overview/indev.rst index 3257dcf6d..9f1533450 100644 --- a/docs/overview/indev.rst +++ b/docs/overview/indev.rst @@ -1,3 +1,5 @@ +.. _indev: + ============= Input devices ============= @@ -14,6 +16,8 @@ An input device usually means: Pointers ******** +.. _indev_cursor: + Cursor ------ @@ -33,6 +37,8 @@ Note that the cursor object should have :cpp:expr:`lv_obj_remove_flag(cursor_obj, LV_OBJ_FLAG_CLICKABLE)`. For images, *clicking* is disabled by default. +.. _indev_gestures: + Gestures -------- @@ -76,6 +82,8 @@ If you did some action on a gesture you can call :cpp:expr:`lv_indev_wait_release(lv_indev_active())` in the event handler to prevent LVGL sending further input device related events. +.. _indev_keypad_and_encoder: + Keypad and encoder ****************** @@ -83,15 +91,17 @@ You can fully control the user interface without a touchpad or mouse by using a keypad or encoder(s). It works similar to the *TAB* key on the PC to select an element in an application or a web page. +.. _indev_groups: + Groups ------ Objects you want to control with a keypad or encoder need to be added to a *Group*. In every group there is exactly one focused object which receives the pressed keys or the encoder actions. For example, if a -`Text area `__ is focused and you press some letter +:ref:`Text area ` is focused and you press some letter on a keyboard, the keys will be sent and inserted into the text area. -Similarly, if a `Slider `__ is focused and you press +Similarly, if a :ref:`Slider ` is focused and you press the left or right arrows, the slider's value will be changed. You need to associate an input device with a group. An input device can @@ -118,11 +128,11 @@ There are some predefined keys which have special meaning: - :cpp:enumerator:`LV_KEY_DOWN`: Decrease value or move downwards - :cpp:enumerator:`LV_KEY_RIGHT`: Increase value or move to the right - :cpp:enumerator:`LV_KEY_LEFT`: Decrease value or move to the left -- :cpp:enumerator:`LV_KEY_ESC`: Close or exit (E.g. close a `Drop down list `__) -- :cpp:enumerator:`LV_KEY_DEL`: Delete (E.g. a character on the right in a `Text area `__) -- :cpp:enumerator:`LV_KEY_BACKSPACE`: Delete a character on the left (E.g. in a `Text area `__) -- :cpp:enumerator:`LV_KEY_HOME`: Go to the beginning/top (E.g. in a `Text area `__) -- :cpp:enumerator:`LV_KEY_END`: Go to the end (E.g. in a `Text area `__) +- :cpp:enumerator:`LV_KEY_ESC`: Close or exit (E.g. close a :ref:`Drop down list `) +- :cpp:enumerator:`LV_KEY_DEL`: Delete (E.g. a character on the right in a :ref:`Text area `) +- :cpp:enumerator:`LV_KEY_BACKSPACE`: Delete a character on the left (E.g. in a :ref:`Text area `) +- :cpp:enumerator:`LV_KEY_HOME`: Go to the beginning/top (E.g. in a :ref:`Text area `) +- :cpp:enumerator:`LV_KEY_END`: Go to the end (E.g. in a :ref:`Text area `) The most important special keys In your ``read_cb`` function @@ -160,9 +170,9 @@ to *Edit* mode. In *Edit* mode, :cpp:enumerator:`LV_KEY_NEXT` and :cpp:enumerator:`LV_KEY_PREV` is usually used to modify an object. Depending on the object's type, a short or long press of :cpp:enumerator:`LV_KEY_ENTER` changes back to *Navigate* mode. Usually, an object -which cannot be pressed (like a `Slider `__) leaves +which cannot be pressed (like a :ref:`Slider `) leaves *Edit* mode upon a short click. But with objects where a short click has -meaning (e.g. `Button `__), a long press is required. +meaning (e.g. :ref:`Button `), a long press is required. Default group ^^^^^^^^^^^^^ @@ -190,5 +200,7 @@ For a more detailed description read the `Style `__ section. +.. _indev_api: + API *** diff --git a/docs/overview/index.rst b/docs/overview/index.rst index eef9b7af4..4ae76adee 100644 --- a/docs/overview/index.rst +++ b/docs/overview/index.rst @@ -16,12 +16,12 @@ Overview layer event indev - disp + display color font - img + image fs - anim + animations timer draw profiler diff --git a/docs/overview/layer.rst b/docs/overview/layer.rst index 217da4038..a5e81672a 100644 --- a/docs/overview/layer.rst +++ b/docs/overview/layer.rst @@ -1,7 +1,11 @@ +.. _layers: + ====== Layers ====== +.. _layers_creation: + Order of creation ***************** @@ -21,23 +25,25 @@ its children. lv_screen_load(scr); /*Load the screen*/ /*Create 2 buttons*/ - lv_obj_t * btn1 = lv_btn_create(scr, NULL); /*Create a button on the screen*/ - lv_btn_set_fit(btn1, true, true); /*Enable automatically setting the size according to content*/ - lv_obj_set_pos(btn1, 60, 40); /*Set the position of the button*/ + lv_obj_t * btn1 = lv_button_create(scr, NULL); /*Create a button on the screen*/ + lv_button_set_fit(btn1, true, true); /*Enable automatically setting the size according to content*/ + lv_obj_set_pos(btn1, 60, 40); /*Set the position of the button*/ - lv_obj_t * btn2 = lv_btn_create(scr, btn1); /*Copy the first button*/ - lv_obj_set_pos(btn2, 180, 80); /*Set the position of the button*/ + lv_obj_t * btn2 = lv_button_create(scr, btn1); /*Copy the first button*/ + lv_obj_set_pos(btn2, 180, 80); /*Set the position of the button*/ /*Add labels to the buttons*/ - lv_obj_t * label1 = lv_label_create(btn1, NULL); /*Create a label on the first button*/ - lv_label_set_text(label1, "Button 1"); /*Set the text of the label*/ + lv_obj_t * label1 = lv_label_create(btn1, NULL); /*Create a label on the first button*/ + lv_label_set_text(label1, "Button 1"); /*Set the text of the label*/ - lv_obj_t * label2 = lv_label_create(btn2, NULL); /*Create a label on the second button*/ - lv_label_set_text(label2, "Button 2"); /*Set the text of the label*/ + lv_obj_t * label2 = lv_label_create(btn2, NULL); /*Create a label on the second button*/ + lv_label_set_text(label2, "Button 2"); /*Set the text of the label*/ /*Delete the second label*/ lv_obj_delete(label2); +.. _layers_order: + Change order ************ @@ -54,6 +60,8 @@ There are four explicit ways to bring an object to the foreground: - Use :cpp:expr:`lv_obj_swap(obj1, obj2)` to swap the relative layer position of two objects. - When :cpp:expr:`lv_obj_set_parent(obj, new_parent)` is used, ``obj`` will be on the foreground of the ``new_parent``. +.. _layers_top_and_sys: + Top and sys layers ****************** @@ -63,7 +71,7 @@ however, shared among multiple physical displays.** The ``layer_top`` is always on top of the default screen (:cpp:func:`lv_screen_active`), and ``layer_sys`` is on top of ``layer_top``. -The get these layers use :cpp:func:`lv_layer_top()` and :cpp:func:`lv_layer_sys()`. +The get these layers use :cpp:func:`lv_layer_top` and :cpp:func:`lv_layer_sys`. These layers work like any other widget, meaning the can be styles, scrolled, and any kind of widgets can be created on them. @@ -81,6 +89,7 @@ The ``layer_sys`` is also used for similar purposes in LVGL. For example, it places the mouse cursor above all layers to be sure it's always visible. +.. _layers_bottom: Bottom layers ************* @@ -89,7 +98,9 @@ Similarly top and sys. layer bottom layer is also screen size but it's located below the active screen. It's visible only if the active screen's background opacity is < 255. -The get the bottom layer use :cpp:func:`lv_layer_bottom()`. +The get the bottom layer use :cpp:func:`lv_layer_bottom`. + +.. _layers_api: API *** diff --git a/docs/overview/new_widget.rst b/docs/overview/new_widget.rst index 1e876c0d7..35127af28 100644 --- a/docs/overview/new_widget.rst +++ b/docs/overview/new_widget.rst @@ -1,3 +1,5 @@ +.. _new_widget: + ========== New widget ========== diff --git a/docs/overview/obj.rst b/docs/overview/obj.rst index cfd60c398..71646af8f 100644 --- a/docs/overview/obj.rst +++ b/docs/overview/obj.rst @@ -1,19 +1,23 @@ +.. _objects: + ======= Objects ======= In LVGL the **basic building blocks** of a user interface are the objects, also called *Widgets*. For example a -`Button `__, `Label `__, -`Image `__, `List `__, -`Chart `__ or `Text area `__. +:ref:`Button `, :ref:`Label `, +:ref:`Image `, :ref:`List `, +:ref:`Chart ` or :ref:`Text area `. -You can see all the `Object types `__ here. +You can see all the :ref:`Object types ` here. All objects are referenced using an :cpp:type:`lv_obj_t` pointer as a handle. This pointer can later be used to set or get the attributes of the object. +.. _objects_attributes: + Attributes ********** @@ -38,7 +42,7 @@ You can set/get these attributes with ``lv_obj_set_...`` and lv_obj_set_size(btn1, 100, 50); /*Set a button's size*/ lv_obj_set_pos(btn1, 20,30); /*Set a button's position*/ -To see all the available functions visit the `Base object's documentation `__. +To see all the available functions visit the :ref:`Base object's documentation `. Specific attributes ------------------- @@ -58,9 +62,11 @@ functions. For example for a slider: lv_slider_set_value(slider1, 40, LV_ANIM_ON); /*Set the current value (position)*/ The API of the widgets is described in their -`Documentation `__ but you can also check the respective +:ref:`Documentation ` but you can also check the respective header files (e.g. *widgets/lv_slider.h*) +.. _objects_working_mechanisms: + Working mechanisms ****************** @@ -161,6 +167,8 @@ using :cpp:expr:`lv_obj_clean(obj)`. You can use :cpp:expr:`lv_obj_delete_delayed(obj, 1000)` to delete an object after some time. The delay is expressed in milliseconds. +.. _objects_screens: + Screens ******* @@ -175,7 +183,7 @@ be created like: lv_obj_t * scr1 = lv_obj_create(NULL); Screens can be created with any object type. For example, a -`Base object `__ or an image to make a wallpaper. +:ref:`Base object ` or an image to make a wallpaper. Get the active screen --------------------- @@ -185,6 +193,8 @@ library creates and loads a "Base object" as a screen for each display. To get the currently active screen use the :cpp:func:`lv_screen_active` function. +.. _objects_load_screens: + Load screens ------------ @@ -208,7 +218,7 @@ system-level things (e.g. mouse cursor will be placed there with The :cpp:func:`lv_layer_top` and :cpp:func:`lv_layer_sys` functions return pointers to the top and system layers respectively. -Read the `Layer overview `__ section to learn more +Read the :ref:`Layer overview ` section to learn more about layers. Load screen with animation @@ -242,14 +252,16 @@ display using :cpp:expr:`lv_disp_set_default(disp)`. :cpp:func:`lv_screen_active`, :cpp:func:`lv_screen_load` and :cpp:func:`lv_screen_load_anim` operate on the default display. -Visit `Multi-display support `__ to learn more. +Visit :ref:`display_multi_display_support` to learn more. + +.. _objects_parts: Parts ***** The widgets are built from multiple parts. For example a -`Base object `__ uses the main and scrollbar parts but a -`Slider `__ uses the main, indicator and knob parts. +:ref:`Base object ` uses the main and scrollbar parts but a +:ref:`Slider ` uses the main, indicator and knob parts. Parts are similar to *pseudo-elements* in CSS. The following predefined parts exist in LVGL: @@ -265,7 +277,9 @@ The following predefined parts exist in LVGL: The main purpose of parts is to allow styling the "components" of the widgets. They are described in more detail in the -`Style overview `__ section. +:ref:`Style overview ` section. + +.. _objects_states: States ****** @@ -295,13 +309,17 @@ values can be used as well. E.g. :cpp:expr:`lv_obj_add_state(obj, part, LV_STATE_PRESSED | LV_PRESSED_CHECKED)`. To learn more about the states read the related section of the -`Style overview `__. +:ref:`Style overview `. + +.. _objects_snapshot: Snapshot ******** A snapshot image can be generated for an object together with its -children. Check details in `Snapshot `__. +children. Check details in :ref:`snapshot`. + +.. _objects_api: API *** diff --git a/docs/overview/profiler.rst b/docs/overview/profiler.rst index 2385de9c7..503eaec05 100644 --- a/docs/overview/profiler.rst +++ b/docs/overview/profiler.rst @@ -8,6 +8,8 @@ As the complexity of the application increases, performance issues such as low F causing lag may arise. LVGL has internally set up some hooks for performance measurement to help developers analyze and locate performance issues. +.. _profiler_introduction: + Introduction ************ @@ -20,6 +22,8 @@ When the buffer is full, the trace system prints the log information through the The output trace logs are formatted according to Android's `systrace `_ format and can be visualized using `Perfetto `_. +.. _profiler_usage: + Usage ***** @@ -162,6 +166,8 @@ Users can add their own measured functions: LV_PROFILER_END_TAG("do_something_2"); } +.. _profiler_custom_implementation: + Custom profiler implementation ****************************** @@ -184,6 +190,8 @@ Taking `NuttX `_ RTOS as an example: #define LV_PROFILER_BEGIN_TAG(str) sched_note_beginex(NOTE_TAG_ALWAYS, str) #define LV_PROFILER_END_TAG(str) sched_note_endex(NOTE_TAG_ALWAYS, str) +.. _profiler_faq: + FAQ *** diff --git a/docs/overview/scroll.rst b/docs/overview/scroll.rst index 862ce4fc4..9141f12d6 100644 --- a/docs/overview/scroll.rst +++ b/docs/overview/scroll.rst @@ -1,3 +1,5 @@ +.. _scroll: + ====== Scroll ====== @@ -9,8 +11,8 @@ In LVGL scrolling works very intuitively: if an object is outside its parent content area (the size without padding), the parent becomes scrollable and scrollbar(s) will appear. That's it. -Any object can be scrollable including ``lv_obj_t``, ``lv_img``, -``lv_btn``, ``lv_meter``, etc +Any object can be scrollable including ``lv_obj``, ``lv_image``, +``lv_button``, ``lv_meter``, etc The object can either be scrolled horizontally or vertically in one stroke; diagonal scrolling is not possible. @@ -73,6 +75,8 @@ base direction. ``pad_left/right/top/bottom`` sets the spacing around the scrollbars and ``width`` sets the scrollbar's width. +.. _scroll_events: + Events ------ @@ -103,9 +107,10 @@ It's possible to make an object non-scrollable with Non-scrollable objects can still propagate the scrolling (chain) to their parents. -The direction in which scrolling happens can be controlled by -``lv_obj_set_scroll_dir(obj, LV_DIR_...)``. The following values are -possible for the direction: +The direction in which scrolling happens can be controlled by ``lv_obj_set_scroll_dir(obj, LV_DIR_...)``. + +The following values are possible for the direction: + - :cpp:enumerator:`LV_DIR_TOP`: only scroll up - :cpp:enumerator:`LV_DIR_LEFT`: only scroll left - :cpp:enumerator:`LV_DIR_BOTTOM`: only scroll down @@ -272,10 +277,14 @@ an object. Here is an example to see how to handle the event: } } +.. _scroll_example: + Examples ******** .. include:: ../examples/scroll/index.rst +.. _scroll_api: + API *** diff --git a/docs/overview/style-props.rst b/docs/overview/style-props.rst index fde9d0f21..d005486a8 100644 --- a/docs/overview/style-props.rst +++ b/docs/overview/style-props.rst @@ -1,3 +1,5 @@ +.. _style_properties: + ================ Style properties ================ diff --git a/docs/overview/style.rst b/docs/overview/style.rst index ec1914c64..0ab70224f 100644 --- a/docs/overview/style.rst +++ b/docs/overview/style.rst @@ -29,6 +29,8 @@ border width, text color and so on. It's similar to a ``class`` in CSS. in LVGL a property is assigned to a given state. - Transitions can be applied when the object changes state. +.. _styles_states: + States ****** @@ -107,6 +109,8 @@ Some practical notes: Instead, for example, use the background color for pressed and checked states and indicate the focused state with a different border color. +.. _styles_cascading: + Cascading styles **************** @@ -134,6 +138,8 @@ style (red). When the button is pressed the light-gray color is a better match because it describes the current state perfectly, so the button will be light-gray. +.. _styles_inheritance: + Inheritance *********** @@ -146,6 +152,8 @@ property. The parents will use their own state to determine the value. So if a button is pressed, and the text color comes from here, the pressed text color will be used. +.. _styles_parts: + Parts ***** @@ -162,7 +170,7 @@ The following predefined parts exist in LVGL: - :cpp:enumerator:`LV_PART_CURSOR`: Mark a specific place e.g. text area's or chart's cursor - :cpp:enumerator:`LV_PART_CUSTOM_FIRST`: Custom part identifiers can be added starting from here. -For example a `Slider `__ has three parts: +For example a :ref:`Slider ` has three parts: - Background - Indicator @@ -171,6 +179,8 @@ For example a `Slider `__ has three parts: This means all three parts of the slider can have their own styles. See later how to add styles to objects and parts. +.. _styles_initialize: + Initialize styles and set/get properties **************************************** @@ -241,6 +251,8 @@ Styles can be built as ``const`` too to save RAM: Later ``const`` style can be used like any other style but (obviously) new properties can not be added. +.. _styles_add_remove: + Add and remove styles to a widget ********************************* @@ -333,6 +345,8 @@ To get a final value of property lv_color_t color = lv_obj_get_style_bg_color(btn, LV_PART_MAIN); +.. _styles_local: + Local styles ************ @@ -355,13 +369,13 @@ To set a local property use functions like lv_obj_set_style_bg_color(slider, lv_color_red(), LV_PART_INDICATOR | LV_STATE_FOCUSED); -.. _style_properties: +.. _styles_properties: Properties ********** For the full list of style properties click -`here `__. +:ref:`here `. Typical background properties ----------------------------- @@ -378,6 +392,8 @@ background properties" are the ones related to: - Width and height transformation - X and Y translation +.. _styles_transitions: + Transitions *********** @@ -419,6 +435,8 @@ initialized and added to a style: lv_style_set_transition(&style1, &trans1); +.. _styles_opacity_blend_modes_transformations: + Opacity, Blend modes and Transformations **************************************** @@ -452,11 +470,15 @@ if it has radius, ``bg_opa != 255``, has shadow, outline, etc. The click area of the widget is also transformed accordingly. +.. _styles_color_filter: + Color filter ************ TODO +.. _styles_themes: + Themes ****** @@ -502,10 +524,14 @@ E.g. default theme -> custom theme -> dark theme. There is an example for it below. +.. _styles_example: + Examples ******** .. include:: ../examples/styles/index.rst +.. _styles_api: + API *** diff --git a/docs/overview/timer.rst b/docs/overview/timer.rst index f8427ad28..0e8b12db2 100644 --- a/docs/overview/timer.rst +++ b/docs/overview/timer.rst @@ -1,3 +1,5 @@ +.. _timer: + ====== Timers ====== @@ -35,7 +37,7 @@ For example: /*Do something with LVGL*/ if(something_happened) { something_happened = false; - lv_btn_create(lv_screen_active(), NULL); + lv_button_create(lv_screen_active(), NULL); } } @@ -138,5 +140,7 @@ If you just want to delete an object and don't need to clean anything up in ``my_screen_cleanup`` you could just use :cpp:func:`lv_obj_delete_async` which will delete the object on the next call to :cpp:func:`lv_timer_handler`. +.. _timer_api: + API *** diff --git a/docs/porting/disp.rst b/docs/porting/display.rst similarity index 98% rename from docs/porting/disp.rst rename to docs/porting/display.rst index 91516be76..b89dd5f69 100644 --- a/docs/porting/disp.rst +++ b/docs/porting/display.rst @@ -260,9 +260,9 @@ Further reading - `lv_port_disp_template.c `__ for a template for your own driver. -- `Drawing `__ to learn more about how rendering +- :ref:`Drawing ` to learn more about how rendering works in LVGL. -- `Display features `__ to learn more about higher +- :ref:`display_features` to learn more about higher level display features. API diff --git a/docs/porting/indev.rst b/docs/porting/indev.rst index a751a898b..cf2e0af3b 100644 --- a/docs/porting/indev.rst +++ b/docs/porting/indev.rst @@ -1,3 +1,5 @@ +.. _porting_indev: + ====================== Input device interface ====================== @@ -24,7 +26,7 @@ The ``type`` member can be: ``read_cb`` is a function pointer which will be called periodically to report the current state of an input device. -Visit `Input devices `__ to learn more about input +Visit :ref:`Input devices ` to learn more about input devices in general. Touchpad, mouse or any pointer @@ -187,6 +189,8 @@ should look like ``const lv_point_t points_array[] = { {12,30},{60,90}, ...}`` When the ``button_read`` callback in the example above changes the ``data->btn_id`` to ``0`` a press/release action at the first index of the ``points_array`` will be performed (``{12,30}``). +.. _porting_indev_other_features: + Other features ************** @@ -258,7 +262,7 @@ Further reading *************** - `lv_port_indev_template.c `__ for a template for your own driver. -- `INdev features `__ to learn more about higher level input device features. +- `INdev features ` to learn more about higher level input device features. API *** diff --git a/docs/porting/index.rst b/docs/porting/index.rst index 24db95fdb..787089bb0 100644 --- a/docs/porting/index.rst +++ b/docs/porting/index.rst @@ -9,7 +9,7 @@ Porting :maxdepth: 2 project - disp + display indev tick timer_handler diff --git a/docs/porting/os.rst b/docs/porting/os.rst index c9c2d1741..6d1908484 100644 --- a/docs/porting/os.rst +++ b/docs/porting/os.rst @@ -8,7 +8,7 @@ LVGL is **not thread-safe** by default. However, in the following conditions it's valid to call LVGL related functions: - In *events*. Learn more in :ref:`events`. - -In *lv_timer*. Learn more in `Timers `__. +In *lv_timer*. Learn more in :ref:`timer`. Tasks and threads ----------------- diff --git a/docs/porting/project.rst b/docs/porting/project.rst index c14c7915a..2ad070622 100644 --- a/docs/porting/project.rst +++ b/docs/porting/project.rst @@ -127,7 +127,7 @@ Initialization To use the graphics library you have to initialize it and setup required components. The order of the initialization is: -1. Call :cpp:func:`lv_init()`. +1. Call :cpp:func:`lv_init`. 2. Initialize your drivers. 3. Register the display and input devices drivers in LVGL. Learn more about `Display `__ and `Input diff --git a/docs/porting/timer_handler.rst b/docs/porting/timer_handler.rst index 56c896756..1a40a62f7 100644 --- a/docs/porting/timer_handler.rst +++ b/docs/porting/timer_handler.rst @@ -52,7 +52,7 @@ In an OS environment, you can use it together with the **delay** or os_delay_ms(time_till_next); /* delay to avoid unnecessary polling */ } -To learn more about timers visit the `Timer `__ +To learn more about timers visit the :ref:`timer` section. API diff --git a/docs/widgets/animimg.rst b/docs/widgets/animimg.rst index 781ede3f1..b6c47650c 100644 --- a/docs/widgets/animimg.rst +++ b/docs/widgets/animimg.rst @@ -1,3 +1,6 @@ +.. _lv_animimg: + +============================ Animation Image (lv_animimg) ============================ @@ -10,6 +13,8 @@ multiple source images. You can specify a duration and repeat count. +.. _lv_animimg_parts_and_styles: + Parts and Styles **************** @@ -17,6 +22,8 @@ Parts and Styles background style properties and the image itself using the image style properties. +.. _lv_animimg_usage: + Usage ***** @@ -26,6 +33,8 @@ Image sources To set the image in a state, use the :cpp:expr:`lv_animimg_set_src(imagebutton, dsc[], num)`. +.. _lv_animimg_events: + Events ****** @@ -35,6 +44,8 @@ See the events of the Base object too. Learn more about :ref:`events`. +.. _lv_animimg_keys: + Keys **** @@ -42,11 +53,15 @@ No Keys are processed by the object type. Learn more about :ref:`indev_keys`. +.. _lv_animimg_example: + Example ******* .. include:: ../examples/widgets/animimg/index.rst +.. _lv_animimg_api: + API *** diff --git a/docs/widgets/arc.rst b/docs/widgets/arc.rst index 689e332ce..cfb332ffc 100644 --- a/docs/widgets/arc.rst +++ b/docs/widgets/arc.rst @@ -1,3 +1,6 @@ +.. _lv_arc: + +============ Arc (lv_arc) ============ @@ -7,6 +10,8 @@ Overview The Arc consists of a background and a foreground arc. The foreground (indicator) can be touch-adjusted. +.. _lv_arc_parts_and_styles: + Parts and Styles **************** @@ -21,6 +26,8 @@ Parts and Styles size is the same as the indicator's width. Larger padding makes it larger, smaller padding makes it smaller. +.. _lv_arc_usage: + Usage ***** @@ -120,6 +127,8 @@ used to rotate the object to the current value of the arc. It's a typical use case to call these functions in the ``VALUE_CHANGED`` event of the arc. +.. _lv_arc_events: + Events ****** @@ -152,6 +161,8 @@ See the events of the `Base object `__ too. Learn more about :ref:`events`. +.. _lv_arc_keys: + Keys **** @@ -160,11 +171,15 @@ Keys Learn more about :ref:`indev_keys`. +.. _lv_arc_example: + Example ******* .. include:: ../examples/widgets/arc/index.rst +.. _lv_arc_api: + API *** diff --git a/docs/widgets/bar.rst b/docs/widgets/bar.rst index fa6332479..a91553446 100644 --- a/docs/widgets/bar.rst +++ b/docs/widgets/bar.rst @@ -1,3 +1,6 @@ +.. _lv_bar: + +============ Bar (lv_bar) ============ @@ -13,6 +16,8 @@ its height. Not only the end, but also the start value of the bar can be set, which changes the start position of the indicator. +.. _lv_bar_parts_and_styles: + Parts and Styles **************** @@ -23,6 +28,8 @@ Parts and Styles - :cpp:enumerator:`LV_PART_INDICATOR` The indicator itself; also uses all the typical background properties. +.. _lv_bar_usage: + Usage ***** @@ -52,12 +59,16 @@ The bar can be one of the following modes: ``lv_bar_set_start_value(bar, new_value, LV_ANIM_ON/OFF)``. The start value always has to be smaller than the end value. +.. _lv_bar_events: + Events ****** See the events of the `Base object `__ too. Learn more about :ref:`events`. +.. _lv_bar_keys: + Keys **** @@ -65,11 +76,15 @@ No *Keys* are processed by the object type. Learn more about :ref:`indev_keys`. +.. _lv_bar_example: + Example ******* .. include:: ../examples/widgets/bar/index.rst +.. _lv_bar_api: + API *** diff --git a/docs/widgets/button.rst b/docs/widgets/button.rst index 6ad1f003b..9ff241139 100644 --- a/docs/widgets/button.rst +++ b/docs/widgets/button.rst @@ -1,27 +1,35 @@ +.. _lv_button: + +================== Button (lv_button) -=============== +================== Overview ******** -Buttons have no new features compared to the `Base -object `__. They are useful for semantic purposes and have +Buttons have no new features compared to the :ref:`Base object `__. They are useful for semantic purposes and have slightly different default settings. Buttons, by default, differ from Base object in the following ways: - Not scrollable - Added to the default group - Default height and width set to :cpp:enumerator:`LV_SIZE_CONTENT` +.. _lv_button_parts_and_styles: + Parts and Styles **************** - :cpp:enumerator:`LV_PART_MAIN` The background of the button. Uses the typical background style properties. +.. _lv_button_usage: + Usage ***** -There are no new features compared to `Base object `__. +There are no new features compared to :ref:`Base object `. + +.. _lv_button_events: Events ****** @@ -32,6 +40,8 @@ Events Learn more about :ref:`events`. +.. _lv_button_keys: + Keys **** @@ -39,14 +49,18 @@ Note that the state of :cpp:enumerator:`LV_KEY_ENTER` is translated to :cpp:enumerator:`LV_EVENT_PRESSED`, :cpp:enumerator:`LV_EVENT_PRESSING` and :cpp:enumerator:`LV_EVENT_RELEASED` etc. -See the events of the `Base object `__ too. +See the events of the :ref:`Base object ` too. Learn more about :ref:`indev_keys`. +.. _lv_button_example: + Example ******* .. include:: ../examples/widgets/button/index.rst +.. _lv_button_api: + API *** diff --git a/docs/widgets/butttonmatrix.rst b/docs/widgets/buttonmatrix.rst similarity index 95% rename from docs/widgets/butttonmatrix.rst rename to docs/widgets/buttonmatrix.rst index 7014dd818..4d9094e64 100644 --- a/docs/widgets/butttonmatrix.rst +++ b/docs/widgets/buttonmatrix.rst @@ -1,5 +1,8 @@ +.. _lv_buttonmatrix: + +=============================== Button matrix (lv_buttonmatrix) -============================ +=============================== Overview ******** @@ -15,6 +18,8 @@ The Button matrix is added to the default group (if one is set). Besides the Button matrix is an editable object to allow selecting and clicking the buttons with encoder navigation too. +.. _lv_buttonmatrix_parts_and_styles: + Parts and Styles **************** @@ -24,6 +29,8 @@ Parts and Styles - :cpp:enumerator:`LV_PART_ITEMS` The buttons all use the text and typical background style properties except translations and transformations. +.. _lv_buttonmatrix_usage: + Usage ***** @@ -94,6 +101,8 @@ The "One check" feature can be enabled with :cpp:expr:`lv_buttonmatrix_set_one_checked(buttonm, true)` to allow only one button to be checked at a time. +.. _lv_buttonmatrix_events: + Events ****** @@ -112,6 +121,8 @@ text of ``button_id``\ th button. Learn more about :ref:`events`. +.. _lv_buttonmatrix_keys: + Keys **** @@ -129,10 +140,14 @@ won't be activated. Learn more about :ref:`indev_keys`. +.. _lv_buttonmatrix_example: + Example ******* .. include:: ../examples/widgets/buttonmatrix/index.rst +.. _lv_buttonmatrix_api: + API *** diff --git a/docs/widgets/calendar.rst b/docs/widgets/calendar.rst index b24b949ea..76c53f525 100644 --- a/docs/widgets/calendar.rst +++ b/docs/widgets/calendar.rst @@ -1,3 +1,6 @@ +.. _lv_calendar: + +====================== Calendar (lv_calendar) ====================== @@ -16,10 +19,12 @@ To make the Calendar flexible, by default it doesn't show the current year or month. Instead, there are optional "headers" that can be attached to the calendar. +.. _lv_calendar_parts_and_styles: + Parts and Styles **************** -The calendar object uses the `Button matrix `__ +The calendar object uses the `Button matrix `__ object under the hood to arrange the days into a matrix. - :cpp:enumerator:`LV_PART_MAIN` The background of the calendar. Uses all the background related style properties. @@ -27,9 +32,11 @@ object under the hood to arrange the days into a matrix. buttons and a custom drawer event is added modify the properties of the buttons as follows: - day names have no border, no background and drawn with a gray color - - days of the previous and next month have :cpp:enumerator:`LV_BTNMATRIX_CTRL_DISABLED` flag + - days of the previous and next month have :cpp:enumerator:`LV_BUTTONMATRIX_CTRL_DISABLED` flag - today has a thicker border with the theme's primary color - highlighted days have some opacity with the theme's primary color. +.. _lv_calendar_usage: + Usage ***** @@ -67,6 +74,8 @@ looks like ``const char * day_names[7] = {"Su", "Mo", ...};`` Only the pointer of the day names is saved so the elements should be static, global or constant variables. +.. _lv_calendar_events: + Events ****** @@ -77,6 +86,8 @@ Events Learn more about :ref:`events`. +.. _lv_calendar_keys: + Keys **** @@ -85,6 +96,8 @@ Keys Learn more about :ref:`indev_keys`. +.. _lv_calendar_header: + Headers ******* @@ -104,10 +117,14 @@ Drop-down :cpp:expr:`lv_calendar_header_dropdown_create(calendar)` creates a header that contains 2 drop-drown lists: one for the year and another for the month. +.. _lv_calendar_example: + Example ******* .. include:: ../examples/widgets/calendar/index.rst +.. _lv_calendar_api: + API *** diff --git a/docs/widgets/canvas.rst b/docs/widgets/canvas.rst index 0cb3beffd..6a998cd5a 100644 --- a/docs/widgets/canvas.rst +++ b/docs/widgets/canvas.rst @@ -1,19 +1,26 @@ +.. _lv_canvas: + +================== Canvas (lv_canvas) ================== Overview ******** -A Canvas inherits from `Image `__ where the user can draw +A Canvas inherits from :ref:`Image ` where the user can draw anything. Rectangles, texts, images, lines, arcs can be drawn here using lvgl's drawing engine. +.. _lv_canvas_parts_and_styles: + Parts and Styles **************** :cpp:enumerator:`LV_PART_MAIN` Uses the typical rectangle style properties and image style properties. +.. _lv_canvas_usage: + Usage ***** @@ -32,8 +39,7 @@ Or you can use The canvas supports all the color formats like :cpp:enumerator:`LV_COLOR_FORMAT_ARGB8888` or :cpp:enumerator:`LV_COLOR_FORMAT_I2`. See the full -list in the `Color formats `__ -section. +list in the :ref:`Color formats ` section. Indexed colors -------------- @@ -67,6 +73,7 @@ The draw function can draw to any color format to which LVGL can render. Typical :cpp:enumerator:`LV_COLOR_FORMAT_RGB565`, :cpp:enumerator:`LV_COLOR_FORMAT_RGB888`, :cpp:enumerator:`LV_COLOR_FORMAT_XRGB888`, and :cpp:enumerator:`LV_COLOR_FORMAT_ARGB8888`. +.. _lv_canvas_events: Events ****** @@ -74,10 +81,12 @@ Events No special events are sent by canvas objects. The same events are sent as for the -See the events of the `Images `__ too. +See the events of the :ref:`lv_image` too. Learn more about :ref:`events`. +.. _lv_canvas_keys: + Keys **** @@ -85,10 +94,14 @@ No *Keys* are processed by the object type. Learn more about :ref:`indev_keys`. +.. _lv_canvas_example: + Example ******* .. include:: ../examples/widgets/canvas/index.rst +.. _lv_canvas_api: + API *** diff --git a/docs/widgets/chart.rst b/docs/widgets/chart.rst index dd0872d4c..623506a8d 100644 --- a/docs/widgets/chart.rst +++ b/docs/widgets/chart.rst @@ -1,3 +1,6 @@ +.. _lv_chart: + +================ Chart (lv_chart) ================ @@ -11,6 +14,8 @@ charts are supported. Charts can have: - division lines - 2 y axis - axis ticks and texts on ticks - cursors - scrolling and zooming +.. _lv_chart_parts_and_styles: + Parts and Styles **************** @@ -36,6 +41,8 @@ Parts and Styles ``width``, ``height``, ``bg_color`` and ``radius`` are used to set the appearance of points. +.. _lv_chart_usage: + Usage ***** @@ -166,7 +173,7 @@ Note that :cpp:enumerator:`LV_CHART_UPDATE_MODE_SHIFT` also changes the Tick marks and labels --------------------- -With the help of `__ vertical and horizontal scales can be added in a very flexible way. +With the help of `Scale `__, vertical and horizontal scales can be added in a very flexible way. See the example below to learn more. Zoom @@ -195,6 +202,8 @@ point. the cursor at a point. If the point's position changes (new value or scrolling) the cursor will move with the point. +.. _lv_chart_events: + Events ****** @@ -206,6 +215,8 @@ See the events of the `Base object `__ too. Learn more about :ref:`events`. +.. _lv_chart_keys: + Keys **** @@ -213,10 +224,14 @@ No *Keys* are processed by the object type. Learn more about :ref:`indev_keys`. +.. _lv_chart_example: + Example ******* .. include:: ../examples/widgets/chart/index.rst +.. _lv_chart_api: + API *** diff --git a/docs/widgets/checkbox.rst b/docs/widgets/checkbox.rst index 5c09a5a1d..dfbb64f28 100644 --- a/docs/widgets/checkbox.rst +++ b/docs/widgets/checkbox.rst @@ -1,3 +1,6 @@ +.. _lv_checkbox: + +====================== Checkbox (lv_checkbox) ====================== @@ -7,6 +10,8 @@ Overview The Checkbox object is created from a "tick box" and a label. When the Checkbox is clicked the tick box is toggled. +.. _lv_checkbox_parts_and_styles: + Parts and Styles **************** @@ -20,6 +25,8 @@ Parts and Styles The Checkbox is added to the default group (if it is set). +.. _lv_checkbox_usage: + Usage ***** @@ -49,6 +56,8 @@ common state add/clear function: To get whether the checkbox is checked or not use: :cpp:expr:`lv_obj_has_state(cb, LV_STATE_CHECKED)`. +.. _lv_checkbox_events: + Events ****** @@ -58,6 +67,8 @@ See the events of the `Base object `__ too. Learn more about :ref:`events`. +.. _lv_checkbox_keys: + Keys **** @@ -71,10 +82,14 @@ Note that, as usual, the state of :cpp:enumerator:`LV_KEY_ENTER` is translated t Learn more about :ref:`indev_keys`. +.. _lv_checkbox_example: + Example ******* .. include:: ../examples/widgets/checkbox/index.rst +.. _lv_checkboxapi: + API *** diff --git a/docs/widgets/dropdown.rst b/docs/widgets/dropdown.rst index b9c8d3a40..2954f75ff 100644 --- a/docs/widgets/dropdown.rst +++ b/docs/widgets/dropdown.rst @@ -1,3 +1,6 @@ +.. _lv_dropdown: + +============================ Drop-down list (lv_dropdown) ============================ @@ -15,6 +18,8 @@ The Drop-down list is added to the default group (if it is set). Besides the Drop-down list is an editable object to allow selecting an option with encoder navigation too. +.. _lv_dropdown_parts_and_styles: + Parts and Styles **************** @@ -53,9 +58,13 @@ The list is hidden/shown on open/close. To add styles to it use Alternatively the theme can be extended with the new styles. +.. _lv_dropdown_usage: + Usage ***** +.. _lv_dropdown_options: + Options ******* @@ -121,6 +130,8 @@ Manually open/close To manually open or close the drop-down list the ``lv_dropdown_open/close(dropdown)`` function can be used. +.. _lv_dropdown_events: + Events ****** @@ -136,6 +147,8 @@ See the events of the `Base object `__ too. Learn more about :ref:`events`. +.. _lv_dropdown_keys: + Keys **** @@ -146,10 +159,14 @@ Keys Learn more about :ref:`indev_keys`. +.. _lv_dropdown_example: + Example ******* .. include:: ../examples/widgets/dropdown/index.rst +.. _lv_dropdown_api: + API *** diff --git a/docs/widgets/image.rst b/docs/widgets/image.rst index a6251867c..bcf96d7d6 100644 --- a/docs/widgets/image.rst +++ b/docs/widgets/image.rst @@ -1,5 +1,8 @@ +.. _lv_image: + +================ Image (lv_image) -============== +================ Overview ******** @@ -7,9 +10,11 @@ Overview Images are the basic object to display images from flash (as arrays) or from files. Images can display symbols (``LV_SYMBOL_...``) too. -Using the `Image decoder interface `__ custom image formats +Using the :ref:`Image decoder interface ` custom image formats can be supported as well. +.. _lv_image_parts_and_styles: + Parts and Styles **************** @@ -17,6 +22,8 @@ Parts and Styles background style properties and the image itself using the image style properties. +.. _lv_image_usage: + Usage ***** @@ -27,7 +34,7 @@ To provide maximum flexibility, the source of the image can be: - a variable in code (a C array with the pixels). - a file stored externally (e.g. on an SD card). -- a text with `Symbols `__. +- a text with :ref:`Symbols `. To set the source of an image, use :cpp:expr:`lv_image_set_src(img, src)`. @@ -40,10 +47,10 @@ To use external files, you also need to convert the image files using the online converter tool but now you should select the binary output format. You also need to use LVGL's file system module and register a driver with some functions for the basic file operation. Go to the -`File system `__ to learn more. To set an image sourced +:ref:`File system ` to learn more. To set an image sourced from a file, use :cpp:expr:`lv_image_set_src(img, "S:folder1/my_img.bin")`. -You can also set a symbol similarly to `Labels `__. In +You can also set a symbol similarly to :ref:`Labels `. In this case, the image will be rendered as text according to the *font* specified in the style. It enables to use of light-weight monochrome "letters" instead of real images. You can set symbol like @@ -77,7 +84,7 @@ supported: - **Alpha indexed**: Only alpha values are stored. These options can be selected in the image converter. To learn more -about the color formats, read the `Images `__ section. +about the color formats, read the :ref:`Images ` section. Recolor ------- @@ -99,7 +106,7 @@ With :cpp:expr:`lv_image_set_offset_x(img, x_ofs)` and :cpp:expr:`lv_image_set_offset_y(img, y_ofs)`, you can add some offset to the displayed image. Useful if the object size is smaller than the image source size. Using the offset parameter a `Texture atlas `__ -or a "running image" effect can be created by `Animating `__ the x or y offset. +or a "running image" effect can be created by :ref:`Animating ` the x or y offset. Transformations --------------- @@ -128,7 +135,7 @@ the transformations are higher quality but slower. The transformations require the whole image to be available. Therefore indexed images (``LV_COLOR_FORMAT_I1/2/4/8_...``), alpha only images cannot be transformed. In other words transformations work only on normal (A)RGB or A8 images stored as -C array, or if a custom `Image decoder `__ +C array, or if a custom :ref:`Image decoder ` returns the whole image. Note that the real coordinates of image objects won't change during @@ -137,7 +144,7 @@ the original, non-zoomed coordinates. **IMPORTANT** The transformation of the image is independent of the transformation properties coming from styles. (See -`here `__). The main +:ref:`here `). The main differences are that pure image widget transformation - doesn't transform the children of the image widget @@ -172,15 +179,19 @@ Or to automatically scale or tile the image The alignment can be set by :cpp:func:`lv_image_set_align(image, align)` +.. _lv_image_events: + Events ****** No special events are sent by image objects. -See the events of the `Base object `__ too. +See the events of the :ref:`Base object ` too. Learn more about :ref:`events`. +.. _lv_image_keys: + Keys **** @@ -188,10 +199,14 @@ No *Keys* are processed by the object type. Learn more about :ref:`indev_keys`. +.. _lv_image_example: + Example ******* -.. include:: ../examples/widgets/img/index.rst +.. include:: ../examples/widgets/image/index.rst + +.. _lv_image_api: API *** diff --git a/docs/widgets/imagebutton.rst b/docs/widgets/imagebutton.rst index 9a9e4eda1..60cc4335b 100644 --- a/docs/widgets/imagebutton.rst +++ b/docs/widgets/imagebutton.rst @@ -1,5 +1,8 @@ +.. _lv_imagebutton: + +============================= Image button (lv_imagebutton) -======================== +============================= Overview ******** @@ -11,6 +14,8 @@ of drawing a rectangle. You can set a left, right and center image, and the center image will be repeated to match the width of the object. +.. _lv_imagebutton_parts_and_styles: + Parts and Styles **************** @@ -18,6 +23,8 @@ Parts and Styles properties are used, a rectangle will be drawn behind the image button. +.. _lv_imagebutton_usage: + Usage ***** @@ -27,7 +34,7 @@ Image sources To set the image in a state, use the :cpp:expr:`lv_imagebutton_set_src(imagebutton, LV_IMAGEBUTTON_STATE_..., src_left, src_center, src_right)`. -The image sources work the same as described in the `Image object `__ +The image sources work the same as described in the `Image object `__ except that "Symbols" are not supported by the Image button. Any of the sources can ``NULL``. The possible states are: @@ -46,10 +53,12 @@ they will be used in pressed state instead of the released images. States ------ -Instead of the regular ``lv_obj_add/remove_state()`` functions the -:cpp:expr:`lv_imagebutton_set_state(imagebutton, LV_IMAGEBUTTON_STATE_...)` functions should be +Instead of the regular :cpp:func:`lv_obj_add_state`and :cpp:func:`lv_obj_remove_state` functions, +the :cpp:expr:`lv_imagebutton_set_state(imagebutton, LV_IMAGEBUTTON_STATE_...)` function should be used to manually set a state. +.. _lv_imagebutton_events: + Events ****** @@ -57,6 +66,8 @@ Events Learn more about :ref:`events`. +.. _lv_imagebutton_keys: + Keys **** @@ -68,10 +79,14 @@ Keys Learn more about :ref:`indev_keys`. +.. _lv_imagebutton_example: + Example ******* -.. include:: ../examples/widgets/imgagebutton/index.rst +.. include:: ../examples/widgets/imagebutton/index.rst + +.. _lv_imagebutton_api: API *** diff --git a/docs/widgets/keyboard.rst b/docs/widgets/keyboard.rst index c66df206f..a72e04399 100644 --- a/docs/widgets/keyboard.rst +++ b/docs/widgets/keyboard.rst @@ -1,12 +1,17 @@ +.. _lv_keyboard: + +====================== Keyboard (lv_keyboard) ====================== Overview ******** -The Keyboard object is a special `Button matrix `__ +The Keyboard object is a special :ref:`Button matrix ` with predefined keymaps and other features to realize a virtual keyboard -to write texts into a `Text area `__. +to write texts into a :ref:`Text area `. + +.. _lv_keyboard_parts_and_styles: Parts and Styles **************** @@ -16,6 +21,8 @@ Similarly to Button matrices Keyboards consist of 2 part: - :cpp:enumerator:`LV_PART_MAIN` The main part. Uses all the typical background properties - :cpp:enumerator:`LV_PART_ITEMS` The buttons. Also uses all typical background properties as well as the *text* properties. +.. _lv_keyboard_usage: + Usage ***** @@ -38,7 +45,7 @@ default mode is :cpp:enumerator:`LV_KEYBOARD_MODE_TEXT_UPPER`. Assign Text area ---------------- -You can assign a `Text area `__ to the Keyboard to +You can assign a :ref:`Text area ` to the Keyboard to automatically put the clicked characters there. To assign the text area, use :cpp:expr:`lv_keyboard_set_textarea(kb, ta)`. @@ -65,7 +72,7 @@ New Keymap You can specify a new map (layout) for the keyboard with :cpp:expr:`lv_keyboard_set_map(kb, LV_KEYBOARD_MODE_..., kb_map, kb_ctrl)`. See -the `Button matrix `__ for more information about +the :ref:`Button matrix ` for more information about creating new maps and ctrls. Keep in mind that using following keywords will have the same effect as @@ -81,6 +88,8 @@ with the original map: - *"abc"* Load the lower case map. - *"1#"* Load the lower case map. +.. _lv_keyboard_events: + Events ****** @@ -101,6 +110,8 @@ with a custom event handler if you wish. Learn more about :ref:`events`. +.. _lv_keyboard_keys: + Keys **** @@ -110,10 +121,14 @@ Keys Learn more about :ref:`indev_keys`. -Examples -******** +.. _lv_keyboard_example: + +Example +******* .. include:: ../examples/widgets/keyboard/index.rst +.. _lv_keyboard_api: + API *** diff --git a/docs/widgets/label.rst b/docs/widgets/label.rst index d199e73c4..e30d452b4 100644 --- a/docs/widgets/label.rst +++ b/docs/widgets/label.rst @@ -1,3 +1,6 @@ +.. _lv_label: + +================ Label (lv_label) ================ @@ -6,6 +9,8 @@ Overview A label is the basic object type that is used to display text. +.. _lv_label_parts_and_styles: + Parts and Styles **************** @@ -18,6 +23,8 @@ Parts and Styles text <#text-selection>`__. Only ``text_color`` and ``bg_color`` style properties can be used. +.. _lv_label_usage: + Usage ***** @@ -42,6 +49,8 @@ safe to use with :cpp:func:`lv_label_set_text_static` (except when used with :cpp:enumerator:`LV_LABEL_LONG_DOT`, as it modifies the buffer in-place), as they are stored in ROM memory, which is always accessible. +.. _lv_label_newline: + Newline ------- @@ -49,6 +58,8 @@ Newline characters are handled automatically by the label object. You can use ``\n`` to make a line break. For example: ``"line1\nline2\n\nline4"`` +.. _lv_label_long_modes: + Long modes ---------- @@ -79,12 +90,7 @@ this implementation detail is unnoticed. This is not the case with :cpp:func:`lv_label_set_text_static` must be writable if you plan to use :cpp:enumerator:`LV_LABEL_LONG_DOT`. -Text recolor ------------- - -In the text, you can use commands to recolor parts of the text. For -example: ``"Write a #ff0000 red# word"``. This feature can be enabled -individually for each label by :cpp:func:`lv_label_set_recolor` function. +.. _lv_label_text_selection: Text selection -------------- @@ -92,22 +98,25 @@ Text selection If enabled by :c:macro:`LV_LABEL_TEXT_SELECTION` part of the text can be selected. It's similar to when you use your mouse on a PC to select a text. The whole mechanism (click and select the text as you drag your -finger/mouse) is implemented in `Text area `__ and +finger/mouse) is implemented in :ref:`Text area ` and the Label widget only allows manual text selection with :cpp:expr:`lv_label_get_text_selection_start(label, start_char_index)` and :cpp:expr:`lv_label_get_text_selection_start(label, end_char_index)`. +.. _lv_label_text_alignment: Text alignment -------------- To horizontally align the lines of a label the `text_align` style property can be used with -:cpp:expr:`lv_obj_set_style_text_align()` or :cpp:expr:`lv_style_set_text_align()` +:cpp:func:`lv_obj_set_style_text_align` or :cpp:func:`lv_style_set_text_align` Note that it has a visible effect only if - the label widget's width is larger than the width of the longest line of the text - the text has multiple lines with non equal line length +.. _lv_label_very_long_texts: + Very long texts --------------- @@ -115,6 +124,8 @@ LVGL can efficiently handle very long (e.g. > 40k characters) labels by saving some extra data (~12 bytes) to speed up drawing. To enable this feature, set ``LV_LABEL_LONG_TXT_HINT 1`` in ``lv_conf.h``. +.. _lv_label_custom_scrolling_animations: + Custom scrolling animations --------------------------- @@ -124,21 +135,27 @@ customized by setting the animation property of a style, using :cpp:func:`lv_style_set_anim`. It will be treated as a template which will be used to create the scroll animatins. +.. _lv_label_symbols: + Symbols ------- The labels can display symbols alongside letters (or on their own). Read -the `Font `__ section to learn more about the symbols. +the :ref:`fonts` section to learn more about the symbols. + +.. _lv_label_events: Events ****** No special events are sent by the Label. -See the events of the `Base object `__ too. +See the events of the :ref:`Base object ` too. Learn more about :ref:`events`. +.. _lv_label_keys: + Keys **** @@ -146,10 +163,14 @@ No *Keys* are processed by the object type. Learn more about :ref:`indev_keys`. +.. _lv_label_example: + Example ******* .. include:: ../examples/widgets/label/index.rst +.. _lv_label_api: + API *** diff --git a/docs/widgets/led.rst b/docs/widgets/led.rst index 376ec1d52..2c3a97cb8 100644 --- a/docs/widgets/led.rst +++ b/docs/widgets/led.rst @@ -1,3 +1,6 @@ +.. _lv_led: + +============ LED (lv_led) ============ @@ -7,11 +10,14 @@ Overview The LEDs are rectangle-like (or circle) object whose brightness can be adjusted. With lower brightness the colors of the LED become darker. +.. _lv_led_parts_and_styles: + Parts and Styles **************** -The LEDs have only one main part, called :cpp:enumerator:`LV_LED_PART_MAIN` and it -uses all the typical background style properties. +- :cpp:enumerator:`LV_LED_PART_MAIN` uses all the typical background style properties. + +.. _lv_led_usage: Usage ***** @@ -36,6 +42,8 @@ Use :cpp:expr:`lv_led_on(led)` and :cpp:expr:`lv_led_off(led)` to set the bright a predefined ON or OFF value. The :cpp:expr:`lv_led_toggle(led)` toggles between the ON and OFF state. +.. _lv_led_events: + Events ****** @@ -43,6 +51,8 @@ See the events of the `Base object `__ too. Learn more about :ref:`events`. +.. _lv_led_keys: + Keys **** @@ -50,10 +60,14 @@ No *Keys* are processed by the object type. Learn more about :ref:`indev_keys`. +.. _lv_led_example: + Example ******* .. include:: ../examples/widgets/led/index.rst +.. _lv_led_api: + API *** diff --git a/docs/widgets/line.rst b/docs/widgets/line.rst index 6fdd256f8..eebcf3bbb 100644 --- a/docs/widgets/line.rst +++ b/docs/widgets/line.rst @@ -1,3 +1,6 @@ +.. _lv_line: + +============== Line (lv_line) ============== @@ -7,11 +10,14 @@ Overview The Line object is capable of drawing straight lines between a set of points. +.. _lv_line_parts_and_styles: + Parts and Styles **************** -- :cpp:enumerator:`LV_PART_MAIN` uses all the typical background properties and line - style properties. +- :cpp:enumerator:`LV_PART_MAIN` uses all the typical background properties and line style properties. + +.. _lv_line_usage: Usage ***** @@ -44,6 +50,8 @@ counter-intuitive in some cases so the y coordinates can be inverted with :cpp:expr:`lv_line_set_y_invert(line, true)`. In this case, *y == 0* will be the bottom of the object. *y invert* is disabled by default. +.. _lv_line_events: + Events ****** @@ -54,6 +62,8 @@ See the events of the `Base object `__ too. Learn more about :ref:`events`. +.. _lv_line_keys: + Keys **** @@ -61,10 +71,14 @@ No *Keys* are processed by the object type. Learn more about :ref:`indev_keys`. +.. _lv_line_example: + Example ******* .. include:: ../examples/widgets/line/index.rst +.. _lv_line_api: + API *** diff --git a/docs/widgets/list.rst b/docs/widgets/list.rst index 7a4e5f620..01b887a0e 100644 --- a/docs/widgets/list.rst +++ b/docs/widgets/list.rst @@ -1,3 +1,6 @@ +.. _lv_list: + +============== List (lv_list) ============== @@ -7,15 +10,19 @@ Overview The List is basically a rectangle with vertical layout to which Buttons and Texts can be added +.. _lv_list_parts_and_styles: + Parts and Styles **************** **Background** - :cpp:enumerator:`LV_PART_MAIN` The main part of the list that uses all the typical background properties -- :cpp:enumerator:`LV_PART_SCROLLBAR` The scrollbar. See the `Base objects `__ documentation for details. +- :cpp:enumerator:`LV_PART_SCROLLBAR` The scrollbar. See the :ref:`Base objects ` documentation for details. -**Buttons and Texts** See the `Button `__\ 's and `Label `__\ 's documentation. +**Buttons and Texts** See the :ref:`Button `\ 's and :ref:`Label `\ 's documentation. + +.. _lv_list_usage: Usage ***** @@ -35,6 +42,8 @@ Texts :cpp:expr:`lv_list_add_text(list, text)` adds a text. +.. _lv_list_events: + Events ****** @@ -42,6 +51,8 @@ No special events are sent by the List, but sent by the Button as usual. Learn more about :ref:`events`. +.. _lv_list_keys: + Keys **** @@ -49,10 +60,14 @@ No *Keys* are processed by the object type. Learn more about :ref:`indev_keys`. +.. _lv_list_example: + Example ******* .. include:: ../examples/widgets/list/index.rst +.. _lv_list_api: + API *** diff --git a/docs/widgets/menu.rst b/docs/widgets/menu.rst index cf3582dfd..36419a134 100644 --- a/docs/widgets/menu.rst +++ b/docs/widgets/menu.rst @@ -1,3 +1,6 @@ +.. _lv_menu: + +============== Menu (lv_menu) ============== @@ -7,16 +10,25 @@ Overview The menu widget can be used to easily create multi-level menus. It handles the traversal between pages automatically. +.. _lv_menu_parts_and_styles: + Parts and Styles **************** -The menu widget is built from the following objects: - Main container: -lv_menu_main_cont - Main header: lv_menu_main_header_cont - Back button: -`lv_button `__ - Back button icon: `lv_img `__ - -Main page: lv_menu_page - Sidebar container: lv_menu_sidebar_cont - -Sidebar header: lv_menu_sidebar_header_cont - Back button: -`lv_button `__ - Back button icon: `lv_img `__ - -Sidebar page: lv_menu_page +The menu widget is built from the following objects: + +- Main container: :cpp:type:`lv_menu_main_cont` +- Main header: :cpp:type:`lv_menu_main_header_cont` +- Back button: :ref:`lv_button` +- Back button icon: :ref:`lv_img` +- Main page: :cpp:type:`lv_menu_page` +- Sidebar container: :cpp:type:`lv_menu_sidebar_cont` +- Sidebar header: :cpp:type:`lv_menu_sidebar_header_cont` +- Back button: :ref:`lv_button` +- Back button icon: :ref:`lv_img` +- Sidebar page: :cpp:type:`lv_menu_page` + +.. _lv_menu_usage: Usage ***** @@ -84,6 +96,8 @@ menu: - :cpp:expr:`lv_menu_section_create(parent page)` creates a new empty section. - :cpp:expr:`lv_menu_separator_create(parent page)` creates a separator. +.. _lv_menu_events: + Events ****** @@ -105,6 +119,8 @@ See the events of the `Base object `__ too. Learn more about :ref:`events`. +.. _lv_menu_keys: + Keys **** @@ -112,10 +128,14 @@ No keys are handled by the menu widget. Learn more about :ref:`indev_keys`. +.. _lv_menu_example: + Example ******* .. include:: ../examples/widgets/menu/index.rst +.. _lv_menu_api: + API *** diff --git a/docs/widgets/msgbox.rst b/docs/widgets/msgbox.rst index 410f08327..7de707e46 100644 --- a/docs/widgets/msgbox.rst +++ b/docs/widgets/msgbox.rst @@ -1,3 +1,6 @@ +.. _lv_msgbox: + +======================= Message box (lv_msgbox) ======================= @@ -14,16 +17,20 @@ will be set automatically to include the text and the buttons. The message box can be modal (blocking clicks on the rest of the screen) or not modal. +.. _lv_msgbox_parts_and_styles: + Parts and Styles **************** The message box is built from other widgets, so you can check these widgets' documentation for details. -- Background: `lv_obj `__ -- Close button: `lv_btn `__ -- Title and text: `lv_label `__ -- Buttons: `lv_btnmatrix `__ +- Background: :ref:`lv_obj` +- Close button: :ref:`lv_button` +- Title and text: :ref:`lv_label` +- Buttons: :ref:`lv_buttonmatrix` + +.. _lv_msgbox_usage: Usage ***** @@ -58,6 +65,8 @@ Close the message box :cpp:expr:`lv_msgbox_close(msgbox)` closes (deletes) the message box. +.. _lv_msgbox_events: + Events ****** @@ -72,6 +81,8 @@ Events Learn more about :ref:`events`. +.. _lv_msgbox_keys: + Keys **** @@ -80,10 +91,14 @@ manually to a group if required. Learn more about :ref:`indev_keys`. +.. _lv_msgbox_example: + Example ******* .. include:: ../examples/widgets/msgbox/index.rst +.. _lv_msgbox_api: + API *** diff --git a/docs/widgets/obj.rst b/docs/widgets/obj.rst index 3dd946c72..b236a5106 100644 --- a/docs/widgets/obj.rst +++ b/docs/widgets/obj.rst @@ -1,3 +1,6 @@ +.. _lv_obj: + +==================== Base object (lv_obj) ==================== @@ -22,12 +25,16 @@ other widgets too. For example :cpp:expr:`lv_obj_set_width(slider, 100)` The Base object can be directly used as a simple widget: it's nothing more than a rectangle. In HTML terms, think of it as a ``
``. +.. _lv_obj_coordinates: + Coordinates ----------- Only a small subset of coordinate settings is described here. To see all the features of LVGL (padding, coordinates in styles, layouts, etc) -visit the `Coordinates `__ page. +visit the :ref:`Coordinates ` page. + +.. _lv_obj_size: Size ^^^^ @@ -37,6 +44,8 @@ The object size can be modified on individual axes with :cpp:expr:`lv_obj_set_height(obj, new_height)`, or both axes can be modified at the same time with :cpp:expr:`lv_obj_set_size(obj, new_width, new_height)`. +.. _lv_obj_position: + Position ^^^^^^^^ @@ -44,6 +53,8 @@ You can set the position relative to the parent with :cpp:expr:`lv_obj_set_x(obj, new_x)` and :cpp:expr:`lv_obj_set_y(obj, new_y)`, or both axes at the same time with :cpp:expr:`lv_obj_set_pos(obj, new_x, new_y)`. +.. _lv_obj_alignment: + Alignment ^^^^^^^^^ @@ -68,6 +79,8 @@ For example, to align a text below an image: The following align types exist: |image1| +.. _lv_obj_parents_and_children: + Parents and children -------------------- @@ -104,6 +117,8 @@ You can change the index of an object in its parent using You can swap the position of two objects with :cpp:expr:`lv_obj_swap(obj1, obj2)`. +.. _lv_obj_display_and_screens: + Display and Screens ------------------- @@ -124,6 +139,8 @@ explicitly selected with :cpp:func:`lv_disp_set_default`. To get an object's screen use the :cpp:expr:`lv_obj_get_screen(obj)` function. +.. _lv_obj_overview_events: + Events ------ @@ -133,13 +150,15 @@ To set an event callback for an object, use To manually send an event to an object, use :cpp:expr:`lv_event_send(obj, LV_EVENT_..., param)` -Read the `Event overview `__ to learn more about +Read the :ref:`Event overview ` to learn more about events. +.. _lv_obj_styles: + Styles ------ -Be sure to read the `Style overview `__. Here only the +Be sure to read the :ref:`Style overview `. Here only the most essential functions are described. A new style can be added to an object with the @@ -150,6 +169,8 @@ is an ORed combination of part and state(s). E.g. The base objects use :cpp:enumerator:`LV_PART_MAIN` style properties and :cpp:enumerator:`LV_PART_SCROLLBAR` with the typical background style properties. +.. _lv_obj_flags: + Flags ----- @@ -198,10 +219,12 @@ Some examples: /*Make an object non-clickable*/ lv_obj_remove_flag(obj, LV_OBJ_FLAG_CLICKABLE); +.. _lv_obj_groups: + Groups ------ -Read the `Input devices overview `__ to learn more +Read the :ref:`Input devices overview ` to learn more about *Groups*. Objects are added to a *group* with :cpp:expr:`lv_group_add_obj(group, obj)`, @@ -212,6 +235,8 @@ belongs to. its group or not. If the object is not added to a group, ``false`` will be returned. +.. _lv_obj_extended_click_area: + Extended click area ------------------- @@ -221,6 +246,8 @@ However, this can be extended with .. _events-1: +.. _lv_obj_events: + Events ****** @@ -229,6 +256,8 @@ Events Learn more about :ref:`events`. +.. _lv_obj_keys: + Keys **** @@ -241,18 +270,21 @@ If :cpp:enumerator:`LV_OBJ_FLAG_SCROLLABLE` is enabled, but the object is not ed :cpp:enumerator:`LV_KEY_DOWN`, :cpp:enumerator:`LV_KEY_LEFT`, :cpp:enumerator:`LV_KEY_RIGHT`) scroll the object. If the object can only scroll vertically, :cpp:enumerator:`LV_KEY_LEFT` and :cpp:enumerator:`LV_KEY_RIGHT` will scroll up/down instead, making it compatible with -an encoder input device. See `Input devices overview `__ for +an encoder input device. See :ref:`Input devices overview ` for more on encoder behaviors and the edit mode. Learn more about :ref:`indev_keys`. .. |image1| image:: /misc/align.png +.. _lv_obj_example: Example ******* .. include:: ../examples/widgets/obj/index.rst +.. _lv_obj_api: + API *** diff --git a/docs/widgets/roller.rst b/docs/widgets/roller.rst index d7a880cf8..c0a788547 100644 --- a/docs/widgets/roller.rst +++ b/docs/widgets/roller.rst @@ -1,3 +1,6 @@ +.. _lv_roller: + +================== Roller (lv_roller) ================== @@ -6,6 +9,8 @@ Overview Roller allows you to simply select one option from a list by scrolling. +.. _lv_roller_parts_and_styles: + Parts and Styles **************** @@ -19,6 +24,8 @@ Parts and Styles typical background properties it uses the text style properties to change the appearance of the text in the selected area. +.. _lv_roller_usage: + Usage ***** @@ -52,6 +59,8 @@ This function calculates the height with the current style. If the font, line space, border width, etc. of the roller changes this function needs to be called again. +.. _lv_roller_events: + Events ****** @@ -61,6 +70,8 @@ See the events of the `Base object `__ too. Learn more about :ref:`events`. +.. _lv_roller_keys: + Keys **** @@ -68,10 +79,14 @@ Keys - ``LV_KEY_LEFT/UP`` Select the previous option - :cpp:enumerator:`LY_KEY_ENTER` Apply the selected option (Send :cpp:enumerator:`LV_EVENT_VALUE_CHANGED` event) +.. _lv_roller_example: + Example ******* .. include:: ../examples/widgets/roller/index.rst +.. _lv_roller_api: + API *** diff --git a/docs/widgets/scale.rst b/docs/widgets/scale.rst index 69d21cd50..1fd9639c7 100644 --- a/docs/widgets/scale.rst +++ b/docs/widgets/scale.rst @@ -1,11 +1,16 @@ +.. _lv_scale: + +================ Scale (lv_scale) -=============== +================ Overview ******** Scale allows you to have a linear scale with ranges and sections with custom styling. +.. _lv_scale_parts_and_styles: + Parts and Styles **************** @@ -17,6 +22,8 @@ The scale widget is divided in the following three parts: .. image:: /misc/scale.png +.. _lv_scale_usage: + Usage ***** @@ -47,22 +54,29 @@ For labels the following properties can be configured: For lines (main line, major and minor ticks) the following properties can be configured: :cpp:expr:`lv_style_set_line_color`, :cpp:expr:`lv_style_set_line_width`. +.. _lv_scale_events: + Events ****** No events supported by this widget. +.. _lv_scale_keys: + Keys **** No keys supported by this widget. +.. _lv_scale_example: Example ******* .. include:: ../examples/widgets/scale/index.rst +.. _lv_scale_api: + API *** diff --git a/docs/widgets/slider.rst b/docs/widgets/slider.rst index 6186b5f26..617ba269a 100644 --- a/docs/widgets/slider.rst +++ b/docs/widgets/slider.rst @@ -1,5 +1,6 @@ -.. _slider: +.. _lv_slider: +================== Slider (lv_slider) ================== @@ -10,6 +11,8 @@ The Slider object looks like a `Bar `__ supplemented with a knob. The knob can be dragged to set a value. Just like Bar, Slider can be vertical or horizontal. +.. _lv_slider_parts_and_styles: + Parts and Styles **************** @@ -25,6 +28,8 @@ Parts and Styles knob can be made larger with the ``padding`` values. Padding values can be asymmetric too. +.. _lv_slider_usage: + Usage ***** @@ -65,6 +70,8 @@ feature is enabled by adding the :cpp:enumerator:`LV_OBJ_FLAG_ADV_HITTEST`: The extended click area (set by :cpp:expr:`lv_obj_set_ext_click_area(slider, value)`) increases to knob's click area. +.. _lv_slider_events: + Events ****** @@ -77,6 +84,8 @@ See the events of the `Bar `__ too. Learn more about :ref:`events`. +.. _lv_slider_keys: + Keys **** @@ -85,10 +94,14 @@ Keys Learn more about :ref:`indev_keys`. +.. _lv_slider_example: + Example ******* .. include:: ../examples/widgets/slider/index.rst +.. _lv_slider_api: + API *** diff --git a/docs/widgets/span.rst b/docs/widgets/span.rst index 16277b1f0..7391f58e2 100644 --- a/docs/widgets/span.rst +++ b/docs/widgets/span.rst @@ -1,3 +1,6 @@ +.. _lv_span: + +============== Span (lv_span) ============== @@ -8,11 +11,15 @@ A spangroup is the object that is used to display rich text. Different from the label object, ``spangroup`` can render text styled with different fonts, colors, and sizes into the spangroup object. +.. _lv_span_parts_and_styles: + Parts and Styles **************** - :cpp:enumerator:`LV_PART_MAIN` The spangroup has only one part. +.. _lv_span_usage: + Usage ***** @@ -103,6 +110,8 @@ Use :cpp:expr:`lv_spangroup_set_max_lines(spangroup, 10)` to set the maximum num of lines to be displayed in LV_SPAN_MODE_BREAK mode, negative values indicate no limit. +.. _lv_span_events: + Events ****** @@ -110,6 +119,8 @@ No special events are sent by this widget. Learn more about :ref:`events`. +.. _lv_span_keys: + Keys **** @@ -117,11 +128,14 @@ No *Keys* are processed by the object type. Learn more about :ref:`indev_keys`. +.. _lv_span_example: + Example ******* - .. include:: ../examples/widgets/span/index.rst +.. _lv_span_api: + API *** diff --git a/docs/widgets/spinbox.rst b/docs/widgets/spinbox.rst index 93065df27..229c9ac84 100644 --- a/docs/widgets/spinbox.rst +++ b/docs/widgets/spinbox.rst @@ -1,3 +1,6 @@ +.. _lv_spinbox: + +==================== Spinbox (lv_spinbox) ==================== @@ -6,13 +9,14 @@ Overview The Spinbox contains a number as text which can be increased or decreased by *Keys* or API functions. Under the hood the Spinbox is a -modified `Text area `__. +modified :ref:`Text area `. + +.. _lv_spinbox_parts_and_styles: Parts and Styles **************** -The parts of the Spinbox are identical to the `Text -area `__. +The parts of the Spinbox are identical to the :ref:`Text area `. Value, range and step --------------------- @@ -52,15 +56,19 @@ rollover mode. If either the minimum or maximum value is reached with rollover enabled, the value will change to the other limit. If rollover is disabled the value will remain at the minimum or maximum value. +.. _lv_spinbox_events: + Events ****** - :cpp:enumerator:`LV_EVENT_VALUE_CHANGED` Sent when the value has changed. -See the events of the `Text area `__ too. +See the events of the :ref:`Text area ` too. Learn more about :ref:`events`. +.. _lv_spinbox_keys: + Keys **** @@ -71,10 +79,14 @@ Keys - :cpp:enumerator:`LV_KEY_ENTER` With *Encoder* got the net digit. Jump to the first after the last. +.. _lv_spinbox_example: + Example ******* .. include:: ../examples/widgets/spinbox/index.rst +.. _lv_spinbox_api: + API *** diff --git a/docs/widgets/spinner.rst b/docs/widgets/spinner.rst index ef0bfed35..486230f49 100644 --- a/docs/widgets/spinner.rst +++ b/docs/widgets/spinner.rst @@ -1,3 +1,6 @@ +.. _lv_spinner: + +==================== Spinner (lv_spinner) ==================== @@ -6,10 +9,14 @@ Overview The Spinner object is a spinning arc over a ring. +.. _lv_spinner_parts_and_styles: + Parts and Styles **************** -The parts are identical to the parts of `lv_arc `__. +The parts are identical to the parts of :ref:`lv_arc`. + +.. _lv_spinner_usage: Usage ***** @@ -23,6 +30,8 @@ To create a spinner use Using :cpp:expr:`lv_spinner_set_anim_params(spinner, spin_duration, angle)` the duration of one revulation and the length of he arc can be customized. +.. _lv_spinner_events: + Events ****** @@ -32,6 +41,8 @@ See the events of the `Arc `__ too. Learn more about :ref:`events`. +.. _lv_spinner_keys: + Keys **** @@ -39,10 +50,14 @@ No *Keys* are processed by the object type. Learn more about :ref:`indev_keys`. +.. _lv_spinner_example: + Example ******* .. include:: ../examples/widgets/spinner/index.rst +.. _lv_spinner_api: + API *** diff --git a/docs/widgets/switch.rst b/docs/widgets/switch.rst index a04ceb70d..c1107abac 100644 --- a/docs/widgets/switch.rst +++ b/docs/widgets/switch.rst @@ -1,3 +1,6 @@ +.. _lv_switch: + +================== Switch (lv_switch) ================== @@ -7,6 +10,8 @@ Overview The Switch looks like a little slider and can be used to turn something on and off. +.. _lv_switch_parts_and_styles: + Parts and Styles **************** @@ -22,6 +27,8 @@ Parts and Styles the slider. The knob can be made larger with the ``padding`` values. Padding values can be asymmetric too. +.. _lv_switch_usage: + Usage ***** @@ -36,6 +43,8 @@ To get the current state of the switch (with ``true`` being on), use Call :cpp:expr:`lv_obj_add_state(obj, LV_STATE_CHECKED)` to turn it on, or :cpp:expr:`lv_obj_remove_state(obj, LV_STATE_CHECKED)` to turn it off. +.. _lv_switch_events: + Events ****** @@ -45,6 +54,8 @@ See the events of the `Base object `__ too. Learn more about :ref:`events`. +.. _lv_switch_keys: + Keys **** @@ -54,10 +65,14 @@ Keys Learn more about :ref:`indev_keys`. +.. _lv_switch_example: + Example ******* .. include:: ../examples/widgets/switch/index.rst +.. _lv_switch_api: + API *** diff --git a/docs/widgets/table.rst b/docs/widgets/table.rst index b82362456..97f7e0014 100644 --- a/docs/widgets/table.rst +++ b/docs/widgets/table.rst @@ -1,3 +1,6 @@ +.. _lv_table: + +================ Table (lv_table) ================ @@ -15,6 +18,8 @@ The Table is added to the default group (if it is set). Besides the Table is an editable object to allow selecting a cell with encoder navigation too. +.. _lv_table_parts_and_styles: + Parts and Styles **************** @@ -23,6 +28,8 @@ Parts and Styles - :cpp:enumerator:`LV_PART_ITEMS` The cells of the table also use all the typical background style properties and the text properties. +.. _lv_table_usage: + Usage ***** @@ -74,6 +81,8 @@ automatically sets the table size to show all the columns and rows. If the width or height is set to a smaller number than the "intrinsic" size then the table becomes scrollable. +.. _lv_table_events: + Events ****** @@ -84,6 +93,8 @@ See the events of the `Base object `__ too. Learn more about :ref:`events`. +.. _lv_table_keys: + Keys **** @@ -99,6 +110,8 @@ currently selected cell. Row and column will be set to Learn more about :ref:`indev_keys`. +.. _lv_table_example: + Example ******* @@ -109,5 +122,7 @@ MicroPython No examples yet. +.. _lv_table_api: + API *** diff --git a/docs/widgets/tabview.rst b/docs/widgets/tabview.rst index 2e4f275ac..80c54d854 100644 --- a/docs/widgets/tabview.rst +++ b/docs/widgets/tabview.rst @@ -1,3 +1,6 @@ +.. _lv_tabview: + +==================== Tabview (lv_tabview) ==================== @@ -7,10 +10,10 @@ Overview The Tab view object can be used to organize content in tabs. The Tab view is built from other widgets: -- Main container: `lv_obj `__ -- Tab buttons: an `lv_obj `__` with `lv_button `__ s -- Container for the tabs: `lv_obj `__ -- Content of the tabs: `lv_obj `__ +- Main container: :ref:`lv_obj` +- Tab buttons: an :ref:`lv_obj` with :ref:`lv_button` +- Container for the tabs: :ref:`lv_obj` +- Content of the tabs: :ref:`lv_obj` The tab buttons can be positioned on the top, bottom, left and right side of the Tab view. @@ -18,25 +21,29 @@ side of the Tab view. A new tab can be selected either by clicking on a tab button or by sliding horizontally on the content. +.. _lv_tabview_parts_and_styles: + Parts and Styles **************** There are no special parts on the Tab view but the ``lv_obj`` and ``lv_button`` widgets are used to create the Tab view. +.. _lv_tabview_usage: + Usage ***** Create a Tab view ----------------- -:cpp:expr:`lv_tabview_create(parent)` creates a new empty -Tab view. +:cpp:expr:`lv_tabview_create(parent)` creates a new empty Tab view. + Add tabs -------- New tabs can be added with :cpp:expr:`lv_tabview_add_tab(tabview, "Tab name")`. -This will return a pointer to an `lv_obj `__ object where +This will return a pointer to an :ref:`lv_obj` object where the tab's content can be created. Rename tabs @@ -73,7 +80,9 @@ Get the parts :cpp:expr:`lv_tabview_get_content(tabview)` returns the container for the tabs, :cpp:expr:`lv_tabview_get_tab_buttons(tabview)` returns the Tab buttons object -which is a `Button matrix `__. +which is a :ref:`Button matrix `. + +.. _lv_tabview_events: Events ****** @@ -84,6 +93,8 @@ Events Learn more about :ref:`events`. +.. _lv_tabview_keys: + Keys **** @@ -92,10 +103,14 @@ to a group if required. Learn more about :ref:`indev_keys`. +.. _lv_tabview_example: + Example ******* .. include:: ../examples/widgets/tabview/index.rst +.. _lv_tabview_api: + API *** diff --git a/docs/widgets/textarea.rst b/docs/widgets/textarea.rst index beb76cef9..f59b7b5b6 100644 --- a/docs/widgets/textarea.rst +++ b/docs/widgets/textarea.rst @@ -1,16 +1,21 @@ +.. _lv_textarea: + +======================= Text area (lv_textarea) ======================= Overview ******** -The Text Area is a `Base object `__ with a +The Text Area is a `Base object `__ with a `Label `__ and a cursor on it. Texts or characters can be added to it. Long lines are wrapped and when the text becomes long enough the Text area can be scrolled. One line mode and password modes are supported. +.. _lv_textarea_parts_and_styles: + Parts and Styles **************** @@ -33,6 +38,8 @@ Parts and Styles - :cpp:enumerator:`LV_PART_TEXTAREA_PLACEHOLDER` Unique to Text Area, allows styling the placeholder text. +.. _lv_textarea_usage: + Usage ***** @@ -144,6 +151,8 @@ Any part of the text can be selected if enabled with :cpp:expr:`lv_textarea_set_text_selection(textarea, true)`. This works much like when you select text on your PC with your mouse. +.. _lv_textarea_events: + Events ****** @@ -162,6 +171,8 @@ See the events of the `Base object `__ too. Learn more about :ref:`events`. +.. _lv_textarea_keys: + Keys **** @@ -170,10 +181,14 @@ Keys Learn more about :ref:`indev_keys`. +.. _lv_textarea_example: + Example ******* .. include:: ../examples/widgets/textarea/index.rst +.. _lv_textarea_api: + API *** diff --git a/docs/widgets/tileview.rst b/docs/widgets/tileview.rst index f85945290..2ab8792bd 100644 --- a/docs/widgets/tileview.rst +++ b/docs/widgets/tileview.rst @@ -1,3 +1,6 @@ +.. _lv_tileview: + +======================= Tile view (lv_tileview) ======================= @@ -12,13 +15,17 @@ individually to not allow moving from one tile to another. If the Tile view is screen sized, the user interface resembles what you may have seen on smartwatches. +.. _lv_tileview_parts_and_styles: + Parts and Styles **************** -The Tile view is built from an `lv_obj `__ container and -`lv_obj `__ tiles. +The Tile view is built from an :ref:`lv_obj` container and +:ref:`lv_obj` tiles. -The parts and styles work the same as for `lv_obj `__. +The parts and styles work the same as for :ref:`lv_obj`. + +.. _lv_tileview_usage: Usage ***** @@ -41,6 +48,8 @@ The Tile view can scroll to a tile with :cpp:expr:`lv_tileview_set_tile(tileview, tile_obj, LV_ANIM_ON/OFF)` or :cpp:expr:`lv_tileview_set_tile_by_index(tileview, col_id, row_id, LV_ANIM_ON/OFF)` +.. _lv_tileview_events: + Events ****** @@ -48,6 +57,8 @@ Events :cpp:expr:`lv_tileview_get_tile_active(tabview)` can be used to get current tile. +.. _lv_tileview_keys: + Keys **** @@ -55,10 +66,14 @@ Keys Learn more about :ref:`indev_keys`. +.. _lv_tileview_example: + Example ******* .. include:: ../examples/widgets/tileview/index.rst +.. _lv_tileview_api: + API *** diff --git a/docs/widgets/win.rst b/docs/widgets/win.rst index f80fc27ce..2ca889829 100644 --- a/docs/widgets/win.rst +++ b/docs/widgets/win.rst @@ -1,3 +1,6 @@ +.. _lv_win: + +=============== Window (lv_win) =============== @@ -7,17 +10,21 @@ Overview The Window is container-like object built from a header with title and buttons and a content area. +.. _lv_win_parts_and_styles: + Parts and Styles **************** The Window is built from other widgets so you can check their documentation for details: -- Background: `lv_obj `__ -- Header on the background: `lv_obj `__ -- Title on the header: `lv_label `__ -- Buttons on the header: `lv_button `__ -- Content area on the background: `lv_obj `__ +- Background: :ref:`lv_obj` +- Header on the background: :ref:`lv_obj` +- Title on the header: :ref:`lv_label` +- Buttons on the header: :ref:`lv_button` +- Content area on the background: :ref:`lv_obj` + +.. _lv_win_usage: Usage ***** @@ -45,6 +52,8 @@ the title is set to take all the remaining space on the header. In other words: it pushes to the right all the buttons that are added after the title. +.. _lv_win_get_parts: + Get the parts ************* @@ -52,6 +61,8 @@ Get the parts :cpp:expr:`lv_win_get_content(win)` returns a pointer to the content container to which the content of the window can be added. +.. _lv_win_events: + Events ****** @@ -60,6 +71,8 @@ manually to the return value of :cpp:func:`lv_win_add_button`. Learn more about :ref:`events`. +.. _lv_win_keys: + Keys **** @@ -67,10 +80,14 @@ No *Keys* are handled by the window. Learn more about :ref:`indev_keys`. +.. _lv_win_example: + Example ******* .. include:: ../examples/widgets/win/index.rst +.. _lv_win_api: + API *** diff --git a/examples/libs/libjpeg_turbo/index.rst b/examples/libs/libjpeg_turbo/index.rst index ce6c3715d..299b1b110 100644 --- a/examples/libs/libjpeg_turbo/index.rst +++ b/examples/libs/libjpeg_turbo/index.rst @@ -1,4 +1,4 @@ -Load an JPG image +Load a JPG image ----------------- .. lv_example:: libs/libjpeg_turbo/lv_example_libjpeg_turbo_1 diff --git a/examples/libs/lodepng/index.rst b/examples/libs/lodepng/index.rst index f4957a5ee..11e035e5a 100644 --- a/examples/libs/lodepng/index.rst +++ b/examples/libs/lodepng/index.rst @@ -1,6 +1,6 @@ Open a PNG image from file and variable --------------------------------------- -.. lv_example:: libs/lodepng/lv_example_png_1 +.. lv_example:: libs/lodepng/lv_example_lodepng_1 :language: c diff --git a/examples/libs/tjpgd/index.rst b/examples/libs/tjpgd/index.rst index c59536c87..a742f8c52 100644 --- a/examples/libs/tjpgd/index.rst +++ b/examples/libs/tjpgd/index.rst @@ -1,4 +1,4 @@ -Load an SJPG image +Load a JPG image ------------------ .. lv_example:: libs/tjpgd/lv_example_tjpgd_1