From b8c5a4123d5ed83fffcde37f58a9aa6e478b95a1 Mon Sep 17 00:00:00 2001 From: Victor Wheeler Date: Tue, 3 Dec 2024 09:15:15 -0700 Subject: [PATCH] feat(docs): batch 8 of proofread/edited docs (#7295) Co-authored-by: Liam <30486941+liamHowatt@users.noreply.github.com> --- docs/details/widgets/tabview.rst | 68 +++++----- docs/details/widgets/textarea.rst | 199 +++++++++++++++++++----------- docs/details/widgets/tileview.rst | 31 +++-- docs/details/widgets/win.rst | 69 ++++++++--- 4 files changed, 236 insertions(+), 131 deletions(-) diff --git a/docs/details/widgets/tabview.rst b/docs/details/widgets/tabview.rst index 4ef13c7b3..9df05ba6c 100644 --- a/docs/details/widgets/tabview.rst +++ b/docs/details/widgets/tabview.rst @@ -1,14 +1,15 @@ .. _lv_tabview: -==================== -Tabview (lv_tabview) -==================== +===================== +Tab View (lv_tabview) +===================== + Overview ******** -The Tab view Widget can be used to organize content in tabs. The Tab -view is built from other widgets: +The Tab View Widget can be used to organize content in tabs. The Tab +View is built from other Widgets: - Main container: :ref:`base_widget` - Tab buttons: an :ref:`base_widget` with :ref:`lv_button` @@ -16,70 +17,77 @@ view is built from other widgets: - Content of the tabs: :ref:`base_widget` The tab buttons can be positioned on the top, bottom, left and right -side of the Tab view. +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 :ref:`base_widget` and -:ref:`lv_button` widgets are used to create the Tab view. +There are no special parts on the Tab View but the :ref:`base_widget` and +:ref:`lv_button` Widgets are used to create the Tab View. + + .. _lv_tabview_usage: Usage ***** -Create a Tab view ------------------ +Creating 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 --------- +Adding tabs +----------- New tabs can be added with :cpp:expr:`lv_tabview_add_tab(tabview, "Tab name")`. This will return a pointer to a :ref:`base_widget` where the tab's content can be created. -Rename tabs ------------ +Renaming tabs +------------- A tab can be renamed with :cpp:expr:`lv_tabview_rename_tab(tabview, tab_id, "New Name")`. -Change tab ----------- +Navigating to a new tab +----------------------- To select a new tab you can: - Click on its tab button - Slide horizontally -- Use :cpp:expr:`lv_tabview_set_active(tabview, id, LV_ANIM_ON)` function +- Use :cpp:expr:`lv_tabview_set_active(tabview, tab_id, LV_ANIM_ON / OFF)` function -Set tab bar position --------------------- +Setting tab bar position +------------------------ Using the :cpp:expr:`lv_tabview_set_tab_bar_position(tabview, LV_DIR_LEFT/RIGHT/TOP/BOTTOM)` -the tab bar can be moved to any sides. +the tab bar can be moved to any side. -Set tab bar size ----------------- +Setting tab bar size +-------------------- The size of the tab bar can be adjusted by :cpp:expr:`lv_tabview_set_tab_bar_size(tabview, size)` -In case of vertical arrangement is means the height of the tab bar, and in horizontal -arrangement it means the width. +When tabs are on the top or bottom, this means the height of the tab bar, and when +they are on the sides, it means the width. -Get the parts -------------- +Accessing the parts +------------------- -- :cpp:expr:`lv_tabview_get_content(tabview)` returns the container for tabs content -- :cpp:expr:`lv_tabview_get_tab_bar(tabview)` returns the container for tabs buttons +- :cpp:expr:`lv_tabview_get_content(tabview)` returns a pointer to the container for + tabs content (a :ref:`base_widget`) +- :cpp:expr:`lv_tabview_get_tab_bar(tabview)` returns a pointer to the container for + tab buttons (a :ref:`base_widget`) @@ -106,7 +114,7 @@ Keys **** Keys have effect only on the tab buttons. -Add manually to a group if required. +Programmatically add these buttons to a group if required. .. admonition:: Further Reading diff --git a/docs/details/widgets/textarea.rst b/docs/details/widgets/textarea.rst index 77ca7ddb2..da74e5588 100644 --- a/docs/details/widgets/textarea.rst +++ b/docs/details/widgets/textarea.rst @@ -4,117 +4,135 @@ Text Area (lv_textarea) ======================= + Overview ******** The Text Area is a :ref:`base_widget_overview` with a :ref:`lv_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. +it. Text 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. + -One line mode and password modes are supported. .. _lv_textarea_parts_and_styles: Parts and Styles **************** -- :cpp:enumerator:`LV_PART_MAIN` The background of the text area. Uses all the - typical background style properties and the text related style - properties including ``text_align`` to align the text to the left, +- :cpp:enumerator:`LV_PART_MAIN` The background of the Text Area; uses the + :ref:`typical background style properties ` and the text related + style properties including ``text_align`` to align the text to the left, right or center. - :cpp:enumerator:`LV_PART_SCROLLBAR` The scrollbar that is shown when the text is - too long. + longer than its height. - :cpp:enumerator:`LV_PART_SELECTED` Determines the style of the :ref:`selected text `. Only ``text_color`` and ``bg_color`` style properties can be used. ``bg_color`` should be set - directly on the label of the text area. + directly on the label of the Text Area. - :cpp:enumerator:`LV_PART_CURSOR` Marks the position where the characters are inserted. The cursor's area is always the bounding box of the current character. A block cursor can be created by adding a background color - and background opacity to :cpp:enumerator:`LV_PART_CURSOR`\ 's style. The create - line cursor leave the cursor transparent and set a left border. The + and background opacity to :cpp:enumerator:`LV_PART_CURSOR`\ 's style. To create + a "bar" cursor leave the cursor transparent and set a left border. The ``anim_time`` style property sets the cursor's blink time. -- :cpp:enumerator:`LV_PART_TEXTAREA_PLACEHOLDER` Unique to Text Area, allows styling - the placeholder text. +- :cpp:enumerator:`LV_PART_TEXTAREA_PLACEHOLDER` Unique to Text Area; allows styling + the :ref:`placeholder text `. + + .. _lv_textarea_usage: Usage ***** -Add text --------- +Adding text +----------- You can insert text or characters to the current cursor's position with: - :cpp:expr:`lv_textarea_add_char(textarea, 'c')` - :cpp:expr:`lv_textarea_add_text(textarea, "insert this text")` -To add wide characters like ``'á'``, ``'ß'`` or CJK characters use -:cpp:expr:`lv_textarea_add_text(ta, "á")`. +To add wide characters like ``'á'``, ``'ß'`` or CJK characters, use +:cpp:expr:`lv_textarea_add_text(textarea, "á")`. -:cpp:expr:`lv_textarea_set_text(ta, "New text")` changes the whole text. +:cpp:expr:`lv_textarea_set_text(textarea, "New text")` replaces all existing text +with "New text". -Placeholder ------------ +.. _textarea_placeholder_text: -A placeholder text can be specified +Placeholder text +---------------- -- which is displayed when the Text area is empty -- with :cpp:expr:`lv_textarea_set_placeholder_text(ta, "Placeholder text")` +Placeholder text is text that is displayed when the Text Area is empty. This can be +a handy way to provide the end user with a hint about what to type there. + +Specify placeholder text using +:cpp:expr:`lv_textarea_set_placeholder_text(textarea, "Placeholder text")`. Delete character ---------------- -To delete a character from the left of the current cursor position use +To delete the character to the left of the current cursor position, use :cpp:expr:`lv_textarea_delete_char(textarea)`. -To delete from the right use :cpp:expr:`lv_textarea_delete_char_forward(textarea)` +To delete to the right, use :cpp:expr:`lv_textarea_delete_char_forward(textarea)` -Move the cursor ---------------- +Moving the cursor +----------------- -The cursor position can be modified directly like -:cpp:expr:`lv_textarea_set_cursor_pos(textarea, 10)`. The ``0`` position means -"before the first characters", :cpp:enumerator:`LV_TEXTAREA_CURSOR_LAST` means "after the +The cursor position can be modified programmatically using +:cpp:expr:`lv_textarea_set_cursor_pos(textarea, corsor_pos)` where ``cursor_pos`` is +the zero-based index of the character the cursor should be placed in front of. +:cpp:enumerator:`LV_TEXTAREA_CURSOR_LAST` can be passed to mean "after the last character" -You can step the cursor with +You can move the cursor one character-position (or line) at a time with - :cpp:expr:`lv_textarea_cursor_right(textarea)` - :cpp:expr:`lv_textarea_cursor_left(textarea)` - :cpp:expr:`lv_textarea_cursor_up(textarea)` - :cpp:expr:`lv_textarea_cursor_down(textarea)` -If :cpp:expr:`lv_textarea_set_cursor_click_pos(textarea, true)` is applied the -cursor will jump to the position where the Text area was clicked. +If :cpp:expr:`lv_textarea_set_cursor_click_pos(textarea, true)` is applied, the +cursor will jump to the position where the Text Area was clicked. -Hide the cursor ---------------- +Hiding the cursor +----------------- -The cursor is always visible, however it can be a good idea to style it -to be visible only in :cpp:enumerator:`LV_STATE_FOCUSED` state. +The cursor is normally always visible. It it can be a good idea to style it +to be visible only in :cpp:enumerator:`LV_STATE_FOCUSED` state. See :ref:`styles` +for more information about how to do this. -One line mode +One-line mode ------------- -The Text area can be configured to be on a single line with -:cpp:expr:`lv_textarea_set_one_line(textarea, true)`. In this mode the height is -set automatically to show only one line, line break characters are -ignored, and word wrap is disabled. +The Text Area can be configured to keep all text on a single line with +:cpp:expr:`lv_textarea_set_one_line(textarea, true)`. In this mode: + +- the height is set automatically to show only one line, +- line break characters are ignored, and +- word wrap is disabled. Password mode ------------- -The text area supports password mode which can be enabled with +The Text Area supports password mode which can be enabled with :cpp:expr:`lv_textarea_set_password_mode(textarea, true)`. By default, if the ``•`` (`Bullet, U+2022 `__) -character exists in the font, the entered characters are converted to it -after some time or when a new character is entered. If ``•`` does not +character exists in the font, the entered characters are converted to it after +a configurable delay after each new character is entered. If ``•`` does not exist in the font, ``*`` will be used. You can override the default -character with :cpp:expr:`lv_textarea_set_password_bullet(textarea, "x")`. +"masking" character with :cpp:expr:`lv_textarea_set_password_bullet(textarea, str)` +where ``str`` is a NUL-terminated C string. Example: + +.. code-block:: c + + lv_textarea_set_password_bullet(textarea, "x"); In password mode :cpp:expr:`lv_textarea_get_text(textarea)` returns the actual text entered, not the bullet characters. @@ -125,32 +143,72 @@ Accepted characters ------------------- You can set a list of accepted characters with -:cpp:expr:`lv_textarea_set_accepted_chars(textarea, "0123456789.+-")`. Other -characters will be ignored. +:cpp:expr:`lv_textarea_set_accepted_chars(textarea, list)` where ``list`` is a +pointer to a NUL-terminated string, or NULL to accept all characters. Characters +entered not in this list will be ignored. + +.. code-block:: c + + lv_textarea_set_accepted_chars(textarea, "0123456789.+-"); Max text length --------------- -The maximum number of characters can be limited with -:cpp:expr:`lv_textarea_set_max_length(textarea, max_char_num)` +The maximum number of characters can be limited using +:cpp:expr:`lv_textarea_set_max_length(textarea, max_char_num)`. -Very long texts ---------------- +Very long text +-------------- -If there is a very long text in the Text area (e.g. > 20k characters), -scrolling and drawing might be slow. However, by enabling -:c:macro:`LV_LABEL_LONG_TXT_HINT` in ``lv_conf.h`` the performance can be -hugely improved. This will save some additional information about the -label to speed up its drawing. Using :c:macro:`LV_LABEL_LONG_TXT_HINT` the -scrolling and drawing will as fast as with "normal" short texts. +If the text in the Text Area is very long (e.g. > 20k characters), scrolling and +drawing might be slow. However, by setting :c:macro:`LV_LABEL_LONG_TXT_HINT` in +``lv_conf.h`` to a non-zero value, the performance with long text is significantly +improved. It does this by saving some additional information about the current +vertical position of the text shown. With this mode configured, scrolling and drawing +is as fast as with "normal" short text. The cost is 12 extra bytes per label in RAM. -Select text ------------ +This value is set to ``1`` by default. If you do not use long text, you can save +12 bytes per label by setting it to ``0``. + +Selecting text +-------------- + +If :c:macro:`LV_LABEL_TEXT_SELECTION` is set to a non-zero value in ``lv_conf.h``, +some additional functionality (and 8 bytes per label) are added to Label Widgets +and Text Area Widgets, and text-selection functionality is automated in Text Area +Widgets. (If you do not use selected text in your application, you can save 8 bytes +per label in RAM by setting that macro to equate to ``0``.) 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. +:cpp:expr:`lv_textarea_set_text_selection(textarea, true)`. This works much like +when you select text on your PC with your mouse. If you pass ``false`` to this +function to disable text-selection, any text selected at the time of the call will be +de-selected. +If you need to programmatically deal with selected text, in addition to the +:cpp:expr:`lv_textarea_set_text_selection(textarea, enable)` function, the following +is your tool set for doing so. (``ta_label`` is a pointer to the Text Area's +Label retrieved with ``ta_label = lv_textarea_get_label(textarea);``.) + +- :cpp:expr:`lv_textarea_get_text_selection(textarea)` tells whether text selection is enabled. +- :cpp:expr:`lv_textarea_text_is_selected(textarea)` tells whether any text is currently selected. +- :cpp:expr:`lv_textarea_clear_selection(textarea)` clears current text selection. +- :cpp:expr:`lv_label_set_text_selection_start(ta_label, index)` where ``index`` is + the zero-based index of the first character of the selected text. + Pass :c:macro:`LV_DRAW_LABEL_NO_TXT_SEL` to specify no text selected. +- :cpp:expr:`lv_label_set_text_selection_end(ta_label, index)` where ``index`` is + the zero-based index of the character just after the selected text. + Pass :c:macro:`LV_DRAW_LABEL_NO_TXT_SEL` to specify no text selected. +- :cpp:expr:`lv_label_get_text_selection_start(ta_label)` zero-based index of the + first character of the selected text. + :c:macro:`LV_DRAW_LABEL_NO_TXT_SEL` indicates no text selected. +- :cpp:expr:`lv_label_get_text_selection_end(ta_label)` zero-based index of the + character just after the selected text. + :c:macro:`LV_DRAW_LABEL_NO_TXT_SEL` indicates no text selected. + +Normally you won't need these since Text Area automates the text selection process, +but if you do need to change the selection programmatically, the above are your +tools to do so. .. _lv_textarea_events: @@ -160,14 +218,17 @@ Events - :cpp:enumerator:`LV_EVENT_INSERT` Sent right before a character or text is inserted. The event parameter is the text about to be inserted. - :cpp:expr:`lv_textarea_set_insert_replace(textarea, "New text")` replaces the - text to insert. The new text cannot be in a local variable which is - destroyed when the event callback exists. ``""`` means do not insert - anything. -- :cpp:enumerator:`LV_EVENT_VALUE_CHANGED` Sent when the content of the text area has - been changed. -- :cpp:enumerator:`LV_EVENT_READY` Sent when :cpp:enumerator:`LV_KEY_ENTER` is pressed (or sent) to - a one line text area. + :cpp:expr:`lv_textarea_set_insert_replace(textarea, "New text")` can be called + from within that event to replace the text to be inserted. The contents of the + buffer passed must be survive long enough for the call to `lv_timer_handler()` + that is driving the event to return (after which the Text Area's label will have + copied the text). So it should not be a local buffer (created on the stack) + where its contents will be destroyed before that happens. Passing ``""`` means "do + not insert anything". +- :cpp:enumerator:`LV_EVENT_VALUE_CHANGED` Sent when the content of the Text Area + has changed. +- :cpp:enumerator:`LV_EVENT_READY` Sent when :cpp:enumerator:`LV_KEY_ENTER` is + pressed (or sent) to a one-line Text Area. .. admonition:: Further Reading diff --git a/docs/details/widgets/tileview.rst b/docs/details/widgets/tileview.rst index c66d188b1..f24711bd6 100644 --- a/docs/details/widgets/tileview.rst +++ b/docs/details/widgets/tileview.rst @@ -4,27 +4,32 @@ Tile View (lv_tileview) ======================= + Overview ******** -The Tile view is a container Widget whose elements (called *tiles*) can +The Tile View is a container Widget whose elements (called *tiles*) can be arranged in grid form. A user can navigate between the tiles by swiping. Any direction of swiping can be disabled on the tiles individually to not allow moving from one tile to another. -If the Tile view is screen sized, the user interface resembles what you +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 :ref:`base_widget` container and +The Tile View is built from a :ref:`base_widget` container and :ref:`base_widget` tiles. The parts and styles work the same as for :ref:`base_widget`. + + .. _lv_tileview_usage: Usage @@ -34,19 +39,19 @@ Add a tile ---------- :cpp:expr:`lv_tileview_add_tile(tileview, col_id, row_id, dir)` creates a new -tile on the ``col_id``\ th column and ``row_id``\ th row. ``dir`` can be +tile on the ``col_id``\ -th column and ``row_id``\ -th row. ``dir`` can be ``LV_DIR_LEFT/RIGHT/TOP/BOTTOM/HOR/VER/ALL`` or OR-ed values to enable -moving to the adjacent tiles into the given direction by swiping. +moving to the adjacent tiles in the given direction by swiping. -The returned value is an ``lv_obj_t *`` on which the content of the tab -can be created. +The returned value is a pointer to the tile (a :ref:`base_widget`) on which the +content of the tab can be created. Change tile ----------- -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)` +The Tile View can scroll to a specified tile with +:cpp:expr:`lv_tileview_set_tile(tileview, tile, LV_ANIM_ON/OFF)` or +:cpp:expr:`lv_tileview_set_tile_by_index(tileview, col_id, row_id, LV_ANIM_ON/OFF)`. @@ -55,9 +60,9 @@ The Tile view can scroll to a tile with Events ****** -- :cpp:enumerator:`LV_EVENT_VALUE_CHANGED` Sent when a new tile loaded by scrolling. - :cpp:expr:`lv_tileview_get_tile_active(tabview)` can be used to get current - tile. +- :cpp:enumerator:`LV_EVENT_VALUE_CHANGED` Sent after a new tile is displayed by scrolling. + :cpp:expr:`lv_tileview_get_tile_active(tabview)` can be used within the event to + get a pointer to the newly-displayed tile. .. admonition:: Further Reading diff --git a/docs/details/widgets/win.rst b/docs/details/widgets/win.rst index e5b57e619..914c9ed5c 100644 --- a/docs/details/widgets/win.rst +++ b/docs/details/widgets/win.rst @@ -4,58 +4,89 @@ Window (lv_win) =============== + Overview ******** -The Window is container-like Widget built from a header with title and +The Window Widget is built from a header (like a title bar) 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 +The Window is built from other Widgets so you can check their documentation for details: - Background: :ref:`base_widget` - Header on the background: :ref:`base_widget` - Title on the header: :ref:`lv_label` - Buttons on the header: :ref:`lv_button` -- Content area on the background: :ref:`base_widget` +- Content Area on the background: :ref:`base_widget` + + .. _lv_win_usage: Usage ***** + Create a Window --------------- -:cpp:expr:`lv_win_create(parent, header_height)` creates a Window with an empty -header. +:cpp:expr:`lv_win_create(parent)` creates a Window that is initially +composed of the following Widget structure: + +- Background (a :ref:`base_widget`, the main window container), is set up to be a + Flex-Flow container that flows its contained Widgets vertically + (:cpp:enumerator:`LV_FLEX_FLOW_COLUMN`). + +- Header (like a title bar) is initially empty, and is a Flex-Flow container set up + to flow its contained Widgets horizontally (:cpp:enumerator:`LV_FLEX_FLOW_ROW`), + left to right. The Header occupies the full width of the Background (its parent) + and the top approximately 1/2 inch (according to :c:macro:`LV_DPI_DEF`). + +- Content Area (a :ref:`base_widget`) occupies the full width of the Background (its + parent) the remainder of the available Background area below the Header. It is + *not itself* a Flex-Flow container, but you can make it so if you wish. See + :ref:`flex` for details. + Title and buttons ----------------- -Any number of texts (but typically only one) can be added to the header -with :cpp:expr:`lv_win_add_title(win, "The title")`. +You can add Button and Label Widgets to the Header using these two functions. They +will be placed in the Header in left-to-right order as they are added. These +functions can be called in any order, any number of times. + +- :cpp:expr:`lv_win_add_title(win, "The title")` adds a Label to the header, with + long mode :c:enumerator:`LV_LABEL_LONG_DOT` so that if its text contents are wider + than the area it has, the text will be truncated with an ellipsis ("...") placed + at the end of the text. It is set to be FLEX GROW 1, so if it is the only Label + in the header, it will occupy all available space after any Buttons are added. + If more than one label is added, each label will share that space equally unless + its FLEX GROW value is altered. See :ref:`flex` for details about how this works. + Because of this, any buttons added after the last Label added will be "stacked" + on the far right of the Header. + +- :cpp:expr:`lv_win_add_button(win, icon, button_width)` adds a Button with the + specified width that occupies the full hight of the Header (its parent). If + ``icon`` is not NULL, an image is created, centered on the button, using ``icon`` + as its image source. All valid image sources are supported, but a common source + to use is one of the ``LV_SYMBOL_...`` macros, such as :c:macro:`LV_SYMBOL_CLOSE` + to provide an "x" (close) symbol. You get back a pointer to the Button created so + you can add an event callback with it and/or whatever else might be needed. -Control buttons can be added to the window's header with -:cpp:expr:`lv_win_add_button(win, icon, button_width)`. ``icon`` can be any image -source, and ``button_width`` is the width of the button. -The title and the buttons will be added in the order the functions are -called. So adding a button, a text and two other buttons will result in -a button on the left, a title, and 2 buttons on the right. The width of -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 -************* +Getting the parts +***************** :cpp:expr:`lv_win_get_header(win)` returns a pointer to the header, :cpp:expr:`lv_win_get_content(win)` returns a pointer to the content container @@ -69,7 +100,7 @@ Events ****** No special events are sent by Window Widgets, however events can be added -manually to the return value of :cpp:func:`lv_win_add_button`. +to any Buttons added. .. admonition:: Further Reading