mirror of
https://github.com/lvgl/lvgl.git
synced 2025-01-28 07:03:00 +08:00
docs update some widgets' docs to v8
This commit is contained in:
Gabor Kiss-Vamosi
parent
32d742cf52
commit
a77fbc574d
@ -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
|
||||
|
||||
```
|
||||
|
||||
|
||||
@ -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
|
||||
|
||||
```
|
||||
|
||||
|
||||
@ -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
|
||||
|
||||
```
|
||||
|
||||
|
||||
@ -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
|
||||
|
||||
```
|
||||
|
||||
|
||||
@ -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
|
||||
|
||||
```
|
||||
|
||||
|
||||
@ -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
|
||||
|
||||
```
|
||||
|
||||
|
||||
@ -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
|
||||
|
||||
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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
|
||||
|
||||
|
||||
|
||||
@ -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
|
||||
|
||||
13
examples/widgets/win/index.rst
Normal file
13
examples/widgets/win/index.rst
Normal file
@ -0,0 +1,13 @@
|
||||
C
|
||||
^
|
||||
|
||||
Simple window
|
||||
"""""""""""""""
|
||||
|
||||
.. lv_example:: widgets/win/lv_example_win_1
|
||||
:language: c
|
||||
|
||||
MicroPython
|
||||
^^^^^^^^^^^
|
||||
|
||||
No examples yet.
|
||||
@ -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);
|
||||
|
||||
|
||||
@ -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*/
|
||||
|
||||
@ -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);
|
||||
|
||||
@ -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*/
|
||||
|
||||
@ -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
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user