Embedded/lvgl
1
0
Fork 0
mirror of https://github.com/lvgl/lvgl.git synced 2025-01-28 07:03:00 +08:00
Code Issues Projects Releases Wiki Activity

docs update some widgets' docs to v8

Browse Source
This commit is contained in:
Gabor Kiss-Vamosi 2021-05-19 13:51:22 +02:00
parent 32d742cf52
commit a77fbc574d
18 changed files with 172 additions and 265 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

61
docs/widgets/extra/msgbox.md
View File

@ -1,55 +1,54 @@
```eval_rst ```eval_rst
.. include:: /header.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) # Message box (lv_msgbox)
## Overview ## Overview
The Message boxes act as pop-ups. 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 ## 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 mesasge box is built from other widgets so you can check these widget's documentation for details.
The *label* style properties affect the style of text. - Background: [lv_obj](/widgets/obj)
- Close button: [lv_btn](/widgets/core/btn)
The buttons parts are the same as in case of [Button matrix](/widgets/btnmatrix): - Title and text: [lv_label](/widgets/core/label)
- `LV_MSGBOX_PART_BTN_BG` the background of the buttons - Buttons: [lv_btnmatrix](/widgets/core/btnmatrix)
- `LV_MSGBOX_PART_BTN` the buttons
## Usage ## Usage
### Create a messaeg box
### Set text `lv_msgbox_create(parent, title, txt, btn_txts[], add_close_btn)` creates a message box.
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.
### Add buttons If `parent` is `NULL` the message box will be a modal. `title` and `txt` are strings for the title and the text.
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", ""}`. `btn_txts[]` is an array with the buttons' text. E.g. `const char * btn_txts[] = {"Ok", "Cancel", NULL}`.
For more information visit the [Button matrix](/widgets/btnmatrix) documentation. `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 ### Close the message box
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. `lv_msgbox_close(msgbox)` closes (deletes) the message box.
The duration of the close animation can be set by `lv_mbox_set_anim_time(mbox, anim_time)`.
## Events ## 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` 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.
- **LV_EVENT_VALUE_CHANGED** sent when the button is clicked. The event data is set to ID of the clicked button. 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.
The Message box has a default event callback which closes itself when a button is clicked.
Learn more about [Events](/overview/event). Learn more about [Events](/overview/event).
##Keys ## Keys
Keys have effect on the close button and button matrix. You can add them manually to a group if required.
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
Learn more about [Keys](/overview/indev). Learn more about [Keys](/overview/indev).
@ -58,7 +57,7 @@ Learn more about [Keys](/overview/indev).
```eval_rst ```eval_rst
.. include:: /lv_examples/src/lv_ex_widgets/lv_ex_msgbox/index.rst .. include:: ../../../examples/widgets/msgbox/index.rst
``` ```

42
docs/widgets/extra/spinbox.md
View File

@ -1,53 +1,49 @@
```eval_rst ```eval_rst
.. include:: /header.rst .. include:: /header.rst
:github_url: |github_link_base|/widgets/spinbox.md :github_url: |github_link_base|/widgets/extra/spinbox.md
``` ```
# Spinbox (lv_spinbox) # Spinbox (lv_spinbox)
## Overview ## Overview
The Spinbox contains a number as text which can be increased or decreased by *Keys* or API functions. 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 ## 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_increment(spinbox)` and `lv_spinbox_decrement(spinbox)` increments/decrements the value of the Spinbox according to the currently selected digit.
`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_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_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_range(spinbox, min, max)` sets the range of the Spinbox.
`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 ## 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.
- **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.
Learn more about [Events](/overview/event). Learn more about [Events](/overview/event).
## Keys ## 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.
- **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.
- **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_ENTER** With *Encoder* got the net digit. Jump to the first after the last.
## Example ## Example
```eval_rst ```eval_rst
.. include:: /lv_examples/src/lv_ex_widgets/lv_ex_spinbox/index.rst .. include:: ../../../examples/widgets/spinbox/index.rst
``` ```

35
docs/widgets/extra/spinner.md
View File

@ -1,42 +1,25 @@
```eval_rst ```eval_rst
.. include:: /header.rst .. include:: /header.rst
:github_url: |github_link_base|/widgets/spinner.md :github_url: |github_link_base|/widgets/extra/spinner.md
``` ```
# Spinner (lv_spinner) # Spinner (lv_spinner)
## Overview ## Overview
The Spinner object is a spinning arc over a border. The Spinner object is a spinning arc over a ring.
## Parts and Styles ## Parts and Styles
The parts are identical to the parts of [lv_arc](/widgets/core/arc).
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.
## Usage ## Usage
### Arc length ### Create a spinner
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)`.
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 ## 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 ## Keys
No *Keys* are processed by the object type. No *Keys* are processed by the object type.
@ -49,7 +32,7 @@ Learn more about [Keys](/overview/indev).
```eval_rst ```eval_rst
.. include:: /lv_examples/src/lv_ex_widgets/lv_ex_spinner/index.rst .. include:: ../../../examples/widgets/spinner/index.rst
``` ```

84
docs/widgets/extra/tabview.md
View File

@ -1,6 +1,6 @@
```eval_rst ```eval_rst
.. include:: /header.rst .. include:: /header.rst
:github_url: |github_link_base|/widgets/tabview.md :github_url: |github_link_base|/widgets/extra/tabview.md
``` ```
# Tabview (lv_tabview) # Tabview (lv_tabview)
@ -8,81 +8,49 @@
## Overview ## Overview
The Tab view object can be used to organize content in tabs. 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 ## Parts and Styles
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.
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.
## Usage ## 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 ### Change tab
To select a new tab you can: 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 ### Get the parts
- Slide
- Use `lv_tabview_set_tab_act(tabview, id, LV_ANIM_ON/OFF)` function
### Change tab's name `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).
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)`.
## Events ## Events
- `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.
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
Learn more about [Events](/overview/event). Learn more about [Events](/overview/event).
## Keys ## Keys
The following *Keys* are processed by the Tabview: Keys have effect only on the tab buttons (Button matrix). You can add it manually to a group if required.
- **LV_KEY_RIGHT/LEFT** Select a tab
- **LV_KEY_ENTER** Change to the selected tab
Learn more about [Keys](/overview/indev). Learn more about [Keys](/overview/indev).
@ -90,7 +58,7 @@ Learn more about [Keys](/overview/indev).
```eval_rst ```eval_rst
.. include:: /lv_examples/src/lv_ex_widgets/lv_ex_tabview/index.rst .. include:: ../../../examples/widgets/tabview/index.rst
``` ```

71
docs/widgets/extra/tileview.md
View File

@ -6,78 +6,35 @@
## Overview ## 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. 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 ## Parts and Styles
The Tile view is build from an [lv_obj](/widgets/obj) container and also [lv_obj](/widgets/obj) tiles.
The parts and styles work the same as for [lv_obj](/widgets/obj).
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.
## Usage ## Usage
### Valid positions ### Add a tile
The tiles don't have to form a full grid where every element exists. `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.
There can be holes in the grid but it has to be continuous, i.e. there can't be an empty rows or columns. `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. The returned value is an `lv_obj_t *` on which the content of the tab can be created.
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.
In other words, the `valid_pos_array` tells where the tiles are. ### Change tile
It can be changed on the fly to disable some positions on specific tiles. 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);`
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
### 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 ## 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. `lv_tileview_get_tile_act(tabview)` can be used to get current tile.
- **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 *`)
## Keys ## Keys
- **LV_KEY_UP**, **LV_KEY_RIGHT** Increment the slider's value by 1 *Keys* are not handled by the Tile view.
- **LV_KEY_DOWN**, **LV_KEY_LEFT** Decrement the slider's value by 1
Learn more about [Keys](/overview/indev). Learn more about [Keys](/overview/indev).
@ -86,7 +43,7 @@ Learn more about [Keys](/overview/indev).
```eval_rst ```eval_rst
.. include:: /lv_examples/src/lv_ex_widgets/lv_ex_tileview/index.rst .. include:: ../../../examples/widgets/tileview/index.rst
``` ```

55
docs/widgets/extra/win.md
View File

@ -7,58 +7,41 @@
## Overview ## Overview
The Window is container-like objects built from a header with title and button and a content area. The Window is container-like objects built from a header with title and button and a content area.
## Parts and Styles ## Parts and Styles
The main part is `LV_WIN_PART_BG` which holds the two other real parts: The Window is built from other widgets so you can check these widget's documentation for details:
1. `LV_WIN_PART_HEADER`: a header [Container](/widgets/cont) on the top with a title and control buttons - Background: [lv_obj](/widgets/obj)
2. `LV_WIN_PART_CONTENT_SCRL` the scrollable part of a [Page](/widgets/page) for the content below the header. - 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`. ## Usage
Read the documentation of [Page](/widgets/page) for more details on the scrollbars.
All parts supports the typical background properties. The title uses the *Text* properties of the header part. ### Create a Window
The height of the control buttons is: *header height - header padding_top - header padding_bottom*.
### Title `lv_win_create(parent, header_height)` creates a Window with am empty header.
On the header, there is a title which can be modified by: `lv_win_set_title(win, "New title")`.
### Control buttons ### Title and 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.
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_...)`. ## Get the parts
See [Page](/widgets/page) for details. `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.
### 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.
## Events ## 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). Learn more about [Events](/overview/event).
## Keys ## Keys
No *Keys* are handled by the window.
The following *Keys* are processed by the Page:
- **LV_KEY_RIGHT/LEFT/UP/DOWN** Scroll the page
Learn more about [Keys](/overview/indev). Learn more about [Keys](/overview/indev).
@ -67,7 +50,7 @@ Learn more about [Keys](/overview/indev).
```eval_rst ```eval_rst
.. include:: /lv_examples/src/lv_ex_widgets/lv_ex_win/index.rst .. include:: ../../../examples/widgets/win/index.rst
``` ```

10
examples/widgets/msgbox/index.rst
View File

@ -4,15 +4,7 @@ C
Simple Message box Simple Message box
""""""""""""""""""" """""""""""""""""""
.. lv_example:: lv_ex_widgets/lv_ex_msgbox/lv_ex_msgbox_1 .. lv_example:: widgets/msgbox/lv_example_msgbox_1
:language: c
Modal
""""""""""""""""
.. lv_example:: lv_ex_widgets/lv_ex_msgbox/lv_ex_msgbox_2
:language: c :language: c

2
examples/widgets/spinbox/index.rst
View File

@ -4,7 +4,7 @@ C
Simple Spinbox Simple Spinbox
""""""""""""""""""""""" """""""""""""""""""""""
.. lv_example:: lv_ex_widgets/lv_ex_spinbox/lv_ex_spinbox_1 .. lv_example:: widgets/spinbox/lv_example_spinbox_1
:language: c :language: c
MicroPython MicroPython

2
examples/widgets/spinner/index.rst
View File

@ -4,7 +4,7 @@ C
Simple spinner Simple spinner
"""""""""""""""""""""""""""" """"""""""""""""""""""""""""
.. lv_example:: lv_ex_widgets/lv_ex_spinner/lv_ex_spinner_1 .. lv_example:: widgets/spinner/lv_example_spinner_1
:language: c :language: c
MicroPython MicroPython

2
examples/widgets/switch/index.rst
View File

@ -4,7 +4,7 @@ C
Simple Switch Simple Switch
""""""""""""""""""""""" """""""""""""""""""""""
.. lv_example:: widgets/lv_example_switch/lv_example_switch_1 .. lv_example:: widgets/switch/lv_example_switch_1
:language: c :language: c
MicroPython MicroPython

2
examples/widgets/tabview/index.rst
View File

@ -4,7 +4,7 @@ C
Simple Tabview Simple Tabview
""""""""""""""""""""""" """""""""""""""""""""""
.. lv_example:: lv_ex_widgets/lv_ex_tabview/lv_ex_tabview_1 .. lv_example:: widgets/tabview/lv_example_tabview_1
:language: c :language: c

2
examples/widgets/tileview/index.rst
View File

@ -4,7 +4,7 @@ C
Tileview with content 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 :language: c
MicroPython MicroPython

13
examples/widgets/win/index.rst Normal file
View File

@ -0,0 +1,13 @@
C
^
Simple window
"""""""""""""""
.. lv_example:: widgets/win/lv_example_win_1
:language: c
MicroPython
^^^^^^^^^^^
No examples yet.

16
src/extra/widgets/spinbox/lv_spinbox.h
View File

@ -61,13 +61,6 @@ lv_obj_t * lv_spinbox_create(lv_obj_t * parent);
* Setter functions * 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 * Set spinbox value
* @param spinbox pointer to spinbox * @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); 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) * Set spinbox digit format (digit count and decimal format)
* @param spinbox pointer to spinbox * @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 * Set spinbox step
* @param spinbox pointer to spinbox * @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); void lv_spinbox_set_step(lv_obj_t * obj, uint32_t step);

3
src/extra/widgets/tabview/lv_tabview.c
View File

@ -258,6 +258,8 @@ static void btns_value_changed_event_cb(lv_event_t * e)
lv_obj_t * tv = lv_obj_get_parent(btns); lv_obj_t * tv = lv_obj_get_parent(btns);
uint32_t id = lv_btnmatrix_get_selected_btn(btns); uint32_t id = lv_btnmatrix_get_selected_btn(btns);
lv_tabview_set_act(tv, id, LV_ANIM_ON); 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) 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; lv_coord_t t = (p.x + w/ 2) / w;
if(t < 0) t = 0; if(t < 0) t = 0;
lv_tabview_set_act(tv, t, LV_ANIM_ON); lv_tabview_set_act(tv, t, LV_ANIM_ON);
lv_event_send(tv, LV_EVENT_VALUE_CHANGED, NULL);
} }
#endif /*LV_USE_TABVIEW*/ #endif /*LV_USE_TABVIEW*/

1
src/extra/widgets/tabview/lv_tabview.h
View File

@ -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_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_add_tab(lv_obj_t * tv, const char * name);
lv_obj_t * lv_tabview_get_content(lv_obj_t * tv); lv_obj_t * lv_tabview_get_content(lv_obj_t * tv);

34
src/extra/widgets/tileview/lv_tileview.c
View File

@ -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; 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 tx = lv_obj_get_x(tile_obj);
lv_coord_t ty = lv_obj_get_y(tile_obj); lv_coord_t ty = lv_obj_get_y(tile_obj);
lv_tileview_tile_t * tile = (lv_tileview_tile_t *)tile_obj; lv_tileview_tile_t * tile = (lv_tileview_tile_t *)tile_obj;
lv_obj_set_scroll_dir(tv, tile->dir); lv_tileview_t * tv = (lv_tileview_t *) obj;
lv_obj_scroll_to(tv, tx, ty, anim_en); 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) 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_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 * 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) static void tileview_event_cb(lv_event_t * e)
{ {
lv_event_code_t code = lv_event_get_code(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) { if(code == LV_EVENT_SCROLL_END) {
lv_coord_t w = lv_obj_get_content_width(tv); lv_coord_t w = lv_obj_get_content_width(obj);
lv_coord_t h = lv_obj_get_content_height(tv); lv_coord_t h = lv_obj_get_content_height(obj);
lv_point_t scroll_end; 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 left = scroll_end.x;
lv_coord_t top = scroll_end.y; lv_coord_t top = scroll_end.y;
lv_coord_t tx = ((left + (w / 2)) / w) * w; lv_coord_t tx = ((left + (w / 2)) / w) * w;
lv_coord_t ty = ((top + (h / 2)) / h) * h; lv_coord_t ty = ((top + (h / 2)) / h) * h;
lv_dir_t dir = LV_DIR_ALL; lv_dir_t dir = LV_DIR_ALL;
uint32_t i; uint32_t i;
for(i = 0; i < lv_obj_get_child_cnt(tv); i++) { for(i = 0; i < lv_obj_get_child_cnt(obj); i++) {
lv_obj_t * tile_obj = lv_obj_get_child(tv, 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 x = lv_obj_get_x(tile_obj);
lv_coord_t y = lv_obj_get_y(tile_obj); lv_coord_t y = lv_obj_get_y(tile_obj);
if(x == tx && y == ty) { if(x == tx && y == ty) {
lv_tileview_tile_t * tile = (lv_tileview_tile_t *)tile_obj; lv_tileview_tile_t * tile = (lv_tileview_tile_t *)tile_obj;
tv->tile_act = (lv_obj_t *)tile;
dir = tile->dir; dir = tile->dir;
lv_event_send(obj, LV_EVENT_VALUE_CHANGED, NULL);
break; break;
} }
} }
lv_obj_set_scroll_dir(tv, dir); lv_obj_set_scroll_dir(obj, dir);
} }
} }
#endif /*LV_USE_TILEVIEW*/ #endif /*LV_USE_TILEVIEW*/

2
src/extra/widgets/tileview/lv_tileview.h
View File

@ -26,6 +26,7 @@ extern "C" {
**********************/ **********************/
typedef struct { typedef struct {
lv_obj_t obj; lv_obj_t obj;
lv_obj_t * tile_act;
}lv_tileview_t; }lv_tileview_t;
typedef struct { 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(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); 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 * Other functions