From a77fbc574d1b937a042f5696f12b795781be656f Mon Sep 17 00:00:00 2001 From: Gabor Kiss-Vamosi Date: Wed, 19 May 2021 13:51:22 +0200 Subject: [PATCH] docs update some widgets' docs to v8 --- docs/widgets/extra/msgbox.md | 61 +++++++++-------- docs/widgets/extra/spinbox.md | 42 ++++++------ docs/widgets/extra/spinner.md | 35 +++------- docs/widgets/extra/tabview.md | 84 ++++++++---------------- docs/widgets/extra/tileview.md | 71 ++++---------------- docs/widgets/extra/win.md | 55 ++++++---------- examples/widgets/msgbox/index.rst | 10 +-- examples/widgets/spinbox/index.rst | 2 +- examples/widgets/spinner/index.rst | 2 +- examples/widgets/switch/index.rst | 2 +- examples/widgets/tabview/index.rst | 2 +- examples/widgets/tileview/index.rst | 2 +- examples/widgets/win/index.rst | 13 ++++ src/extra/widgets/spinbox/lv_spinbox.h | 16 ++--- src/extra/widgets/tabview/lv_tabview.c | 3 + src/extra/widgets/tabview/lv_tabview.h | 1 - src/extra/widgets/tileview/lv_tileview.c | 34 ++++++---- src/extra/widgets/tileview/lv_tileview.h | 2 + 18 files changed, 172 insertions(+), 265 deletions(-) create mode 100644 examples/widgets/win/index.rst diff --git a/docs/widgets/extra/msgbox.md b/docs/widgets/extra/msgbox.md index 0a65373d0..da327e0fd 100644 --- a/docs/widgets/extra/msgbox.md +++ b/docs/widgets/extra/msgbox.md @@ -1,55 +1,54 @@ ```eval_rst .. include:: /header.rst -:github_url: |github_link_base|/widgets/msgbox.md +:github_url: |github_link_base|/widgets/extra/msgbox.md ``` # Message box (lv_msgbox) ## Overview The Message boxes act as pop-ups. -They are built from a background [Container](/widgets/cont), a [Label](/widgets/label) and a [Button matrix](/widgets/btnmatrix) for buttons. +They are built from a background container, a title, an optional close button, a text and optional buttons. -The text will be broken into multiple lines automatically (has `LV_LABEL_LONG_MODE_BREAK`) and the height will be set automatically to involve the text and the buttons (`LV_FIT_TIGHT` fit vertically)- +The text will be broken into multiple lines automatically and the height will be set automatically to involve the text and the buttons. + +The message box can be a modal (block clicks on the rest of the screen) or not modal. ## Parts and Styles -The Message box's main part is called `LV_MSGBOX_PART_MAIN` and it uses all the typical background style properties. Using padding will add space on the sides. *pad_inner* will add space between the text and the buttons. -The *label* style properties affect the style of text. - -The buttons parts are the same as in case of [Button matrix](/widgets/btnmatrix): -- `LV_MSGBOX_PART_BTN_BG` the background of the buttons -- `LV_MSGBOX_PART_BTN` the buttons - +The mesasge box is built from other widgets so you can check these widget's documentation for details. +- Background: [lv_obj](/widgets/obj) +- Close button: [lv_btn](/widgets/core/btn) +- Title and text: [lv_label](/widgets/core/label) +- Buttons: [lv_btnmatrix](/widgets/core/btnmatrix) ## Usage +### Create a messaeg box -### Set text -To set the text use the `lv_msgbox_set_text(msgbox, "My text")` function. Not only the pointer of the text will be saved, so the the text can be in a local variable too. +`lv_msgbox_create(parent, title, txt, btn_txts[], add_close_btn)` creates a message box. -### Add buttons - To add buttons use the `lv_msgbox_add_btns(msgbox, btn_str)` function. The button's text needs to be specified like `const char * btn_str[] = {"Apply", "Close", ""}`. - For more information visit the [Button matrix](/widgets/btnmatrix) documentation. +If `parent` is `NULL` the message box will be a modal. `title` and `txt` are strings for the title and the text. +`btn_txts[]` is an array with the buttons' text. E.g. `const char * btn_txts[] = {"Ok", "Cancel", NULL}`. +`add_colse_btn` can be `true` or `false` to add/don't add a close button. - The button matrix will be created only when `lv_msgbox_add_btns()` is called for the first time. +### Get the parts +The building block of the message box can be get with the following functions: +```c +lv_obj_t * lv_msgbox_get_title(lv_obj_t * mbox); +lv_obj_t * lv_msgbox_get_close_btn(lv_obj_t * mbox); +lv_obj_t * lv_msgbox_get_text(lv_obj_t * mbox); +lv_obj_t * lv_msgbox_get_btns(lv_obj_t * mbox); +``` -### Auto-close -With `lv_msgbox_start_auto_close(mbox, delay)` the message box can be closed automatically after `delay` milliseconds with an animation. The `lv_mbox_stop_auto_close(mbox)` function stops a started auto close. - -The duration of the close animation can be set by `lv_mbox_set_anim_time(mbox, anim_time)`. +### Close the message box +`lv_msgbox_close(msgbox)` closes (deletes) the message box. ## Events -Besides the [Generic events](../overview/event.html#generic-events) the following [Special events](../overview/event.html#special-events) are sent by the Message boxes: - - **LV_EVENT_VALUE_CHANGED** sent when the button is clicked. The event data is set to ID of the clicked button. - -The Message box has a default event callback which closes itself when a button is clicked. +- `LV_EVENT_VALUE_CHANGED` is sent by the buttons if one of them is clicked. `LV_OBJ_FLAG_EVENT_BUBBLE` is enabled on the buttons so you can add events to the message box itself. +In the event `lv_event_get_target(e)` will give the button matrix, `lv_event_get_current_target(e)` will give the message box. `lv_msgbox_get_active_btn_text(msgbox)` can be used to get the text of the clicked button. Learn more about [Events](/overview/event). -##Keys - -The following *Keys* are processed by the Buttons: -- **LV_KEY_RIGHT/DOWN** Select the next button -- **LV_KEY_LEFT/TOP** Select the previous button -- **LV_KEY_ENTER** Clicks the selected button +## Keys +Keys have effect on the close button and button matrix. You can add them manually to a group if required. Learn more about [Keys](/overview/indev). @@ -58,7 +57,7 @@ Learn more about [Keys](/overview/indev). ```eval_rst -.. include:: /lv_examples/src/lv_ex_widgets/lv_ex_msgbox/index.rst +.. include:: ../../../examples/widgets/msgbox/index.rst ``` diff --git a/docs/widgets/extra/spinbox.md b/docs/widgets/extra/spinbox.md index 5b64a30f9..54742751b 100644 --- a/docs/widgets/extra/spinbox.md +++ b/docs/widgets/extra/spinbox.md @@ -1,53 +1,49 @@ ```eval_rst .. include:: /header.rst -:github_url: |github_link_base|/widgets/spinbox.md +:github_url: |github_link_base|/widgets/extra/spinbox.md ``` # Spinbox (lv_spinbox) ## 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](/widgets/textarea). +Under the hood the Spinbox is a modified [Text area](/widgets/core/textarea). ## Parts and Styles -The Spinbox's main part is called `LV_SPINBOX_PART_BG` which is a rectangle-like background using all the typical background style properties. It also describes the style of the label with its *text* style properties. +The parts of the Spinbox are identiacl to the [Text area](/widgets/core/textarea). -`LV_SPINBOX_PART_CURSOR` is a virtual part describing the cursor. Read the [Text area](/widgets/textarea) documentation for a detailed description. +### Value, range and step +`lv_spinbox_set_value(spinbox, 1234)` sets a new value on the Spinbox. -### Set format -`lv_spinbox_set_digit_format(spinbox, digit_count, separator_position)` set the format of the number. -`digit_count` sets the number of digits. Leading zeros are added to fill the space on the left. -`separator_position` sets the number of digit before the decimal point. `0` means no decimal point. +`lv_spinbox_increment(spinbox)` and `lv_spinbox_decrement(spinbox)` increments/decrements the value of the Spinbox according to the currently selected digit. -`lv_spinbox_set_padding_left(spinbox, cnt)` add `cnt` "space" characters between the sign an the most left digit. +`lv_spinbox_set_range(spinbox, -1000, 2500)` sets a range. If the value is changed by `lv_spinbox_set_value`, by *Keys*,`lv_spinbox_increment/decrement` this range will be respected. -### Value and ranges -`lv_spinbox_set_range(spinbox, min, max)` sets the range of the Spinbox. +`lv_spinbox_set_step(spinbox, 100)` sets which digits to change on increment/decrement. Only 10^n values values can be set, and not for example 3. -`lv_spinbox_set_value(spinbox, num)` sets the Spinbox's value manually. +### Format -`lv_spinbox_increment(spinbox)` and `lv_spinbox_decrement(spinbox)` increments/decrements the value of the Spinbox. +`lv_spinbox_set_digit_format(spinbox, digit_count, separator_position)` sets the number format. `digit_count` is the number of digit excluding the decimal separator and the sign. +`separator_position` is the number of digit before the decimal point. If 0, decimal point is not -`lv_spinbox_set_step(spinbox, step)` sets the amount to increment decrement. +### Rollover +`lv_spinbox_set_rollover(spinbox, true/false)` enables/disabled rolloiver mode. If the minimum or maximum values is reached with rollover the value will change to the other limit. +If not enabled the value will be reamain at the minimum or maximum value. ## Events -Besides the [Generic events](../overview/event.html#generic-events) the following [Special events](../overview/event.html#special-events) are sent by the Drop down lists: -- **LV_EVENT_VALUE_CHANGED** sent when the value has changed. (the value is set as event data as `int32_t`) -- **LV_EVENT_INSERT** sent by the ancestor Text area but shouldn't be used. +- `LV_EVENT_VALUE_CHANGED` Sent when the value has changed. Learn more about [Events](/overview/event). ## Keys -The following *Keys* are processed by the Buttons: -- **LV_KEY_LEFT/RIGHT** With *Keypad* move the cursor left/right. With *Encoder* decrement/increment the selected digit. -- **LY_KEY_ENTER** Apply the selected option (Send `LV_EVENT_VALUE_CHANGED` event and close the Drop down list) -- **LV_KEY_ENTER** With *Encoder* got the net digit. Jump to the first after the last. - +- `LV_KEY_LEFT/RIGHT` With *Keypad* move the cursor left/right. With *Encoder* decrement/increment the selected digit. +- `LV_KEY_UP/DOWN` With *Keypad* and *Encoder* increment/decrement the value. +- `LV_KEY_ENTER` With *Encoder* got the net digit. Jump to the first after the last. ## Example ```eval_rst -.. include:: /lv_examples/src/lv_ex_widgets/lv_ex_spinbox/index.rst +.. include:: ../../../examples/widgets/spinbox/index.rst ``` diff --git a/docs/widgets/extra/spinner.md b/docs/widgets/extra/spinner.md index d10058d2b..35ce7a763 100644 --- a/docs/widgets/extra/spinner.md +++ b/docs/widgets/extra/spinner.md @@ -1,42 +1,25 @@ ```eval_rst .. include:: /header.rst -:github_url: |github_link_base|/widgets/spinner.md +:github_url: |github_link_base|/widgets/extra/spinner.md ``` # Spinner (lv_spinner) ## Overview -The Spinner object is a spinning arc over a border. +The Spinner object is a spinning arc over a ring. ## Parts and Styles - -The Spinner uses the the following parts: -- `LV_SPINNER_PART_BG`: main part -- `LV_SPINNER_PART_INDIC`: the spinning arc (virtual part) - -The parts and style works the same as in case of [Arc](/widgets/arc). Read its documentation for a details description. +The parts are identical to the parts of [lv_arc](/widgets/core/arc). ## Usage -### Arc length -The length of the arc can be adjusted by `lv_spinner_set_arc_length(spinner, deg)`. - -### Spinning speed -The speed of the spinning can be adjusted by `lv_spinner_set_spin_time(preload, time_ms)`. - -### Spin types -You can choose from more spin types: -- **LV_SPINNER_TYPE_SPINNING_ARC** spin the arc, slow down on the top -- **LV_SPINNER_TYPE_FILLSPIN_ARC** spin the arc, slow down on the top but also stretch the arc -- **LV_SPINNER_TYPE_CONSTANT_ARC** spin the arc at a constant speed - -To apply one if them use `lv_spinner_set_type(preload, LV_SPINNER_TYPE_...)` - -### Spin direction -The direction of spinning can be changed with `lv_spinner_set_dir(preload, LV_SPINNER_DIR_FORWARD/BACKWARD)`. +### Create a spinner +To create spinner use `lv_spinner_create(parent, spin_time, arc_length)`. `spin time` set the spin time in milliseconds, `arc_length` sets the length of the spinning arc in degrees. ## Events -Only the [Generic events](../overview/event.html#generic-events) are sent by the object type. +No special events are sent the the Spinner. + +Learn more about [Events](/overview/events). ## Keys No *Keys* are processed by the object type. @@ -49,7 +32,7 @@ Learn more about [Keys](/overview/indev). ```eval_rst -.. include:: /lv_examples/src/lv_ex_widgets/lv_ex_spinner/index.rst +.. include:: ../../../examples/widgets/spinner/index.rst ``` diff --git a/docs/widgets/extra/tabview.md b/docs/widgets/extra/tabview.md index 78aa9a444..a17b561cb 100644 --- a/docs/widgets/extra/tabview.md +++ b/docs/widgets/extra/tabview.md @@ -1,6 +1,6 @@ ```eval_rst .. include:: /header.rst -:github_url: |github_link_base|/widgets/tabview.md +:github_url: |github_link_base|/widgets/extra/tabview.md ``` # Tabview (lv_tabview) @@ -8,81 +8,49 @@ ## Overview The Tab view object can be used to organize content in tabs. +The Tab view is built from other widgets like this: +- Main container: [lv_obj](/widgets/obj)) + - Tab buttons: [lv_btnmatrix](/widgets/core/btnmatrix) + - Container for the tabs: [lv_obj](/widgets/obj) + - Content of the tabs: [lv_obj](/widgets/obj) + +The tab buttons can be positioned on the topn, bottom, left and right side of teh Tab view. + +A new tab can be selected either clicking on a tab button or sliding horizontally on the content. ## Parts and Styles - -The Tab view object has several parts. The main is `LV_TABVIEW_PART_BG`. It a rectangle-like container which holds the other parts of the Tab view. - -On the background 2 important real parts are created: - -- `LV_TABVIEW_PART_BG_SCRL`: it's the scrollable part of [Page](/widgets/page). It holds the content of the tabs next to each other. The background of the Page is always transparent and can't be accessed externally. -- `LV_TABVIEW_PART_TAB_BG`: The tab buttons which is a [Button matrix](/widgets/btnmatrix). -Clicking on a button will scroll `LV_TABVIEW_PART_BG_SCRL` to the related tab's content. The tab buttons can be accessed via `LV_TABVIEW_PART_TAB_BTN`. When tabs are selected, the buttons are in the checked state, and can be styled using `LV_STATE_CHECKED`. -The height of the tab's button matrix is calculated from the font height plus padding of the background's and the button's style. - -All the listed parts supports the typical background style properties and padding. - -`LV_TABVIEW_PART_TAB_BG` has an additional real part, an indicator, called `LV_TABVIEW_PART_INDIC`. -It's a thin rectangle-like object under the currently selected tab. When the tab view is animated to an other tab the indicator will be animated too. -It can be styles using the typical background style properties. The *size* style property will set the its thickness. - -When a new tab is added a [Page](/widgets/page) is create for them on `LV_TABVIEW_PART_BG_SCRL` and a new button is added to `LV_TABVIEW_PART_TAB_BG` Button matrix. -The created Pages can be used as normal Pages and they have the usual Page parts. +There are no special parts on the Tab view but the `lv_obj` and `lv_btnnmatrix` widgets are used to build up the Tab view. ## Usage -### Adding tab +### Create a Tab view -New tabs can be added with `lv_tabview_add_tab(tabview, "Tab name")`. It will return with a pointer to a [Page](/widgets/page) object where the tab's content can be created. +`lv_tabview_create(parent, tab_pos, tab_size);` creates a new empty Tab view. `tab_pos` can be `LV_DIR_TOP/BOTTOM/LEFT/RIGHT` to position the tab buttons to a side. +`tab_size` is the height (in case of `LV_DIR_TOP/BOTTOM`) or width (in case of `LV_DIR_LEFT/RIGHT`) tab buttons. + +### Add tabs + +New tabs can be added with `lv_tabview_add_tab(tabview, "Tab name")`. It will return with a pointer to an [lv_obj](/widgets/obj) object where the tab's content can be created. ### Change tab To select a new tab you can: +- Click on its tab button +- Slide horizontally +- Use `lv_tabview_set_act(tabview, id, LV_ANIM_ON/OFF)` function -- Click on it on the Button matrix part -- Slide -- Use `lv_tabview_set_tab_act(tabview, id, LV_ANIM_ON/OFF)` function +### Get the parts -### Change tab's name - -To change the name (shown text of the underlying button matrix) of tab `id` during runtime the function `lv_tabview_set_tab_name(tabview, id, name)` can be used. - -### Tab button's position - -By default, the tab selector buttons are placed on the top of the Tab view. It can be changed with `lv_tabview_set_btns_pos(tabview, LV_TABVIEW_TAB_POS_TOP/BOTTOM/LEFT/RIGHT/NONE)` - -`LV_TABVIEW_TAB_POS_NONE` will hide the tabs. - -Note that, you can't change the tab position from top or bottom to left or right when tabs are already added. - -### Animation time - -The animation time is adjusted by `lv_tabview_set_anim_time(tabview, anim_time_ms)`. It is used when the new tab is loaded. - -### Scroll propagation - -As the tabs' content object is a Page it can receive scroll propagation from an other Page-like object. -For example, if a text area is created on the tab's content and that Text area is scrolled but it reached the end the scroll can be propagated to the content Page. -It can be enabled with `lv_page/textarea_set_scroll_propagation(obj, true)`. - -By default the tab's content Pages have enabled scroll propagation, therefore when they are scrolled horizontally the scroll is propagated to `LV_TABVIEW_PART_BG_SCRL` and this way the Pages will be scrolled. - -The manual sliding can be disabled with `lv_page_set_scroll_propagation(tab_page, false)`. +`lv_tabview_get_content(tabview)` return the container for the tabs, `lv_tabview_get_tab_btns(tabview)` returns the Tab buttons which is a [Button matrix](/widgets/core/btnmatrix). ## Events - -Besides the [Generic events](../overview/event.html#generic-events) the following [Special events](../overview/event.html#special-events) are sent by the Slider: - -- **LV_EVENT_VALUE_CHANGED** Sent when a new tab is selected by sliding or clicking the tab button +- `LV_EVENT_VALUE_CHANGED` Sent when a new tab is selected by sliding or clicking the tab button. `lv_tabview_get_tab_act(tabview)` returns the zero based index of the current tab. Learn more about [Events](/overview/event). ## Keys -The following *Keys* are processed by the Tabview: - -- **LV_KEY_RIGHT/LEFT** Select a tab -- **LV_KEY_ENTER** Change to the selected tab +Keys have effect only on the tab buttons (Button matrix). You can add it manually to a group if required. Learn more about [Keys](/overview/indev). @@ -90,7 +58,7 @@ Learn more about [Keys](/overview/indev). ```eval_rst -.. include:: /lv_examples/src/lv_ex_widgets/lv_ex_tabview/index.rst +.. include:: ../../../examples/widgets/tabview/index.rst ``` diff --git a/docs/widgets/extra/tileview.md b/docs/widgets/extra/tileview.md index 15f347e22..543e16dbb 100644 --- a/docs/widgets/extra/tileview.md +++ b/docs/widgets/extra/tileview.md @@ -6,78 +6,35 @@ ## Overview -The Tileview is a container object where its elements (called *tiles*) can be arranged in a grid form. +The Tile view is a container object where its elements (called *tiles*) can be arranged in a grid form. By swiping the user can navigate between the tiles. +Any direction of swiping can be disabled on the tiles individually to not allow moving from tile to an other. -If the Tileview is screen sized it gives a user interface you might have seen on the smartwatches. +If the Tile view is screen sized it gives a user interface you might have seen on the smartwatches. ## Parts and Styles +The Tile view is build from an [lv_obj](/widgets/obj) container and also [lv_obj](/widgets/obj) tiles. - -The Tileview has the same parts as [Page](/widgets/page). -Expect `LV_PAGE_PART_SCRL` because it can't be referenced and it's always transparent. -Refer the Page's documentation of details. +The parts and styles work the same as for [lv_obj](/widgets/obj). ## Usage -### Valid positions +### Add a tile -The tiles don't have to form a full grid where every element exists. -There can be holes in the grid but it has to be continuous, i.e. there can't be an empty rows or columns. +`lv_tileview_add_tile(tileview, row_id, col_id, dir)` creates a new tile on the `row_id`th row and `col_id`th column. +`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 with swiping. -With `lv_tileview_set_valid_positions(tileview, valid_pos_array, array_len)` the valid positions can be set. -Scrolling will be possible only to this positions. -The `0,0` index means the top left tile. -E.g. `lv_point_t valid_pos_array[] = {{0,0}, {0,1}, {1,1}, {{LV_COORD_MIN, LV_COORD_MIN}}` gives a Tile view with "L" shape. -It indicates that there is no tile in `{1,1}` therefore the user can't scroll there. +The returned value is an `lv_obj_t *` on which the content of the tab can be created. -In other words, the `valid_pos_array` tells where the tiles are. -It can be changed on the fly to disable some positions on specific tiles. -For example, there can be a 2x2 grid where all tiles are added but the first row (y = 0) as a "main row" and the second row (y = 1) contains options for the tile above it. -Let's say horizontal scrolling is possible only in the main row and not possible between the options in the second row. In this case the `valid_pos_array` needs to changed when a new main tile is selected: -- for the first main tile: `{0,0}, {0,1}, {1,0}` to disable the `{1,1}` option tile -- for the second main tile `{0,0}, {1,0}, {1,1}` to disable the `{0,1}` option tile +### Change tile +The Tile view can scroll to a tile with `lv_obj_set_tile(tileview, tile_obj, LV_ANIM_ON/OFF)` or `lv_obj_set_tile_id(tileviewv, col_id, row_id, LV_ANIM_ON/OFF);` -### Set tile - -To set the currently visible tile use `lv_tileview_set_tile_act(tileview, x_id, y_id, LV_ANIM_ON/OFF)`. - - -### Add element - -To add elements just create an object on the Tileview and position it manually to the desired position. - -`lv_tileview_add_element(tielview, element)` should be used to make possible to scroll (drag) the Tileview by one its element. -For example, if there is a button on a tile, the button needs to be explicitly added to the Tileview to enable the user to scroll the Tileview with the button too. - - -### Scroll propagation -The scroll propagation feature of page-like objects (like [List](/widgets/list)) can be used very well here. -For example, there can be a full-sized List and when it reaches the top or bottom most position the user will scroll the tile view instead. - - -### Animation time - -The animation time of the Tileview can be adjusted with `lv_tileview_set_anim_time(tileview, anim_time)`. - -Animations are applied when -- a new tile is selected with `lv_tileview_set_tile_act` -- the current tile is scrolled a little and then released (revert the original title) -- the current tile is scrolled more than half size and then released (move to the next tile) - -### Edge flash - -An "edge flash" effect can be added when the tile view reached hits an invalid position or the end of tile view when scrolled. - -Use `lv_tileview_set_edge_flash(tileview, true)` to enable this feature. ## Events -Besides the [Generic events](../overview/event.html#generic-events) the following [Special events](../overview/event.html#special-events) are sent by the Slider: -- **LV_EVENT_VALUE_CHANGED** Sent when a new tile loaded either with scrolling or `lv_tileview_set_act`. The event data is set ti the index of the new tile in `valid_pos_array` (It's type is `uint32_t *`) +- `LV_EVENT_VALUE_CHANGED` Sent when a new tile loaded either with scrolling. `lv_tileview_get_tile_act(tabview)` can be used to get current tile. ## Keys -- **LV_KEY_UP**, **LV_KEY_RIGHT** Increment the slider's value by 1 -- **LV_KEY_DOWN**, **LV_KEY_LEFT** Decrement the slider's value by 1 +*Keys* are not handled by the Tile view. Learn more about [Keys](/overview/indev). @@ -86,7 +43,7 @@ Learn more about [Keys](/overview/indev). ```eval_rst -.. include:: /lv_examples/src/lv_ex_widgets/lv_ex_tileview/index.rst +.. include:: ../../../examples/widgets/tileview/index.rst ``` diff --git a/docs/widgets/extra/win.md b/docs/widgets/extra/win.md index 33d59f899..fdd92606c 100644 --- a/docs/widgets/extra/win.md +++ b/docs/widgets/extra/win.md @@ -7,58 +7,41 @@ ## Overview The Window is container-like objects built from a header with title and button and a content area. - ## Parts and Styles -The main part is `LV_WIN_PART_BG` which holds the two other real parts: -1. `LV_WIN_PART_HEADER`: a header [Container](/widgets/cont) on the top with a title and control buttons -2. `LV_WIN_PART_CONTENT_SCRL` the scrollable part of a [Page](/widgets/page) for the content below the header. +The Window is built from other widgets so you can check these widget's documentation for details: +- Background: [lv_obj](/widgets/obj) +- Header on the background: [lv_obj](/widgets/obj) +- Title on the header: [lv_label](/widgets/core/label) +- Buttons on the header: [lv_btn](/widgets/core/btn) +- Content area on the background: [lv_obj](/widgets/obj) -Besides these, `LV_WIN_PART_CONTENT_SCRL` has a scrollbar part called `LV_WIN_PART_CONTENT_SCRL`. -Read the documentation of [Page](/widgets/page) for more details on the scrollbars. +## Usage -All parts supports the typical background properties. The title uses the *Text* properties of the header part. - -The height of the control buttons is: *header height - header padding_top - header padding_bottom*. - +### Create a Window -### Title -On the header, there is a title which can be modified by: `lv_win_set_title(win, "New title")`. +`lv_win_create(parent, header_height)` creates a Window with am empty header. -### Control buttons -Control buttons can be added to the right of the window header with: `lv_win_add_btn_right(win, LV_SYMBOL_CLOSE)`, to add a button to the left side of the window header use `lv_win_add_btn_left(win, LV_SYMBOL_CLOSE)` instead. -The second parameter is an [Image](/widgets/img) source so it can be a symbol, a pointer to an `lv_img_dsc_t `variable or a path to file. +### Title and buttons -The width of the buttons can be set with `lv_win_set_btn_width(win, w)`. If `w == 0` the buttons will be square-shaped. +Any number of text's (but typically only one) can be added to the header with `lv_win_add_title(win, "The title")`. -`lv_win_close_event_cb` can be used as an event callback to close the Window. +Control buttons can be added to the window's header with `lv_win_add_btn_right(win, icon, btn_width)`. `icon` can be any image source, and `btn_width` is the width of the button. -### Scrollbars +The title and the buttons will be added in the order of the functions are called. So adding a button, a text and two other buttons will result in a button on the left, a title, ant 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 the buttons to the right added after the title. -The scrollbar behavior can be set by `lv_win_set_scrlbar_mode(win, LV_SCRLBAR_MODE_...)`. -See [Page](/widgets/page) for details. - -### Manual scroll and focus -To scroll the Window directly you can use `lv_win_scroll_hor(win, dist_px)` or `lv_win_scroll_ver(win, dist_px)`. - -To make the Window show an object on it use `lv_win_focus(win, child, LV_ANIM_ON/OFF)`. - -The time of scroll and focus animations can be adjusted with `lv_win_set_anim_time(win, anim_time_ms)` - -### Layout -To set a layout for the content use `lv_win_set_layout(win, LV_LAYOUT_...)`. -See [Container](/widgets/cont) for details. +## Get the parts +`lv_win_get_header(win)` return a pointer to the header, `lv_win_get_content(win)` returns a pointer to the content container to which the content of the window can be added. ## Events -Only the [Generic events](../overview/event.html#generic-events) are sent by the object type. +No special events are sent by the windows, however events can be added manually to the return value of `lv_win_add_btn_right`. Learn more about [Events](/overview/event). ## Keys - -The following *Keys* are processed by the Page: -- **LV_KEY_RIGHT/LEFT/UP/DOWN** Scroll the page +No *Keys* are handled by the window. Learn more about [Keys](/overview/indev). @@ -67,7 +50,7 @@ Learn more about [Keys](/overview/indev). ```eval_rst -.. include:: /lv_examples/src/lv_ex_widgets/lv_ex_win/index.rst +.. include:: ../../../examples/widgets/win/index.rst ``` diff --git a/examples/widgets/msgbox/index.rst b/examples/widgets/msgbox/index.rst index 279e5188a..44e4019be 100644 --- a/examples/widgets/msgbox/index.rst +++ b/examples/widgets/msgbox/index.rst @@ -4,15 +4,7 @@ C Simple Message box """"""""""""""""""" -.. lv_example:: lv_ex_widgets/lv_ex_msgbox/lv_ex_msgbox_1 - :language: c - - - -Modal -"""""""""""""""" - -.. lv_example:: lv_ex_widgets/lv_ex_msgbox/lv_ex_msgbox_2 +.. lv_example:: widgets/msgbox/lv_example_msgbox_1 :language: c diff --git a/examples/widgets/spinbox/index.rst b/examples/widgets/spinbox/index.rst index f56a5fae0..c7c6767b3 100644 --- a/examples/widgets/spinbox/index.rst +++ b/examples/widgets/spinbox/index.rst @@ -4,7 +4,7 @@ C Simple Spinbox """"""""""""""""""""""" -.. lv_example:: lv_ex_widgets/lv_ex_spinbox/lv_ex_spinbox_1 +.. lv_example:: widgets/spinbox/lv_example_spinbox_1 :language: c MicroPython diff --git a/examples/widgets/spinner/index.rst b/examples/widgets/spinner/index.rst index 7e3b37a2f..556084f66 100644 --- a/examples/widgets/spinner/index.rst +++ b/examples/widgets/spinner/index.rst @@ -4,7 +4,7 @@ C Simple spinner """""""""""""""""""""""""""" -.. lv_example:: lv_ex_widgets/lv_ex_spinner/lv_ex_spinner_1 +.. lv_example:: widgets/spinner/lv_example_spinner_1 :language: c MicroPython diff --git a/examples/widgets/switch/index.rst b/examples/widgets/switch/index.rst index 802ca98db..2ac076fa6 100644 --- a/examples/widgets/switch/index.rst +++ b/examples/widgets/switch/index.rst @@ -4,7 +4,7 @@ C Simple Switch """"""""""""""""""""""" -.. lv_example:: widgets/lv_example_switch/lv_example_switch_1 +.. lv_example:: widgets/switch/lv_example_switch_1 :language: c MicroPython diff --git a/examples/widgets/tabview/index.rst b/examples/widgets/tabview/index.rst index f246558c5..1ca60b161 100644 --- a/examples/widgets/tabview/index.rst +++ b/examples/widgets/tabview/index.rst @@ -4,7 +4,7 @@ C Simple Tabview """"""""""""""""""""""" -.. lv_example:: lv_ex_widgets/lv_ex_tabview/lv_ex_tabview_1 +.. lv_example:: widgets/tabview/lv_example_tabview_1 :language: c diff --git a/examples/widgets/tileview/index.rst b/examples/widgets/tileview/index.rst index 09463fde1..751a70790 100644 --- a/examples/widgets/tileview/index.rst +++ b/examples/widgets/tileview/index.rst @@ -4,7 +4,7 @@ C Tileview with content """"""""""""""""""""""""""" -.. lv_example:: lv_ex_widgets/lv_ex_tileview/lv_ex_tileview_1 +.. lv_example:: widgets/tileview/lv_example_tileview_1 :language: c MicroPython diff --git a/examples/widgets/win/index.rst b/examples/widgets/win/index.rst new file mode 100644 index 000000000..5064612d8 --- /dev/null +++ b/examples/widgets/win/index.rst @@ -0,0 +1,13 @@ +C +^ + +Simple window +""""""""""""""" + +.. lv_example:: widgets/win/lv_example_win_1 + :language: c + +MicroPython +^^^^^^^^^^^ + +No examples yet. diff --git a/src/extra/widgets/spinbox/lv_spinbox.h b/src/extra/widgets/spinbox/lv_spinbox.h index bade3b6bc..92000a042 100644 --- a/src/extra/widgets/spinbox/lv_spinbox.h +++ b/src/extra/widgets/spinbox/lv_spinbox.h @@ -61,13 +61,6 @@ lv_obj_t * lv_spinbox_create(lv_obj_t * parent); * Setter functions *====================*/ -/** - * Set spinbox rollover function - * @param spinbox pointer to spinbox - * @param b true or false to enable or disable (default) - */ -void lv_spinbox_set_rollover(lv_obj_t * obj, bool b); - /** * Set spinbox value * @param spinbox pointer to spinbox @@ -75,6 +68,13 @@ void lv_spinbox_set_rollover(lv_obj_t * obj, bool b); */ void lv_spinbox_set_value(lv_obj_t * obj, int32_t i); +/** + * Set spinbox rollover function + * @param spinbox pointer to spinbox + * @param b true or false to enable or disable (default) + */ +void lv_spinbox_set_rollover(lv_obj_t * obj, bool b); + /** * Set spinbox digit format (digit count and decimal format) * @param spinbox pointer to spinbox @@ -87,7 +87,7 @@ void lv_spinbox_set_digit_format(lv_obj_t * obj, uint8_t digit_count, uint8_t se /** * Set spinbox step * @param spinbox pointer to spinbox - * @param step steps on increment/decrement + * @param step steps on increment/decrement. Can be 1, 10, 100, 1000, etc the digit that will change. */ void lv_spinbox_set_step(lv_obj_t * obj, uint32_t step); diff --git a/src/extra/widgets/tabview/lv_tabview.c b/src/extra/widgets/tabview/lv_tabview.c index c5ed85873..240bca756 100644 --- a/src/extra/widgets/tabview/lv_tabview.c +++ b/src/extra/widgets/tabview/lv_tabview.c @@ -258,6 +258,8 @@ static void btns_value_changed_event_cb(lv_event_t * e) lv_obj_t * tv = lv_obj_get_parent(btns); uint32_t id = lv_btnmatrix_get_selected_btn(btns); lv_tabview_set_act(tv, id, LV_ANIM_ON); + + lv_event_send(tv, LV_EVENT_VALUE_CHANGED, NULL); } static void cont_scroll_end_event_cb(lv_event_t * e) { @@ -272,5 +274,6 @@ static void cont_scroll_end_event_cb(lv_event_t * e) lv_coord_t t = (p.x + w/ 2) / w; if(t < 0) t = 0; lv_tabview_set_act(tv, t, LV_ANIM_ON); + lv_event_send(tv, LV_EVENT_VALUE_CHANGED, NULL); } #endif /*LV_USE_TABVIEW*/ diff --git a/src/extra/widgets/tabview/lv_tabview.h b/src/extra/widgets/tabview/lv_tabview.h index c7773d487..4cfc4971b 100644 --- a/src/extra/widgets/tabview/lv_tabview.h +++ b/src/extra/widgets/tabview/lv_tabview.h @@ -41,7 +41,6 @@ extern const lv_obj_class_t lv_tabview_class; **********************/ lv_obj_t * lv_tabview_create(lv_obj_t * parent, lv_dir_t tab_pos, lv_coord_t tab_size); - lv_obj_t * lv_tabview_add_tab(lv_obj_t * tv, const char * name); lv_obj_t * lv_tabview_get_content(lv_obj_t * tv); diff --git a/src/extra/widgets/tileview/lv_tileview.c b/src/extra/widgets/tileview/lv_tileview.c index 21cd55d3a..b7fd20e94 100644 --- a/src/extra/widgets/tileview/lv_tileview.c +++ b/src/extra/widgets/tileview/lv_tileview.c @@ -72,14 +72,17 @@ lv_obj_t * lv_tileview_add_tile(lv_obj_t * tv, uint8_t col_id, uint8_t row_id, l return obj; } -void lv_obj_set_tile(lv_obj_t * tv, lv_obj_t * tile_obj, lv_anim_enable_t anim_en) +void lv_obj_set_tile(lv_obj_t * obj, lv_obj_t * tile_obj, lv_anim_enable_t anim_en) { lv_coord_t tx = lv_obj_get_x(tile_obj); lv_coord_t ty = lv_obj_get_y(tile_obj); lv_tileview_tile_t * tile = (lv_tileview_tile_t *)tile_obj; - lv_obj_set_scroll_dir(tv, tile->dir); - lv_obj_scroll_to(tv, tx, ty, anim_en); + lv_tileview_t * tv = (lv_tileview_t *) obj; + tv->tile_act = (lv_obj_t *)tile; + + lv_obj_set_scroll_dir(obj, tile->dir); + lv_obj_scroll_to(obj, tx, ty, anim_en); } void lv_obj_set_tile_id(lv_obj_t * tv, uint32_t col_id, uint32_t row_id, lv_anim_enable_t anim_en) @@ -104,6 +107,12 @@ void lv_obj_set_tile_id(lv_obj_t * tv, uint32_t col_id, uint32_t row_id, lv_anim LV_LOG_WARN("No tile found with at (%d,%d) index", col_id, row_id); } +lv_obj_t * lv_tileview_get_tile_act(lv_obj_t * obj) +{ + lv_tileview_t * tv = (lv_tileview_t *) obj; + return tv->tile_act; +} + /********************** * STATIC FUNCTIONS **********************/ @@ -137,33 +146,36 @@ static void lv_tileview_tile_constructor(const lv_obj_class_t * class_p, lv_obj_ static void tileview_event_cb(lv_event_t * e) { lv_event_code_t code = lv_event_get_code(e); - lv_obj_t * tv = lv_event_get_target(e); + lv_obj_t * obj = lv_event_get_target(e); + lv_tileview_t * tv = (lv_tileview_t *) obj; + if(code == LV_EVENT_SCROLL_END) { - lv_coord_t w = lv_obj_get_content_width(tv); - lv_coord_t h = lv_obj_get_content_height(tv); + lv_coord_t w = lv_obj_get_content_width(obj); + lv_coord_t h = lv_obj_get_content_height(obj); lv_point_t scroll_end; - lv_obj_get_scroll_end(tv, &scroll_end); + lv_obj_get_scroll_end(obj, &scroll_end); lv_coord_t left = scroll_end.x; lv_coord_t top = scroll_end.y; lv_coord_t tx = ((left + (w / 2)) / w) * w; lv_coord_t ty = ((top + (h / 2)) / h) * h; - lv_dir_t dir = LV_DIR_ALL; uint32_t i; - for(i = 0; i < lv_obj_get_child_cnt(tv); i++) { - lv_obj_t * tile_obj = lv_obj_get_child(tv, i); + for(i = 0; i < lv_obj_get_child_cnt(obj); i++) { + lv_obj_t * tile_obj = lv_obj_get_child(obj, i); lv_coord_t x = lv_obj_get_x(tile_obj); lv_coord_t y = lv_obj_get_y(tile_obj); if(x == tx && y == ty) { lv_tileview_tile_t * tile = (lv_tileview_tile_t *)tile_obj; + tv->tile_act = (lv_obj_t *)tile; dir = tile->dir; + lv_event_send(obj, LV_EVENT_VALUE_CHANGED, NULL); break; } } - lv_obj_set_scroll_dir(tv, dir); + lv_obj_set_scroll_dir(obj, dir); } } #endif /*LV_USE_TILEVIEW*/ diff --git a/src/extra/widgets/tileview/lv_tileview.h b/src/extra/widgets/tileview/lv_tileview.h index 8fdb8d1e0..79f1acd46 100644 --- a/src/extra/widgets/tileview/lv_tileview.h +++ b/src/extra/widgets/tileview/lv_tileview.h @@ -26,6 +26,7 @@ extern "C" { **********************/ typedef struct { lv_obj_t obj; + lv_obj_t * tile_act; }lv_tileview_t; typedef struct { @@ -52,6 +53,7 @@ lv_obj_t * lv_tileview_add_tile(lv_obj_t * tv, uint8_t row_id, uint8_t col_id, l void lv_obj_set_tile(lv_obj_t * tv, lv_obj_t * tile_obj, lv_anim_enable_t anim_en); void lv_obj_set_tile_id(lv_obj_t * tv, uint32_t col_id, uint32_t row_id, lv_anim_enable_t anim_en); +lv_obj_t * lv_tileview_get_tile_act(lv_obj_t * obj); /*===================== * Other functions