github-code/lvgl
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

add the md files from the docs repo to start updating them to v8

Browse Source
This commit is contained in:
Gabor Kiss-Vamosi
2021-04-12 18:19:04 +02:00
parent c587fc4d2a
commit 73f4264320
93 changed files with 7007 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

79
docs/widgets/arc.md Normal file
View File

@@ -0,0 +1,79 @@
```eval_rst
.. include:: /header.rst
:github_url: |github_link_base|/widgets/arc.md
```
# Arc (lv_arc)
## Overview
The Arc are consists of a background and a foreground arc. Both can have start and end angles and thickness.
## Parts and Styles
The Arc's main part is called `LV_ARC_PART_MAIN`. It draws a background using the typical background style properties and an arc using the *line* style properties.
The arc's size and position will respect the *padding* style properties.
`LV_ARC_PART_INDIC` is virtual part and it draws an other arc using the *line* style properties. It's padding values are interpreted relative to the background arc.
The radius of the indicator arc will be modified according to the greatest padding value.
`LV_ARC_PART_KNOB` is virtual part and it draws on the end of the arc indicator. It uses all background properties and padding values. With zero padding the knob size is the same as the indicator's width.
Larger padding makes it larger, smaller padding makes it smaller.
## Usage
### Angles
To set the angles of the background, use the `lv_arc_set_bg_angles(arc, start_angle, end_angle)` function or `lv_arc_set_bg_start/end_angle(arc, start_angle)`.
Zero degree is at the middle right (3 o'clock) of the object and the degrees are increasing in a clockwise direction.
The angles should be in [0;360] range.
Similarly, `lv_arc_set_angles(arc, start_angle, end_angle)` function or `lv_arc_set_start/end_angle(arc, start_angle)` sets the angles of the indicator arc.
### Rotation
An offset to the 0 degree position can added with `lv_arc_set_rotation(arc, deg)`.
### Range and values
Besides setting angles manually the arc can have a range and a value. To set the range use `lv_arc_set_range(arc, min, max)` and to set a value use `lv_arc_set_value(arc, value)`.
Using range and value the angle of the indicator will be mapped between background angles.
Note that, settings angles and values are independent. You should use either value and angle settings. Mixing the two might result unintended behavior.
### Type
The arc can have the different "types". They are set with `lv_arc_set_type`.
The following types exist:
- `LV_ARC_TYPE_NORMAL` indicator arc drawn clockwise (min to current)
- `LV_ARC_TYPE_REVERSE` indicator arc drawn counter clockwise (max to current)
- `LV_ARC_TYPE_SYMMETRIC` indicator arc drawn from the middle point to the current value.
## Events
Besides the [Generic events](../overview/event.html#generic-events) the following [Special events](../overview/event.html#special-events) are sent by the arcs:
- **LV_EVENT_VALUE_CHANGED** sent when the arc is pressed/dragged to set a new value.
Learn more about [Events](/overview/event).
## Keys
No *Keys* are processed by the object type.
Learn more about [Keys](/overview/indev).
## Example
```eval_rst
.. include:: /lv_examples/src/lv_ex_widgets/lv_ex_arc/index.rst
```
## API
```eval_rst
.. doxygenfile:: lv_arc.h
:project: lvgl
```

64
docs/widgets/bar.md Normal file
View File

@@ -0,0 +1,64 @@
```eval_rst
.. include:: /header.rst
:github_url: |github_link_base|/widgets/bar.md
```
# Bar (lv_bar)
## Overview
The bar object has a background and an indicator on it. The width of the indicator is set according to the current value of the bar.
Vertical bars can be created if the width of the object is smaller than its height.
Not only end, but the start value of the bar can be set which changes the start position of the indicator.
## Parts and Styles
The Bar's main part is called `LV_BAR_PART_BG` and it uses the typical background style properties.
`LV_BAR_PART_INDIC` is a virtual part which also uses all the typical background properties.
By default the indicator maximal size is the same as the background's size but setting positive padding values in `LV_BAR_PART_BG` will make the indicator smaller. (negative values will make it larger)
If the *value* style property is used on the indicator the alignment will be calculated based on the current size of the indicator.
For example a center aligned value is always shown in the middle of the indicator regardless it's current size.
## Usage
### Value and range
A new value can be set by `lv_bar_set_value(bar, new_value, LV_ANIM_ON/OFF)`.
The value is interpreted in a range (minimum and maximum values) which can be modified with `lv_bar_set_range(bar, min, max)`.
The default range is 1..100.
The new value in `lv_bar_set_value` can be set with or without an animation depending on the last parameter (`LV_ANIM_ON/OFF`).
The time of the animation can be adjusted by `lv_bar_set_anim_time(bar, 100)`. The time is in milliseconds unit.
It's also possible to set the start value of the bar using `lv_bar_set_start_value(bar, new_value, LV_ANIM_ON/OFF)`
### Modes
The bar can be drawn symmetrical to zero (drawn from zero, left to right), if it's enabled with `lv_bar_set_type(bar, LV_BAR_TYPE_SYMMETRICAL)`.
## Events
Only the [Generic events](../overview/event.html#generic-events) are sent by the object type.
Learn more about [Events](/overview/event).
## Keys
No *Keys* are processed by the object type.
Learn more about [Keys](/overview/indev).
## Example
```eval_rst
.. include:: /lv_examples/src/lv_ex_widgets/lv_ex_bar/index.rst
```
## API
```eval_rst
.. doxygenfile:: lv_bar.h
:project: lvgl
```

82
docs/widgets/btn.md Normal file
View File

@@ -0,0 +1,82 @@
```eval_rst
.. include:: /header.rst
:github_url: |github_link_base|/widgets/btn.md
```
# Button (lv_btn)
## Overview
Buttons are simple rectangle-like objects. They are derived from [Containers](/widgets/cont) so [layout](/widgets/cont#layout) and [fit](/widgets/cont#fit) are also available.
Besides, it can be enabled to automatically go to checked state on click.
## Parts and Styles
The buttons has only a main style called `LV_BTN_PART_MAIN` and it can use all the properties from the following groups:
- background
- border
- outline
- shadow
- value
- pattern
- transitions
It also uses the *padding* properties when *layout* or *fit* is enabled.
## Usage
### States
To make buttons usage simpler the button's state can be get with `lv_btn_get_state(btn)`. It returns one of the following values:
- **LV_BTN_STATE_RELEASED**
- **LV_BTN_STATE_PRESSED**
- **LV_BTN_STATE_CHECKED_RELEASED**
- **LV_BTN_STATE_CHECKED_PRESSED**
- **LV_BTN_STATE_DISABLED**
- **LV_BTN_STATE_CHECKED_DISABLED**
With `lv_btn_set_state(btn, LV_BTN_STATE_...)` the buttons state can be changed manually.
If a more precise description of the state is required (e.g. focused) the general `lv_obj_get_state(btn)` can be used.
### Checkable
You can configure the buttons as *toggle button* with `lv_btn_set_checkable(btn, true)`. In this case, on click, the button goes to `LV_STATE_CHECKED` state automatically, or back when clicked again.
### Layout and Fit
Similarly to [Containers](/widgets/cont), buttons also have layout and fit attributes.
- `lv_btn_set_layout(btn, LV_LAYOUT_...) `set a layout. The default is `LV_LAYOUT_CENTER`.
So, if you add a label, then it will be automatically aligned to the middle and can't be moved with `lv_obj_set_pos()`.
You can disable the layout with `lv_btn_set_layout(btn, LV_LAYOUT_OFF)`.
- `lv_btn_set_fit/fit2/fit4(btn, LV_FIT_..)` enables to set the button width and/or height automatically according to the children, parent, and fit type.
## Events
Besides the [Generic events](../overview/event.html#generic-events) the following [Special events](../overview/event.html#special-events) are sent by the buttons:
- **LV_EVENT_VALUE_CHANGED** - sent when the button is toggled.
Learn more about [Events](/overview/event).
## Keys
The following *Keys* are processed by the Buttons:
- **LV_KEY_RIGHT/UP** - Go to toggled state if toggling is enabled.
- **LV_KEY_LEFT/DOWN** - Go to non-toggled state if toggling is enabled.
Note that, the state of `LV_KEY_ENTER` is translated to `LV_EVENT_PRESSED/PRESSING/RELEASED` etc.
Learn more about [Keys](/overview/indev).
## Example
```eval_rst
.. include:: /lv_examples/src/lv_ex_widgets/lv_ex_btn/index.rst
```
## API
```eval_rst
.. doxygenfile:: lv_btn.h
:project: lvgl
```

103
docs/widgets/btnmatrix.md Normal file
View File

@@ -0,0 +1,103 @@
```eval_rst
.. include:: /header.rst
:github_url: |github_link_base|/widgets/btnmatrix.md
```
# Button matrix (lv_btnmatrix)
## Overview
The Button Matrix objects can display **multiple buttons** in rows and columns.
The main reasons for wanting to use a button matrix instead of a container and individual button objects are:
- The button matrix is simpler to use for grid-based button layouts.
- The button matrix consumes a lot less memory per button.
## Parts and Styles
The Button matrix's main part is called `LV_BTNMATRIX_PART_BG`. It draws a background using the typical background style properties.
`LV_BTNMATRIX_PART_BTN` is virtual part and it refers to the buttons on the button matrix. It also uses all the typical background properties.
The top/bottom/left/right padding values from the background are used to keep some space on the sides. Inner padding is applied between the buttons.
## Usage
### Button's text
There is a text on each button. To specify them a descriptor string array, called *map*, needs to be used.
The map can be set with `lv_btnmatrix_set_map(btnm, my_map)`.
The declaration of a map should look like `const char * map[] = {"btn1", "btn2", "btn3", ""}`.
Note that **the last element has to be an empty string**!
Use `"\n"` in the map to make **line break**. E.g. `{"btn1", "btn2", "\n", "btn3", ""}`. Each line's buttons have their width calculated automatically.
### Control buttons
The **buttons width** can be set relative to the other button in the same line with `lv_btnmatrix_set_btn_width(btnm, btn_id, width)`
E.g. in a line with two buttons: *btnA, width = 1* and *btnB, width = 2*, *btnA* will have 33 % width and *btnB* will have 66 % width.
It's similar to how the [`flex-grow`](https://developer.mozilla.org/en-US/docs/Web/CSS/flex-grow) property works in CSS.
In addition to width, each button can be customized with the following parameters:
- **LV_BTNMATRIX_CTRL_HIDDEN** - make a button hidden (hidden buttons still take up space in the layout, they are just not visible or clickable)
- **LV_BTNMATRIX_CTRL_NO_REPEAT** - disable repeating when the button is long pressed
- **LV_BTNMATRIX_CTRL_DISABLED** - make a button disabled
- **LV_BTNMATRIX_CTRL_CHECKABLE** - enable toggling of a button
- **LV_BTNMATRIX_CTRL_CHECK_STATE** - set the toggle state
- **LV_BTNMATRIX_CTRL_CLICK_TRIG** - if 0, the button will react on press, if 1, will react on release
The set or clear a button's control attribute, use `lv_btnmatrix_set_btn_ctrl(btnm, btn_id, LV_BTNM_CTRL_...)` and
`lv_btnmatrix_clear_btn_ctrl(btnm, btn_id, LV_BTNM_CTRL_...)` respectively. More `LV_BTNM_CTRL_...` values can be *Or*ed
The set/clear the same control attribute for all buttons of a button matrix, use `lv_btnmatrix_set_btn_ctrl_all(btnm, btn_id, LV_BTNM_CTRL_...)` and
`lv_btnmatrix_clear_btn_ctrl_all(btnm, btn_id, LV_BTNM_CTRL_...)`.
The set a control map for a button matrix (similarly to the map for the text), use `lv_btnmatrix_set_ctrl_map(btnm, ctrl_map)`.
An element of `ctrl_map` should look like `ctrl_map[0] = width | LV_BTNM_CTRL_NO_REPEAT | LV_BTNM_CTRL_TGL_ENABLE`.
The number of elements should be equal to the number of buttons (excluding newlines characters).
### One check
The "One check" feature can be enabled with `lv_btnmatrix_set_one_check(btnm, true)` to allow only one button to be checked (toggled) at once.
### Recolor
The **texts** on the button can be **recolored** similarly to the recolor feature for [Label](/widgets/label) object. To enable it, use `lv_btnmatrix_set_recolor(btnm, true)`.
After that a button with `#FF0000 Red#` text will be red.
### Aligning the button's text
To align the text on the buttons, use `lv_btnmatrix_set_align(roller, LV_LABEL_ALIGN_LEFT/CENTER/RIGHT)`.
All text items in the button matrix will conform to the alignment proprty as it is set.
### Notes
The Button matrix object is very light weighted because the buttons are not created just virtually drawn on the fly.
This way, 1 button use only 8 extra bytes instead of the ~100-150 byte size of a normal [Button](/widgets/btn) object (plus the size of its container and a label for each button).
The disadvantage of this setup is that the ability to style individual buttons to be different from others is limited (aside from the toggling feature).
If you require that ability, using individual buttons is very likely to be a better approach.
## Events
Besides the [Generic events](../overview/event.html#generic-events), the following [Special events](../overview/event.html#special-events) are sent by the button matrices:
- **LV_EVENT_VALUE_CHANGED** - sent when the button is pressed/released or repeated after long press. The event data is set to the ID of the pressed/released button.
Learn more about [Events](/overview/event).
## Keys
The following *Keys* are processed by the Buttons:
- **LV_KEY_RIGHT/UP/LEFT/RIGHT** - To navigate among the buttons to select one
- **LV_KEY_ENTER** - To press/release the selected button
Learn more about [Keys](/overview/indev).
## Example
```eval_rst
.. include:: /lv_examples/src/lv_ex_widgets/lv_ex_btnmatrix/index.rst
```
## API
```eval_rst
.. doxygenfile:: lv_btnmatrix.h
:project: lvgl
```

82
docs/widgets/calendar.md Normal file
View File

@@ -0,0 +1,82 @@
```eval_rst
.. include:: /header.rst
:github_url: |github_link_base|/widgets/calendar.md
```
# Calendar (lv_calendar)
## Overview
The Calendar object is a classic calendar which can:
- highlight the current day
- highlight any user-defined dates
- display the name of the days
- go the next/previous month by button click
- highlight the clicked day
## Parts and Styles
The calendar's main part is called `LV_CALENDAR_PART_BG`. It draws a background using the typical background style properties.
Besides the following virtual parts exist:
- `LV_CALENDAR_PART_HEADER` The upper area where the current year and month's name is shown. It also has buttons to move the next/previous month.
It uses typical background properties plus padding to adjust its size and margin to set the distance from the top of the calendar and the day names below it.
- `LV_CALENDAR_PART_DAY_NAMES` Shows the name of the days below the header. It uses the *text* style properties padding to keep some distance from the background (left, right), header (top) and dates (bottom).
- `LV_CALENDAR_PART_DATES` Show the date numbers from 1..28/29/30/31 (depending on current month). Different "state" of the states are drawn according to the states defined in this part:
- normal dates: drawn with `LV_STATE_DEFAULT` style
- pressed date: drawn with `LV_STATE_PRESSED` style
- today: drawn with `LV_STATE_FOCUSED` style
- highlighted dates: drawn with `LV_STATE_CHECKED` style
## Usage
## Overview
To set and get dates in the calendar, the `lv_calendar_date_t` type is used which is a structure with `year`, `month` and `day` fields.
### Current date
To set the current date (today), use the `lv_calendar_set_today_date(calendar, &today_date)` function.
### Shown date
To set the shown date, use `lv_calendar_set_shown_date(calendar, &shown_date)`;
### Highlighted days
The list of highlighted dates should be stored in a `lv_calendar_date_t` array loaded by `lv_calendar_set_highlighted_dates(calendar, &highlighted_dates)`.
Only the arrays pointer will be saved so the array should be a static or global variable.
### Name of the days
The name of the days can be adjusted with `lv_calendar_set_day_names(calendar, day_names)` where `day_names` looks like `const char * day_names[7] = {"Su", "Mo", ...};`
### Name of the months
Similarly to `day_names`, the name of the month can be set with `lv_calendar_set_month_names(calendar, month_names_array)`.
## Events
Besides the [Generic events](../overview/event.html#generic-events), the following [Special events](../overview/event.html#special-events) are sent by the calendars:
**LV_EVENT_VALUE_CHANGED** is sent when the current month has changed.
In *Input device related* events, `lv_calendar_get_pressed_date(calendar)` tells which day is currently being pressed or return `NULL` if no date is pressed.
## Keys
No *Keys* are processed by the object type.
Learn more about [Keys](/overview/indev).
## Example
```eval_rst
.. include:: /lv_examples/src/lv_ex_widgets/lv_ex_calendar/index.rst
```
## API
```eval_rst
.. doxygenfile:: lv_calendar.h
:project: lvgl
```

98
docs/widgets/canvas.md Normal file
View File

@@ -0,0 +1,98 @@
```eval_rst
.. include:: /header.rst
:github_url: |github_link_base|/widgets/canvas.md
```
# Canvas (lv_canvas)
## Overview
A Canvas inherites from [Image](/widgets/img) where the user can draw anything. Rectangles, texts, images, lines arcs can be drawn here using lvgl's drawing engine.
Besides some "effects" can be applied as well like rotation, zoom and blur.
## Parts and Styles
The Canvas has on one main part called `LV_CANVAS_PART_MAIN` and only the *image_recolor* property is used to give a color to `LV_IMG_CF_ALPHA_1/2/4/8BIT` images.
## Usage
### Buffer
The Canvas needs a buffer which stores the drawn image.
To assign a buffer to a Canvas, use `lv_canvas_set_buffer(canvas, buffer, width, height, LV_IMG_CF_...)`.
Where `buffer` is a static buffer (not just a local variable) to hold the image of the canvas.
For example,
`static lv_color_t buffer[LV_CANVAS_BUF_SIZE_TRUE_COLOR(width, height)]`. `LV_CANVAS_BUF_SIZE_...` macros help to determine the size of the buffer with different color formats.
The canvas supports all the built-in color formats like `LV_IMG_CF_TRUE_COLOR` or `LV_IMG_CF_INDEXED_2BIT`.
See the full list in the [Color formats](/overview/image.html#color-formats) section.
### Palette
For `LV_IMG_CF_INDEXED_...` color formats, a palette needs to be initialized with `lv_canvas_set_palette(canvas, 3, LV_COLOR_RED)`. It sets pixels with *index=3* to red.
### Drawing
To set a pixel on the canvas, use `lv_canvas_set_px(canvas, x, y, LV_COLOR_RED)`.
With `LV_IMG_CF_INDEXED_...` or `LV_IMG_CF_ALPHA_...`, the index of the color or the alpha value needs to be passed as color. E.g. `lv_color_t c; c.full = 3;`
`lv_canvas_fill_bg(canvas, LV_COLOR_BLUE, LV_OPA_50)` fills the whole canvas to blue with 50% opacity. Note that, if the current color format doesn't support colors (e.g. `LV_IMG_CF_ALPHA_2BIT`) teh color will be ignored.
Similarly, if opacity is not supported (e.g. `LV_IMG_CF_TRUE_COLOR`) it will be ignored.
An array of pixels can be copied to the canvas with `lv_canvas_copy_buf(canvas, buffer_to_copy, x, y, width, height)`. The color format of the buffer and the canvas need to match.
To draw something to the canvas use
- `lv_canvas_draw_rect(canvas, x, y, width, heigth, &draw_dsc)`
- `lv_canvas_draw_text(canvas, x, y, max_width, &draw_dsc, txt, LV_LABEL_ALIGN_LEFT/CENTER/RIGHT)`
- `lv_canvas_draw_img(canvas, x, y, &img_src, &draw_dsc)`
- `lv_canvas_draw_line(canvas, point_array, point_cnt, &draw_dsc)`
- `lv_canvas_draw_polygon(canvas, points_array, point_cnt, &draw_dsc)`
- `lv_canvas_draw_arc(canvas, x, y, radius, start_angle, end_angle, &draw_dsc)`
`draw_dsc` is a `lv_draw_rect/label/img/line_dsc_t` variable which should be first initialized with `lv_draw_rect/label/img/line_dsc_init()` function and then it's filed should be modified with the desired colors and other values.
The draw function can draw to any color format. For example, it's possible to draw a text to an `LV_IMG_VF_ALPHA_8BIT` canvas and use the result image as a mask in [lv_objmask](/widgets/objmask) later.
### Transformations
`lv_canvas_transform()` can be used to rotate and/or scale the image of an image and store the result on the canvas. The function needs the following parameters:
- `canvas` pointer to a canvas object to store the result of the transformation.
- `img pointer` to an image descriptor to transform. Can be the image descriptor of an other canvas too (`lv_canvas_get_img()`).
- `angle` the angle of rotation (0..3600), 0.1 deg resolution
- `zoom` zoom factor (256 no zoom, 512 double size, 128 half size);
- `offset_x` offset X to tell where to put the result data on destination canvas
- `offset_y` offset X to tell where to put the result data on destination canvas
- `pivot_x` pivot X of rotation. Relative to the source canvas. Set to `source width / 2` to rotate around the center
- `pivot_y` pivot Y of rotation. Relative to the source canvas. Set to `source height / 2` to rotate around the center
- `antialias` true: apply anti-aliasing during the transformation. Looks better but slower.
Note that a canvas can't be rotated on itself. You need a source and destination canvas or image.
## Blur
A given area of the canvas can be blurred horizontally with `lv_canvas_blur_hor(canvas, &area, r)` to vertically with `lv_canvas_blur_ver(canvas, &area, r)`.
`r` is the radius of the blur (greater value means more intensive burring). `area` is the area where the blur should be applied (interpreted relative to the canvas)
## Events
As default the clicking of a canvas is disabled (inherited by [Image](/widgets/img)) and therefore no events are generated.
If clicking is enabled (`lv_obj_set_click(canvas, true)`) only the [Generic events](../overview/event.html#generic-events) are sent by the object type.
Learn more about [Events](/overview/event).
## Keys
No *Keys* are processed by the object type.
Learn more about [Keys](/overview/indev).
## Example
```eval_rst
.. include:: /lv_examples/src/lv_ex_widgets/lv_ex_canvas/index.rst
```
## API
```eval_rst
.. doxygenfile:: lv_canvas.h
:project: lvgl
```

148
docs/widgets/chart.md Normal file
View File

@@ -0,0 +1,148 @@
```eval_rst
.. include:: /header.rst
:github_url: |github_link_base|/widgets/chart.md
```
# Chart (lv_chart)
## Overview
Charts are a basic object to visualize data points.
They support *Line* charts (connect points with lines and/or draw points on them) and *Column* charts.
Charts also support division lines, 2 y axis, axis ticks, and texts on ticks.
## Parts and Styles
The Chart's main part is called `LV_CHART_PART_BG` and it uses all the typical background properties.
The *text* style properties determine the style of the axis texts and the *line* properties determine ticks' style.
*Padding* values add some space on the sides thus it makes the *series area* smaller. Padding also can be used to make space for axis texts and ticks.
The background of the series is called `LV_CHART_PART_SERIES_BG` and it's placed on the main background.
The division lines, and series data is drawn on this part. Besides the typical background style properties
the *line* style properties are used by the division lines. The *padding* values tells the space between the this part and the axis texts.
The style of the series can be referenced by `LV_CHART_PART_SERIES`. In case of column type the following properties are used:
- *radius*: radius of the bars
- *padding_inner*: space between the columns of the same x coordinate
In case of Line type these properties are used:
- *line properties* to describe the lines
- *size* radius of the points
- *bg_opa*: the overall opacity of the area below the lines
- *bg_main_stop*: % of *bg_opa* at the top to create an alpha fade (0: transparent at the top, 255: *bg_opa* at the top)
- *bg_grad_stop*: % of *bg_opa* at the bottom to create an alpha fade (0: transparent at the bottom, 255: *bg_opa* at the top)
- *bg_drag_dir*: should be `LV_GRAD_DIR_VER` to allow alpha fading with *bg_main_stop* and *bg_grad_stop*
`LV_CHART_PART_CURSOR` refres to the cursors. Any number of cursor can be added and their appearence can be set by the line related style properties. The color of the cursors are set when the cursor is created and `line_color` fro mteh style is overwritten by this value.
## Usage
### Data series
You can add any number of series to the charts by `lv_chart_add_series(chart, color)`.
It allocates data for a `lv_chart_series_t` structure which contains the chosen `color` and an array for the data points if
not using an external array, if an external array is assigned any internal points associated with the series are deallocated
and the series points to the external array instead.
### Series' type
The following **data display types** exist:
- **LV_CHART_TYPE_NONE** - Do not display any data. It can be used to hide the series.
- **LV_CHART_TYPE_LINE** - Draw lines between the points.
- **LV_CHART_TYPE_COLUMN** - Draw columns.
You can specify the display type with `lv_chart_set_type(chart, LV_CHART_TYPE_...)`. The types can be 'OR'ed (like `LV_CHART_TYPE_LINE`).
### Modify the data
You have several options to set the data of series:
1. Set the values manually in the array like `ser1->points[3] = 7` and refresh the chart with `lv_chart_refresh(chart)`.
2. Use `lv_chart_set_point_id(chart, ser, value, id)` where id is the index of the point you wish to update.
3. Use the `lv_chart_set_next(chart, ser, value)`.
4. Initialize all points to a given value with: `lv_chart_init_points(chart, ser, value)`.
5. Set all points from an array with: `lv_chart_set_points(chart, ser, value_array)`.
Use `LV_CHART_POINT_DEF` as value to make the library skip drawing that point, column, or line segment.
### Override default start point for series
If you wish a plot to start from a point other than the default which is point[0] of the series, you can set an alternative
index with the function `lv_chart_set_x_start_point(chart, ser, id)` where id is the new index position to start plotting from.
### Set an external data source
You can make the chart series update from an external data source by assigning it with the function:
`lv_chart_set_ext_array(chart, ser, array, point_cnt )` where array is an external array of lv_coord_t with point_cnt elements.
Note: you should call `lv_chart_refresh(chart)` after the external data source has been updated, to update the chart.
### Get current chart information
There are four functions to get information about a chart:
1. `lv_chart_get_type(chart)` returns the current chart type.
2. `lv_chart_get_point_count(chart)` returns the current chart point count.
3. `lv_chart_get_x_start_point(ser)` returns the current plotting index for the specified series.
4. `lv_chart_get_point_id(chart, ser, id)` returns the value of the data at a particular index(id) for the specified series.
### Update modes
`lv_chart_set_next` can behave in two ways depending on *update mode*:
- **LV_CHART_UPDATE_MODE_SHIFT** - Shift old data to the left and add the new one o the right.
- **LV_CHART_UPDATE_MODE_CIRCULAR** - Circularly add the new data (Like an ECG diagram).
The update mode can be changed with `lv_chart_set_update_mode(chart, LV_CHART_UPDATE_MODE_...)`.
### Number of points
The number of points in the series can be modified by `lv_chart_set_point_count(chart, point_num)`. The default value is 10.
Note: this also affects the number of points processed when an external buffer is assigned to a series.
### Vertical range
You can specify the minimum and maximum values in y-direction with `lv_chart_set_range(chart, y_min, y_max)`. The value of the points will be scaled proportionally. The default range is: 0..100.
### Division lines
The number of horizontal and vertical division lines can be modified by `lv_chart_set_div_line_count(chart, hdiv_num, vdiv_num)`. The default settings are 3 horizontal and 5 vertical division lines.
### Tick marks and labels
Ticks and labels can be added to the axis.
`lv_chart_set_x_tick_text(chart, list_of_values, num_tick_marks, LV_CHART_AXIS_...)` set the ticks and texts on x axis.
`list_of_values` is a string with `'\n'` terminated text (expect the last) with text for the ticks. E.g. `const char * list_of_values = "first\nsec\nthird"`. `list_of_values` can be `NULL`.
If `list_of_values` is set then `num_tick_marks` tells the number of ticks between two labels. If `list_of_values` is `NULL` then it specifies the total number of ticks.
*Major tick lines* are drawn where text is placed, and *minor tick lines* are drawn elsewhere. `lv_chart_set_x_tick_length(chart, major_tick_len, minor_tick_len)` sets the length of tick lines on the x-axis.
The same functions exists for the y axis too: `lv_chart_set_y_tick_text` and `lv_chart_set_y_tick_length`.
### Cursor
A cursor can be added with `lv_chart_cursor_t * c1 = lv_chart_add_cursor(chart, color, dir);`. The possible values of `dir` `LV_CHART_CURSOR_NONE/RIGHT/UP/LEFT/DOWN` or their OR-ed values to tell in which direction(s) should the cursor be drawn.
`lv_chart_set_cursor_point(chart, cursor, &point)` sets the position of the cursor. `point` is a pointer to an `lv_poin_t` variable. E.g. `lv_point_t point = {10, 20};`. The point is relative to the series area of the chart.
The `lv_coord_t p_index = lv_chart_get_nearest_index_from_coord(chart, x)` tells which point index is to the closest to a X coordinate (relative to the series area). It can be used to snap the cursor to a point for example when the chart is clicked.
`lv_chart_get_x_from_index(chart, series, id)` and `lv_chart_get_y_from_index(chart, series, id)` tells the X and Y coordinate of a given point. It's useful to place the cursor to given point.
The current series area can be retrieved with `lv_chart_get_series_area(chart, &area)` where `area` is a pointer to an `lv_area_t` variable to store the result. The area has absolute coordinates.
## Events
Only the [Generic events](../overview/event.html#generic-events) are sent by the object type.
Learn more about [Events](/overview/event).
## Keys
No *Keys* are processed by the object type.
Learn more about [Keys](/overview/indev).
## Example
```eval_rst
.. include:: /lv_examples/src/lv_ex_widgets/lv_ex_chart/index.rst
```
## API
```eval_rst
.. doxygenfile:: lv_chart.h
:project: lvgl
```

81
docs/widgets/checkbox.md Normal file
View File

@@ -0,0 +1,81 @@
```eval_rst
.. include:: /header.rst
:github_url: |github_link_base|/widgets/checkbox.md
```
# Checkbox (lv_cb)
## Overview
The Checkbox objects are built from a [Button](/widgets/btn) background which contains an also Button *bullet* and a [Label](/widgets/label) to realize a classical checkbox.
## Parts and Styles
The Check box's main part is called `LV_CHECKBOX_PART_BG`. It's a container for a "bullet" and a text next to it. The background uses all the typical background style properties.
The bullet is real [lv_obj](/widgets/obj) object and can be referred with `LV_CHECKBOX_PART_BULLET`.
The bullet automatically inherits the state of the background. So the background is pressed the bullet goes to pressed state as well.
The bullet also uses all the typical background style properties.
There is not dedicated part for the label. Its styles can be set in the background's styles because the *text* styles properties are always inherited.
## Usage
### Text
The text can be modified by the `lv_checkbox_set_text(cb, "New text")` function. It will dynamically allocate the text.
To set a static text, use `lv_checkbox_set_static_text(cb, txt)`. This way, only a pointer of `txt` will be stored and it shouldn't be deallocated while the checkbox exists.
### Check/Uncheck
You can manually check / un-check the Checkbox via `lv_checkbox_set_checked(cb, true/false)`. Setting `true` will check the checkbox and `false` will un-check the checkbox.
### Disabled
To make the Checkbox disabled, use `lv_checkbox_set_disabled(cb, true)`.
### Get/Set Checkbox State
You can get the current state of the Checkbox with the `lv_checkbox_get_state(cb)` function which returns the current state.
You can set the current state of the Checkbox with the `lv_checkbox_set_state(cb, state)`.
The available states as defined by the enum `lv_btn_state_t` are:
- **LV_BTN_STATE_RELEASED**
- **LV_BTN_STATE_PRESSED**
- **LV_BTN_STATE_DISABLED**
- **LV_BTN_STATE_CHECKED_RELEASED**
- **LV_BTN_STATE_CHECKED_PRESSED**
- **LV_BTN_STATE_CHECKED_DISABLED**
## Events
Besides the [Generic events](../overview/event.html#generic-events) the following [Special events](../overview/event.html#special-events) are sent by the Checkboxes:
- **LV_EVENT_VALUE_CHANGED** - sent when the checkbox is toggled.
Note that, the generic input device-related events (like `LV_EVENT_PRESSED`) are sent in the inactive state too. You need to check the state with `lv_cb_is_inactive(cb)` to ignore the events from inactive Checkboxes.
Learn more about [Events](/overview/event).
## Keys
The following *Keys* are processed by the 'Buttons':
- **LV_KEY_RIGHT/UP** - Go to toggled state if toggling is enabled
- **LV_KEY_LEFT/DOWN** - Go to non-toggled state if toggling is enabled
Note that, as usual, the state of `LV_KEY_ENTER` is translated to `LV_EVENT_PRESSED/PRESSING/RELEASED` etc.
Learn more about [Keys](/overview/indev).
## Example
```eval_rst
.. include:: /lv_examples/src/lv_ex_widgets/lv_ex_checkbox/index.rst
```
## API
```eval_rst
.. doxygenfile:: lv_checkbox.h
:project: lvgl
```

72
docs/widgets/cont.md Normal file
View File

@@ -0,0 +1,72 @@
```eval_rst
.. include:: /header.rst
:github_url: |github_link_base|/widgets/cont.md
```
# Container (lv_cont)
## Overview
The containers are essentially a **basic object** with layout and automatic sizing features features.
## Parts and Styles
The containers has only a main style called `LV_CONT_PART_MAIN` and it can use all the typicaly bacground properties properties and padding for layout auto sizing.
## Usage
### Layout
You can apply a layout on the containers to automatically order their children. The layout spacing comes from the style's `pad` properties. The possible layout options:
- **LV_LAYOUT_OFF** - Do not align the children.
- **LV_LAYOUT_CENTER** - Align children to the center in column and keep `pad_inner` space between them.
- **LV_LAYOUT_COLUMN_LEFT** - Align children in a left-justified column. Keep `pad_left` space on the left, `pad_top` space on the top and `pad_inner` space between the children.
- **LV_LAYOUT_COLUMN_MID** - Align children in centered column. Keep `pad_top` space on the top and `pad_inner` space between the children.
- **LV_LAYOUT_COLUMN_RIGHT** - Align children in a right-justified column. Keep `pad_right` space on the right, `pad_top` space on the top and `pad_inner` space between the children.
- **LV_LAYOUT_ROW_TOP** - Align children in a top justified row. Keep `pad_left` space on the left, `pad_top` space on the top and `pad_inner` space between the children.
- **LV_LAYOUT_ROW_MID** - Align children in centered row. Keep `pad_left` space on the left and `pad_inner` space between the children.
- **LV_LAYOUT_ROW_BOTTOM** - Align children in a bottom justified row. Keep `pad_left` space on the left, `pad_bottom` space on the bottom and `pad_inner` space between the children.
- **LV_LAYOUT_PRETTY_TOP** - Put as many objects as possible in a row (with at least `pad_inner` space and `pad_left/right` space on the sides). Divide the space in each line equally between the children.
If here are children with different height in a row align their top edge.
- **LV_LAYOUT_PRETTY_MID** - Same as `LV_LAYOUT_PRETTY_TOP` but if here are children with different height in a row align their middle line.
- **LV_LAYOUT_PRETTY_BOTTOM** - Same as `LV_LAYOUT_PRETTY_TOP` but if here are children with different height in a row align their bottom line.
- **LV_LAYOUT_GRID** - Similar to `LV_LAYOUT_PRETTY` but not divide horizontal space equally just let `pad_left/right` on the edges and `pad_inner` space between the elements.
### Autofit
Container have an autofit feature which can automatically change the size of the container according to its children and/or its parent. The following options exist:
- **LV_FIT_NONE** - Do not change the size automatically.
- **LV_FIT_TIGHT** - Shrink-wrap the container around all of its children, while keeping `pad_top/bottom/left/right` space on the edges.
- **LV_FIT_PARENT** - Set the size to the parent's size minus `pad_top/bottom/left/right` (from the parent's style) space.
- **LV_FIT_MAX** - Use `LV_FIT_PARENT` while smaller than the parent and `LV_FIT_TIGHT` when larger. It will ensure that the container is, at minimum, the size of its parent.
To set the auto fit mode for all directions, use `lv_cont_set_fit(cont, LV_FIT_...)`.
To use different auto fit horizontally and vertically, use `lv_cont_set_fit2(cont, hor_fit_type, ver_fit_type)`.
To use different auto fit in all 4 directions, use `lv_cont_set_fit4(cont, left_fit_type, right_fit_type, top_fit_type, bottom_fit_type)`.
## Events
Only the [Generic events](../overview/event.html#generic-events) are sent by the object type.
Learn more about [Events](/overview/event).
## Keys
No *Keys* are processed by the object type.
Learn more about [Keys](/overview/indev).
## Example
```eval_rst
.. include:: /lv_examples/src/lv_ex_widgets/lv_ex_cont/index.rst
```
## API
```eval_rst
.. doxygenfile:: lv_cont.h
:project: lvgl
```

69
docs/widgets/cpicker.md Normal file
View File

@@ -0,0 +1,69 @@
```eval_rst
.. include:: /header.rst
:github_url: |github_link_base|/widgets/cpicker.md
```
# color picker (lv_cpicker)
## Overview
As its name implies *Color picker* allows to select color. The Hue, Saturation and Value of the color can be selected after each other.
The widget has two forms: circle (disc) and rectangle.
In both forms, be long pressing the object, the color picker will change to the next parameter of the color (hue, saturation or value).
Besides, double click will reset the current parameter.
## Parts and Styles
The Color picker's main part is called `LV_CPICKER_PART_BG`. In circular form it uses *scale_width* to set the the width of the circle and *pad_inner* for padding between the circle and the inner preview circle.
In rectangle mode *radius* can be used to apply a radius on the rectangle.
The object has virtual part called `LV_CPICKER_PART_KNOB` which is rectangle (or circle) drawn on the current value.
It uses all the rectangle like style properties and padding to make it larger than the width of the circle or rectangle background.
## Usage
### Type
The type of the Color picker can be changed with `lv_cpicker_set_type(cpicker, LV_CPICKER_TYPE_RECT/DISC)`
### Set color
The colro can be set manually with `lv_cpicker_set_hue/saturation/value(cpicker, x)` or all at once with `lv_cpicker_set_hsv(cpicker, hsv)` or `lv_cpicker_set_color(cpicker, rgb)`
### Color mode
The current color moed can be manually selected with `lv_cpicker_set_color_mode(cpicker, LV_CPICKER_COLOR_MODE_HUE/SATURATION/VALUE)`.
The color moe be fixed (do not change with long press) using `lv_cpicker_set_color_mode_fixed(cpicker, true)`
### Knob color
`lv_cpicker_set_knob_colored(cpicker, true)` make the knob to automatically show the selected color as background color.
## Events
Only the [Generic events](../overview/event.html#generic-events) are sent by the object type.
Learn more about [Events](/overview/event).
## Keys
- **LV_KEY_UP**, **LV_KEY_RIGHT** Increment the current parameter's value by 1
- **LV_KEY_DOWN**, **LV_KEY_LEFT** Decrement the current parameter's by 1
- **LV_KEY_ENTER** By long press the next mode will be shown. By double click the current parameter will be reset.
Learn more about [Keys](/overview/indev).
## Example
```eval_rst
.. include:: /lv_examples/src/lv_ex_widgets/lv_ex_cpicker/index.rst
```
## API
```eval_rst
.. doxygenfile:: lv_cpicker.h
:project: lvgl
```

106
docs/widgets/dropdown.md Normal file
View File

@@ -0,0 +1,106 @@
```eval_rst
.. include:: /header.rst
:github_url: |github_link_base|/widgets/dropdown.md
```
# Drop-down list (lv_dropdown)
## Overview
The drop-down list allows the user to select one value from a list.
The drop-down list is closed by default and displays a single value or a predefined text.
When activated (by click on the drop-down list), a list is created from which the user may select one option.
When the user selects a new value, the list is deleted.
## Parts and Styles
The drop-down list's main part is called `LV_DROPDOWN_PART_MAIN` which is a simple [lv_obj](/widgets/obj) object.
It uses all the typical background properties. *Pressed*, *Focused*, *Edited* etc. stiles are also applied as usual.
The list, which is created when the main object is clicked, is an [Page](/widgets/page).
Its background part can be referenced with `LV_DROPDOWN_PART_LIST` and uses all the typical background properties for the rectangle itself and text properties for the options.
To adjust the space between the options use the *text_line_space* style property.
Padding values can be used to make some space on the edges.
The scrollable part of the page is hidden and its styles are always empty (so transparent with no padding).
The scrollbar can be referenced with `LV_DROPDOWN_PART_SCRLBAR` and uses all the typical background properties.
The selected option can be referenced with `LV_DROPDOWN_PART_SELECTED` and uses all the typical background properties.
It will used in its default state to draw a rectangle on the selected option, and in pressed state to draw a rectangle on the being pressed option.
## Usage
## Overview
### Set options
The options are passed to the drop-down list as a string with `lv_dropdown_set_options(dropdown, options)`. The options should be separated by `\n`. For example: `"First\nSecond\nThird"`.
The string will be saved in the drop-down list, so it can in local variable too.
The `lv_dropdown_add_option(dropdown, "New option", pos)` function inserts a new option to `pos` index.
To save memory the options can set from a static(constant) string too with `lv_dropdown_set_static_options(dropdown, options)`.
In this case the options string should be alive while the drop-down list exists and `lv_dropdown_add_option` can't be used
You can select an option manually with `lv_dropdown_set_selected(dropdown, id)`, where _id_ is the index of an option.
### Get selected option
The get the currently selected option, use `lv_dropdown_get_selected(dropdown)`. It will return the *index* of the selected option.
`lv_dropdown_get_selected_str(dropdown, buf, buf_size)` copies the name of the selected option to a `buf`.
### Direction
The list can be created on any side. The default `LV_DROPDOWN_DOWN` can be modified by `lv_dropdown_set_dir(dropdown, LV_DROPDOWN_DIR_LEFT/RIGHT/UP/DOWN)` function.
If the list would be vertically out of the screen, it will aligned to the edge.
### Symbol
A symbol (typically an arrow) can be added to the drop down list with `lv_dropdown_set_symbol(dropdown, LV_SYMBOL_...)`
If the direction of the drop-down list is `LV_DROPDOWN_DIR_LEFT` the symbol will be shown on the left, else on the right.
### Maximum height
The maximum height of drop-down list can be set via `lv_dropdown_set_max_height(dropdown, height)`. By default it's set to 3/4 vertical resolution.
### Show selected
The main part can either show the selected option or a static text. It can controlled with `lv_dropdown_set_show_selected(sropdown, true/false)`.
The static text can be set with `lv_dropdown_set_text(dropdown, "Text")`. Only the pointer of the text is saved.
If you also don't want the selected option to be highlighted, a custom transparent style can be used for `LV_DROPDOWN_PART_SELECTED`.
### Animation time
The drop-down list's open/close animation time is adjusted by `lv_dropdown_set_anim_time(ddlist, anim_time)`. Zero animation time means no animation.
### Manually open/close
To manually open or close the drop-down list the `lv_dropdown_open/close(dropdown, LV_ANIM_ON/OFF)` function can be used.
## 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 list:
- **LV_EVENT_VALUE_CHANGED** - Sent when the new option is selected.
Learn more about [Events](/overview/event).
## Keys
The following *Keys* are processed by the Buttons:
- **LV_KEY_RIGHT/DOWN** - Select the next option.
- **LV_KEY_LEFT/UP** - Select the previous option.
- **LY_KEY_ENTER** - Apply the selected option (Send `LV_EVENT_VALUE_CHANGED` event and close the drop-down list).
## Example
```eval_rst
.. include:: /lv_examples/src/lv_ex_widgets/lv_ex_dropdown/index.rst
```
## API
```eval_rst
.. doxygenfile:: lv_dropdown.h
:project: lvgl
```

70
docs/widgets/gauge.md Normal file
View File

@@ -0,0 +1,70 @@
```eval_rst
.. include:: /header.rst
:github_url: |github_link_base|/widgets/gauge.md
```
# Gauge (lv_gauge)
## Overview
The gauge is a meter with scale labels and one or more needles.
## Parts and Styles
The Gauge's main part is called `LV_GAUGE_PART_MAIN`. It draws a background using the typical background style properties and "minor" scale lines using the *line* and *scale* style properties.
It also uses the *text* properties to set the style of the scale labels. *pad_inner* is used to set space between the scale lines and the scale labels.
`LV_GAUGE_PART_MAJOR` is a virtual part which describes the major scale lines (where labels are added) using the *line* and *scale* style properties.
`LV_GAUGE_PART_NEEDLE` is also virtual part and it describes the needle(s) via the *line* style properties.
The *size* and the typical background properties are used to describe a rectangle (or circle) in the pivot point of the needle(s).
*pad_inner* is used to to make the needle(s) smaller than the outer radius of the scale lines.
## Usage
### Set value and needles
The gauge can show more than one needle.
Use the `lv_gauge_set_needle_count(gauge, needle_num, color_array)` function to set the number of needles and an array with colors for each needle.
The array must be static or global variable because only its pointer is stored.
You can use `lv_gauge_set_value(gauge, needle_id, value)` to set the value of a needle.
### Scale
You can use the `lv_gauge_set_scale(gauge, angle, line_num, label_cnt)` function to adjust the scale angle and the number of the scale lines and labels.
The default settings are 220 degrees, 6 scale labels, and 21 lines.
The scale of the Gauge can have offset. It can be adjusted with `lv_gauge_set_angle_offset(gauge, angle)`.
### Range
The range of the gauge can be specified by `lv_gauge_set_range(gauge, min, max)`. The default range is 0..100.
### Needle image
An images also can be used as needles. The image should point to the right (like `==>`). To set an image use `lv_gauge_set_needle_img(gauge1, &img, pivot_x, pivot_y)`. `pivot_x` and `pivot_y` are offset of the rotation center from the top left corner. Images will be recolored to the needle's color with `image_recolor_opa` intensity coming from the styles in `LV_GAUGE_PART_NEEDLE`.
### Critical value
To set a critical value, use `lv_gauge_set_critical_value(gauge, value)`. The scale color will be changed to *scale_end_color* after this value. The default critical value is 80.
## Events
Only the [Generic events](../overview/event.html#generic-events) are sent by the object type.
Learn more about [Events](/overview/event).
## Keys
No *Keys* are processed by the object type.
Learn more about [Keys](/overview/indev).
## Example
```eval_rst
.. include:: /lv_examples/src/lv_ex_widgets/lv_ex_gauge/index.rst
```
## API
```eval_rst
.. doxygenfile:: lv_gauge.h
:project: lvgl
```

124
docs/widgets/img.md Normal file
View File

@@ -0,0 +1,124 @@
```eval_rst
.. include:: /header.rst
:github_url: |github_link_base|/widgets/img.md
```
# Image (lv_img)
## Overview
*Images* are the basic object to display from the flash (as arrays) or externally as files. Images can display symbols (`LV_SYMBOL_...`) too.
Using the [Image decoder interface](/overview/image.html#image-decoder) custom image formats can be supported as well.
## Parts and Styles
The images has only a main part called `LV_IMG_PART_MAIN` which uses the typical background style propeties to draw a background rectangle and the *image* properties.
The padding values are used to make the background virtually larger. (It won't change the image's real size but the size modification is applied only during drawing)
## Usage
### Image source
To provide maximum flexibility, the source of the image can be:
- a variable in the code (a C array with the pixels).
- a file stored externally (like on an SD card).
- a text with [Symbols](/overview/font).
To set the source of an image, use `lv_img_set_src(img, src)`.
To generate a **pixel array** from a PNG, JPG or BMP image, use the [Online image converter tool](https://lvgl.io/tools/imageconverter) and set the converted image with its pointer: `lv_img_set_src(img1, &converted_img_var);`
To make the variable visible in the C file, you need to declare it with `LV_IMG_DECLARE(converted_img_var)`.
To use **external files**, you also need to convert the image files using the online converter tool but now you should select the binary Output format.
You also need to use LVGL's file system module and register a driver with some functions for the basic file operation. Got to the [File system](/overview/file-system) to learn more.
To set an image sourced from a file, use `lv_img_set_src(img, "S:folder1/my_img.bin")`.
You can set a **symbol** similarly to [Labels](/widgets/label). In this case, the image will be rendered as text according to the *font* specified in the style. It enables to use of light-weighted mono-color
"letters" instead of real images. You can set symbol like `lv_img_set_src(img1, LV_SYMBOL_OK)`.
### Label as an image
Images and labels are sometimes used to convey the same thing. For example, to describe what a button does. Therefore, images and labels are somewhat interchangeable.
To handle these images can even display texts by using `LV_SYMBOL_DUMMY` as the prefix of the text. For example, `lv_img_set_src(img, LV_SYMBOL_DUMMY "Some text")`.
### Transparency
The internal (variable) and external images support 2 transparency handling methods:
- **Chrome keying** - Pixels with `LV_COLOR_TRANSP` (*lv_conf.h*) color will be transparent.
- **Alpha byte** - An alpha byte is added to every pixel.
### Palette and Alpha index
Besides *True color* (RGB) color format, the following formats are also supported:
- **Indexed** - Image has a palette.
- **Alpha indexed** - Only alpha values are stored.
These options can be selected in the font converter. To learn more about the color formats, read the [Images](/overview/image) section.
### Recolor
The images can be re-colored in run-time to any color according to the brightness of the pixels.
It is very useful to show different states (selected, inactive, pressed, etc.) of an image without storing more versions of the same image.
This feature can be enabled in the style by setting `img.intense` between `LV_OPA_TRANSP` (no recolor, value: 0) and `LV_OPA_COVER` (full recolor, value: 255).
The default value is `LV_OPA_TRANSP` so this feature is disabled.
### Auto-size
It is possible to automatically set the size of the image object to the image source's width and height if enabled by the `lv_img_set_auto_size(image, true)` function.
If *auto-size* is enabled, then when a new file is set, the object size is automatically changed. Later, you can modify the size manually. The *auto-size* is enabled by default if the image is not a screen.
### Mosaic
If the object size is greater than the image size in any directions, then the image will be repeated like a mosaic.
It's a very useful feature to create a large image from only a very narrow source.
For example, you can have a *300 x 1* image with a special gradient and set it as a wallpaper using the mosaic feature.
### Offset
With `lv_img_set_offset_x(img, x_ofs)` and `lv_img_set_offset_y(img, y_ofs)`, you can add some offset to the displayed image.
It is useful if the object size is smaller than the image source size.
Using the offset parameter a [Texture atlas](https://en.wikipedia.org/wiki/Texture_atlas) or a "running image" effect can be created by [Animating](/overview/animation) the x or y offset.
## Transformations
Using the `lv_img_set_zoom(img, factor)` the images will be zoomed. Set `factor` to `256` or `LV_IMG_ZOOM_NONE` to disable zooming.
A larger value enlarges the images (e.g. `512` double size), a smaller value shrinks it (e.g. `128` half size).
Fractional scale works as well. E.g. `281` for 10% enlargement.
To rotate the image use `lv_img_set_angle(img, angle)`. Angle has 0.1 degree precision, so for 45.8° set 458.
By default, the pivot point of the rotation is the center of the image. It can be changed with `lv_img_set_pivot(img, pivot_x, pivot_y)`. `0;0` is the top left corner.
The quality of the transformation can be adjusted with `lv_img_set_antialias(img, true/false)`. With enabled anti-aliasing the transformations has a higher quality but they are slower.
The transformations require the whole image to be available. Therefore indexed images (`LV_IMG_CF_INDEXED_...`), alpha only images (`LV_IMG_CF_ALPHA_...`) or images from files can not be transformed.
In other words transformations work only on true color images stored as C array, or if a custom [Image decoder](/overview/images#image-edecoder) returns the whole image.
Note that, the real coordinates of image object won't change during transformation. That is `lv_obj_get_width/height/x/y()` will returned the original, non-zoomed coordinates.
## Rotate
The images can be rotated with
## Events
As by default, clicking of the image objects is disabled, only [generic](../overview/event.html#generic-events) non-input device-related events are sent.
If you want to catch all of the generic events of an image object, you should enable its clicking by using this: `lv_obj_set_click(img, true)`
Learn more about [Events](/overview/event).
## Keys
No *Keys* are processed by the object type.
Learn more about [Keys](/overview/indev).
## Example
```eval_rst
.. include:: /lv_examples/src/lv_ex_widgets/lv_ex_img/index.rst
```
## API
```eval_rst
.. doxygenfile:: lv_img.h
:project: lvgl
```

62
docs/widgets/imgbtn.md Normal file
View File

@@ -0,0 +1,62 @@
```eval_rst
.. include:: /header.rst
:github_url: |github_link_base|/widgets/imgbtn.md
```
# Image button (lv_imgbtn)
## Overview
The Image button is very similar to the simple 'Button' object. The only difference is that, it displays user-defined images in each state instead of drawing a rectangle.
Before reading this section, please read the [Button](/widgets/btn) section for better understanding.
## Parts and Styles
The Image button object has only a main part called `LV_IMG_BTN_PART_MAIN` from where all *image* style properties are used.
It's possible to recolor the image in each state with *image_recolor* and *image_recolor_opa* proeprties. For example, to make the image darker if it is pressed.
## Usage
### Image sources
To set the image in a state, use the `lv_imgbtn_set_src(imgbtn, LV_BTN_STATE_..., &img_src)`.
The image sources works the same as described in the [Image object](/widgets/img) except that, "Symbols" are not supported by the Image button.
If `LV_IMGBTN_TILED` is enabled in *lv_conf.h*, then `lv_imgbtn_set_src_tiled(imgbtn, LV_BTN_STATE_..., &img_src_left, &img_src_mid, &img_src_right)` becomes available.
Using the tiled feature the *middle* image will be repeated to fill the width of the object.
Therefore with `LV_IMGBTN_TILED`, you can set the width of the Image button using `lv_obj_set_width()`. However, without this option, the width will be always the same as the image source's width.
### Button features
Similarly to normal Buttons `lv_imgbtn_set_checkable(imgbtn, true/false)`, `lv_imgbtn_toggle(imgbtn)` and `lv_imgbtn_set_state(imgbtn, LV_BTN_STATE_...)` also works.
## Events
Beside the [Generic events](../overview/event.html#generic-events), the following [Special events](../overview/event.html#special-events) are sent by the buttons:
- **LV_EVENT_VALUE_CHANGED** - Sent when the button is toggled.
Note that, the generic input device related events (like `LV_EVENT_PRESSED`) are sent in the inactive state too. You need to check the state with `lv_btn_get_state(btn)` to ignore the events from inactive buttons.
Learn more about [Events](/overview/event).
## Keys
The following *Keys* are processed by the Buttons:
- **LV_KEY_RIGHT/UP** - Go to toggled state if toggling is enabled.
- **LV_KEY_LEFT/DOWN** - Go to non-toggled state if toggling is enabled.
Note that, as usual, the state of `LV_KEY_ENTER` is translated to `LV_EVENT_PRESSED/PRESSING/RELEASED` etc.
Learn more about [Keys](/overview/indev).
## Example
```eval_rst
.. include:: /lv_examples/src/lv_ex_widgets/lv_ex_imgbtn/index.rst
```
## API
```eval_rst
.. doxygenfile:: lv_imgbtn.h
:project: lvgl
```

48
docs/widgets/index.md Normal file
View File

@@ -0,0 +1,48 @@
```eval_rst
.. include:: /header.rst
:github_url: |github_link_base|/object-types/index.md
```
# Widgets
```eval_rst
.. toctree::
:maxdepth: 1
obj
arc
bar
btn
btnmatrix
calendar
canvas
checkbox
chart
cont
cpicker
dropdown
gauge
img
imgbtn
keyboard
label
led
line
list
linemeter
msgbox
objmask
page
roller
slider
spinbox
spinner
switch
table
tabview
textarea
tileview
win
```

89
docs/widgets/keyboard.md Normal file
View File

@@ -0,0 +1,89 @@
```eval_rst
.. include:: /header.rst
:github_url: |github_link_base|/widgets/keyboard.md
```
# Keyboard (lv_keyboard)
## Overview
The Keyboard object is a special [Button matrix](/widgets/btnmatrix) with predefined keymaps and other features to realize a virtual keyboard to write text.
## Parts and Styles
Similarly to Button matices Keyboards consist of 2 part:
- `LV_KEYBOARD_PART_BG` which is the main part and uses all the typical background properties
- `LV_KEYBOARD_PART_BTN` which is virtual part for the buttons. It also uses all typical backround proeprties and the *text* properties.
## Usage
### Modes
The Keyboards have thefollowing modes:
- **LV_KEYBOARD_MODE_TEXT_LOWER** - Display lower case letters
- **LV_KEYBOARD_MODE_TEXT_UPPER** - Display upper case letters
- **LV_KEYBOARD_MODE_TEXT_SPECIAL** - Display special characters
- **LV_KEYBOARD_MODE_NUM** - Display numbers, +/- sign, and decimal dot.
The `TEXT` modes' layout contains buttons to change mode.
To set the mode manually, use `lv_keyboard_set_mode(kb, mode)`. The default more is `LV_KEYBOARD_MODE_TEXT_UPPER`.
### Assign Text area
You can assign a [Text area](/widgets/textarea) to the Keyboard to automatically put the clicked characters there.
To assign the text area, use `lv_keyboard_set_textarea(kb, ta)`.
The assigned text area's **cursor can be managed** by the keyboard: when the keyboard is assigned, the previous text area's cursor will be hidden and the new one will be shown.
When the keyboard is closed by the *Ok* or *Close* buttons, the cursor also will be hidden. The cursor manager feature is enabled by `lv_keyboard_set_cursor_manage(kb, true)`. The default is not managed.
### New Keymap
You can specify a new map (layout) for the keyboard with `lv_keyboard_set_map(kb, map)` and `lv_keyboard_set_ctrl_map(kb, ctrl_map)`.
Learn more about the [Button matrix](/widgets/btnmatrix) object.
Keep in mind that, using following keywords will have the same effect as with the original map:
- *LV_SYMBOL_OK* - Apply.
- *LV_SYMBOL_CLOSE* - Close.
- *LV_SYMBOL_BACKSPACE* - Delete on the left.
- *LV_SYMBOL_LEFT* - Move the cursor left.
- *LV_SYMBOL_RIGHT* - Move the cursor right.
- *"ABC"* - Load the uppercase map.
- *"abc"* - Load the lower case map.
- *"Enter"* - New line.
## Events
Besides the [Generic events](../overview/event.html#generic-events), the following [Special events](../overview/event.html#special-events) are sent by the keyboards:
- **LV_EVENT_VALUE_CHANGED** - Sent when the button is pressed/released or repeated after long press. The event data is set to the ID of the pressed/released button.
- **LV_EVENT_APPLY** - The *Ok* button is clicked.
- **LV_EVENT_CANCEL** - The *Close* button is clicked.
The keyboard has a **default event handler** callback called `lv_keyboard_def_event_cb`.
It handles the button pressing, map changing, the assigned text area, etc.
You can completely replace it with your custom event handler however, you can call `lv_keyboard_def_event_cb` at the beginning of your event handler to handle the same things as before.
Learn more about [Events](/overview/event).
## Keys
The following *Keys* are processed by the buttons:
- **LV_KEY_RIGHT/UP/LEFT/RIGHT** - To navigate among the buttons and select one.
- **LV_KEY_ENTER** - To press/release the selected button.
Learn more about [Keys](/overview/indev).
## Examples
```eval_rst
.. include:: /lv_examples/src/lv_ex_widgets/lv_ex_keyboard/index.rst
```
## API
```eval_rst
.. doxygenfile:: lv_keyboard.h
:project: lvgl
```

100
docs/widgets/label.md Normal file
View File

@@ -0,0 +1,100 @@
```eval_rst
.. include:: /header.rst
:github_url: |github_link_base|/widgets/label.md
```
# Label (lv_label)
## Overview
A label is the basic object type that is used to display text.
## Parts and Styles
The label has only a main part, called `LV_LABEL_PART_MAIN`. It uses all the typical background properties and the *text* properties.
The padding values can be used to make the area for the text small in the related direction.
## Usage
### Set text
You can set the text on a label at runtime with `lv_label_set_text(label, "New text")`.
It will allocate a buffer dynamically, and the provided string will be copied into that buffer.
Therefore, you don't need to keep the text you pass to `lv_label_set_text` in scope after that function returns.
With `lv_label_set_text_fmt(label, "Value: %d", 15)` **printf formatting** can be used to set the text.
Labels are able to show text from a **static character buffer** which is `\0`-terminated.
To do so, use `lv_label_set_text_static(label, "Text")`.
In this case, the text is not stored in the dynamic memory and the given buffer is used directly instead.
This means that the array can't be a local variable which goes out of scope when the function exits.
Constant strings are safe to use with `lv_label_set_text_static` (except when used with `LV_LABEL_LONG_DOT`, as it modifies the buffer in-place), as they are stored in ROM memory, which is always accessible.
### Line break
Line breaks are handled automatically by the label object. You can use `\n` to make a line break. For example: `"line1\nline2\n\nline4"`
### Long modes
By default, the width of the label object automatically expands to the text size. Otherwise, the text can be manipulated according to several long mode policies:
* **LV_LABEL_LONG_EXPAND** - Expand the object size to the text size (Default)
* **LV_LABEL_LONG_BREAK** - Keep the object width, break (wrap) the too long lines and expand the object height
* **LV_LABEL_LONG_DOT** - Keep the object size, break the text and write dots in the last line (**not supported when using `lv_label_set_text_static`**)
* **LV_LABEL_LONG_SROLL** - Keep the size and scroll the label back and forth
* **LV_LABEL_LONG_SROLL_CIRC** - Keep the size and scroll the label circularly
* **LV_LABEL_LONG_CROP** - Keep the size and crop the text out of it
You can specify the long mode with `lv_label_set_long_mode(label, LV_LABEL_LONG_...)`
It's important to note that, when a label is created and its text is set, the label's size already expanded to the text size.
In addition with the default `LV_LABEL_LONG_EXPAND`, *long mode* `lv_obj_set_width/height/size()` has no effect.
So you need to change the *long mode* first set the new *long mode* and then set the size with `lv_obj_set_width/height/size()`.
Another important note is that **`LV_LABEL_LONG_DOT` manipulates the text buffer in-place** in order to add/remove the dots.
When `lv_label_set_text` or `lv_label_set_array_text` are used, a separate buffer is allocated and this implementation detail is unnoticed.
This is not the case with `lv_label_set_text_static`! **The buffer you pass to `lv_label_set_text_static` must be writable if you plan to use `LV_LABEL_LONG_DOT`.**
### Text align
The lines of the text can be aligned to the left, right or center with `lv_label_set_align(label, LV_LABEL_ALIGN_LEFT/RIGHT/CENTER)`. Note that, it will align only the lines, not the label object itself.
Vertical alignment is not supported by the label itself; you should place the label inside a larger container and align the whole label object instead.
### Text recolor
In the text, you can use commands to recolor parts of the text. For example: `"Write a #ff0000 red# word"`.
This feature can be enabled individually for each label by `lv_label_set_recolor()` function.
Note that, recoloring work only in a single line. Therefore, `\n` should not use in a recolored text or it should be wrapped by `LV_LABEL_LONG_BREAK` else, the text in the new line won't be recolored.
### Very long texts
Lvgl can efficiently handle very long (> 40k characters) by saving some extra data (~12 bytes) to speed up drawing. To enable this feature, set `LV_LABEL_LONG_TXT_HINT 1` in *lv_conf.h*.
### Symbols
The labels can display symbols alongside letters (or on their own). Read the [Font](/overview/font) section to learn more about the symbols.
## Events
Only the [Generic events](../overview/event.html#generic-events) are sent by the object type.
Learn more about [Events](/overview/event).
## Keys
No *Keys* are processed by the object type.
Learn more about [Keys](/overview/indev).
## Example
```eval_rst
.. include:: /lv_examples/src/lv_ex_widgets/lv_ex_label/index.rst
```
## API
```eval_rst
.. doxygenfile:: lv_label.h
:project: lvgl
```

48
docs/widgets/led.md Normal file
View File

@@ -0,0 +1,48 @@
```eval_rst
.. include:: /header.rst
:github_url: |github_link_base|/widgets/led.md
```
# LED (lv_led)
## Overview
The LEDs are rectangle-like (or circle) object. It's brightness can be adjusted. With lower brightness the the colors of the LED become darker.
## Parts and Styles
The LEDs have only one main part, called `LV_LED_PART_MAIN` and it uses all the typical background style properties.
## Usage
### Brightness
You can set their brightness with `lv_led_set_bright(led, bright)`. The brightness should be between 0 (darkest) and 255 (lightest).
### Toggle
Use `lv_led_on(led)` and `lv_led_off(led)` to set the brightness to a predefined ON or OFF value. The `lv_led_toggle(led)` toggles between the ON and OFF state.
## Events
Only the [Generic events](../overview/event.html#generic-events) are sent by the object type.
Learn more about [Events](/overview/event).
## Keys
No *Keys* are processed by the object type.
Learn more about [Keys](/overview/indev).
## Example
```eval_rst
.. include:: /lv_examples/src/lv_ex_widgets/lv_ex_led/index.rst
```
## API
```eval_rst
.. doxygenfile:: lv_led.h
:project: lvgl
```

52
docs/widgets/line.md Normal file
View File

@@ -0,0 +1,52 @@
```eval_rst
.. include:: /header.rst
:github_url: |github_link_base|/widgets/line.md
```
# Line (lv_line)
## Overview
The Line object is capable of drawing straight lines between a set of points.
## Parts and Styles
The Line has only a main part, called `LV_LABEL_PART_MAIN`. It uses all the *line* style properties.
## Usage
### Set points
The points has to be stored in an `lv_point_t` array and passed to the object by the `lv_line_set_points(lines, point_array, point_cnt)` function.
### Auto-size
It is possible to automatically set the size of the line object according to its points.
It can be enable with the `lv_line_set_auto_size(line, true)` function.
If enabled then when the points are set the object's width and height will be changed according to the maximal x and y coordinates among the points. The *auto size* is enabled by default.
### Invert y
By deafult, the *y == 0* point is in the top of the object. It might be conter-intuitive in some cases so the y coordinates can be inverted with `lv_line_set_y_invert(line, true)`. In this case, *y == 0* will be the bottom of teh obejct.
The *y invert* is disabled by default.
## Events
Only the [Generic events](../overview/event.html#generic-events) are sent by the object type.
Learn more about [Events](/overview/event).
## Keys
No *Keys* are processed by the object type.
Learn more about [Keys](/overview/indev).
## Example
```eval_rst
.. include:: /lv_examples/src/lv_ex_widgets/lv_ex_line/index.rst
```
## API
```eval_rst
.. doxygenfile:: lv_line.h
:project: lvgl
```

61
docs/widgets/linemeter.md Normal file
View File

@@ -0,0 +1,61 @@
```eval_rst
.. include:: /header.rst
:github_url: |github_link_base|/widgets/linemeter.md
```
# Line meter (lv_lmeter)
## Overview
The Line meter object consists of some radial lines which draw a scale. Setting a value for the Line meter will change the color of the scale lines proportionally.
## Parts and Styles
The Line meter has only a main part, called `LV_LINEMETER_PART_MAIN`. It uses all the typical background properties the draw a rectangle-like or circle background and the *line* and *scale* properties to draw the scale lines.
The active lines (which are related to smaller values the the current value) are colored from *line_color* to *scale_grad_color*. The lines in the end (after the current value) are set to *scale_end_color* color.
## Usage
### Set value
When setting a new value with `lv_linemeter_set_value(linemeter, new_value)` the proportional part of the scale will be recolored.
### Range and Angles
The `lv_linemeter_set_range(linemeter, min, max)` function sets the range of the line meter.
You can set the angle of the scale and the number of the lines by: `lv_linemeter_set_scale(linemeter, angle, line_num)`.
The default angle is 240 and the default line number is 31.
### Angle offset
By default the scale angle is interpreted symmetrically to the y axis. It results in "standing" line meter. With `lv_linemeter_set_angle_offset` an offset can be added the scale angle.
It can used e.g to put a quarter line meter into a corner or a half line meter to the right or left side.
### Mirror
By default the Line meter's lines are activated clock-wise. It can be changed using `lv_linemeter_set_mirror(linemeter, true/false)`.
## Events
Only the [Generic events](../overview/event.html#generic-events) are sent by the object type.
Learn more about [Events](/overview/event).
## Keys
No *Keys* are processed by the object type.
Learn more about [Keys](/overview/indev).
## Example
```eval_rst
.. include:: /lv_examples/src/lv_ex_widgets/lv_ex_linemeter/index.rst
```
## API
```eval_rst
.. doxygenfile:: lv_linemeter.h
:project: lvgl
```

95
docs/widgets/list.md Normal file
View File

@@ -0,0 +1,95 @@
```eval_rst
.. include:: /header.rst
:github_url: |github_link_base|/widgets/list.md
```
# List (lv_list)
## Overview
The Lists are built from a background [Page](/widgets/page) and [Buttons](/widgets/btn) on it.
The Buttons contain an optional icon-like [Image](/widgets/img) (which can be a symbol too) and a [Label](/widgets/label).
When the list becomes long enough it can be scrolled.
## Parts and Styles
The List has the same parts as the [Page](/widgets/page)
- `LV_LIST_PART_BG`
- `LV_LIST_PART_SCRL`
- `LV_LIST_PART_SCRLBAR`
- `LV_LIST_PART_EDGE_FLASH`
Refer to the [Page](/widgets/page) documentation for details.
The buttons on the list are treated as normal buttons and they only have a main part called `LV_BTN_PART_MAIN`.
## Usage
### Add buttons
You can add new list elements (button) with `lv_list_add_btn(list, &icon_img, "Text")` or with symbol `lv_list_add_btn(list, SYMBOL_EDIT, "Edit text")`.
If you do not want to add image use `NULL` as image source. The function returns with a pointer to the created button to allow further configurations.
The width of the buttons is set to maximum according to the object width.
The height of the buttons are adjusted automatically according to the content. (*content height* + *padding_top* + *padding_bottom*).
The labels are created with `LV_LABEL_LONG_SROLL_CIRC` long mode to automatically scroll the long labels circularly.
`lv_list_get_btn_label(list_btn)` and `lv_list_get_btn_img(list_btn)` can be used to get the label and the image of a list button.
The text can be et directly with `lv_list_get_btn_text(list_btn)`.
### Delete buttons
To delete a list element use `lv_list_remove(list, btn_index)`. btn_index can be obtained by `lv_list_get_btn_index(list, btn)` where btn is the return value of `lv_list_add_btn()`.
To clean the list (remove all buttons) use `lv_list_clean(list)`
### Manual navigation
You can navigate manually in the list with `lv_list_up(list)` and `lv_list_down(list)`.
You can focus on a button directly using `lv_list_focus(btn, LV_ANIM_ON/OFF)`.
The **animation time** of up/down/focus movements can be set via: `lv_list_set_anim_time(list, anim_time)`. Zero animation time means not animations.
### Layout
By default the list is vertical. To get a horizontal list use `lv_list_set_layout(list, LV_LAYOUT_ROW_MID)`.
### Edge flash
A circle-like effect can be shown when the list reaches the most top or bottom position.
`lv_list_set_edge_flash(list, true)` enables this feature.
### Scroll propagation
If the list is created on an other scrollable element (like a [Page](/widgets/page)) and the list can't be scrolled further the scrolling can be propagated to the parent.
This way the scroll will be continued on the parent. It can be enabled with `lv_list_set_scroll_propagation(list, true)`
## Events
Only the [Generic events](../overview/event.html#generic-events) are sent by the object type.
Learn more about [Events](/overview/event).
## Keys
The following *Keys* are processed by the Lists:
- **LV_KEY_RIGHT/DOWN** Select the next button
- **LV_KEY_LEFT/UP** Select the previous button
Note that, as usual, the state of `LV_KEY_ENTER` is translated to `LV_EVENT_PRESSED/PRESSING/RELEASED` etc.
The Selected buttons are in `LV_BTN_STATE_PR/TG_PR` state.
To manually select a button use `lv_list_set_btn_selected(list, btn)`. When the list is defocused and focused again it will restore the last selected button.
Learn more about [Keys](/overview/indev).
## Example
```eval_rst
.. include:: /lv_examples/src/lv_ex_widgets/lv_ex_list/index.rst
```
## API
```eval_rst
.. doxygenfile:: lv_list.h
:project: lvgl
```

72
docs/widgets/msgbox.md Normal file
View File

@@ -0,0 +1,72 @@
```eval_rst
.. include:: /header.rst
:github_url: |github_link_base|/widgets/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.
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)-
## 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
## Usage
### 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.
### 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.
The button matrix will be created only when `lv_msgbox_add_btns()` is called for the first time.
### 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)`.
## 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.
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
Learn more about [Keys](/overview/indev).
## Example
```eval_rst
.. include:: /lv_examples/src/lv_ex_widgets/lv_ex_msgbox/index.rst
```
## API
```eval_rst
.. doxygenfile:: lv_msgbox.h
:project: lvgl
```

227
docs/widgets/obj.md Normal file
View File

@@ -0,0 +1,227 @@
```eval_rst
.. include:: /header.rst
:github_url: |github_link_base|/widgets/obj.md
```
# Base object (lv_obj)
## Overview
The 'Base Object' implements the basic properties of widgets on a screen, such as:
- coordinates
- parent object
- children
- main style
- attributes like *Click enable*, *Drag enable*, etc.
In object-oriented thinking, it is the base class from which all other objects in LVGL are inherited. This, among another things, helps reduce code duplication.
The functions and functionalities of Base object can be used with other widgets too. For example `lv_obj_set_width(slider, 100)`
The Base object can be directly used as a simple widgets. It nothing else then a rectangle.
### Coordinates
#### Size
The object size can be modified on individual axes with `lv_obj_set_width(obj, new_width)` and `lv_obj_set_height(obj, new_height)`, or both axes can be modified at the same time with `lv_obj_set_size(obj, new_width, new_height)`.
Styles can add [Margin](/overview/style/#properties) to the objects. Margin tells that "I want this space around me".
To set width or height reduced by the margin `lv_obj_set_width_margin(obj, new_width)` or `lv_obj_set_height_margin(obj, new_height)`.
In more exact way: `new_width = left_margin + object_width + right_margin`.
To get the width or height which includes the margins use `lv_obj_get_width/height_margin(obj)`.
Styles can add [Padding](/overview/style/#properties) to the object as well. Padding means "I don't want my children too close to my sides, so keep this space".
To set width or height reduced by the padding `lv_obj_set_width_fit(obj, new_width)` or `lv_obj_set_height_fit(obj, new_height)`.
In a more exact way: `new_width = left_pad + object_width + right_pad`
To get the width or height which is REDUCED by padding use `lv_obj_get_width/height_fit(obj)`. It can be considered the "useful size of the object".
Margin and padding gets important when [Layout](/widget/cont#layout) or [Auto-fit](/wisgets/cont#fit) is used by other widgets.
#### Position
You can set the x and y coordinates relative to the parent with `lv_obj_set_x(obj, new_x)` and `lv_obj_set_y(obj, new_y)`, or both at the same time with `lv_obj_set_pos(obj, new_x, new_y)`.
#### Alignment
You can align the object to another with `lv_obj_align(obj, obj_ref, LV_ALIGN_..., x_ofs, y_ofs)`.
- `obj` is the object to align.
- `obj_ref` is a reference object. `obj` will be aligned to it. If `obj_ref = NULL`, then the parent of `obj` will be used.
- The third argument is the *type* of alignment. These are the possible options:
![](/misc/align.png "Alignment types in LVGL")
The alignment types build like `LV_ALIGN_OUT_TOP_MID`.
- The last two arguments allow you to shift the object by a specified number of pixels after aligning it.
For example, to align a text below an image: `lv_obj_align(text, image, LV_ALIGN_OUT_BOTTOM_MID, 0, 10)`.
Or to align a text in the middle of its parent: `lv_obj_align(text, NULL, LV_ALIGN_CENTER, 0, 0)`.
`lv_obj_align_origo` works similarly to `lv_obj_align` but it aligns the center of the object.
For example, `lv_obj_align_origo(btn, image, LV_ALIGN_OUT_BOTTOM_MID, 0, 0)` will align the center of the button the bottom of the image.
The parameters of the alignment will be saved in the object if `LV_USE_OBJ_REALIGN` is enabled in *lv_conf.h*. You can then realign the objects simply by calling `lv_obj_realign(obj)`.
It's equivalent to calling `lv_obj_align` again with the same parameters.
If the alignment happened with `lv_obj_align_origo`, then it will be used when the object is realigned.
The `lv_obj_align_x/y` and `lv_obj_align_origo_x/y` function can be used t align only on one axis.
If `lv_obj_set_auto_realign(obj, true)` is used the object will be realigned automatically, if its size changes in `lv_obj_set_width/height/size()` functions.
It's very useful when size animations are applied to the object and the original position needs to be kept.
**Note that the coordinates of screens can't be changed. Attempting to use these functions on screens will result in undefined behavior.**
### Parents and children
You can set a new parent for an object with `lv_obj_set_parent(obj, new_parent)`. To get the current parent, use `lv_obj_get_parent(obj)`.
To get the children of an object, use `lv_obj_get_child(obj, child_prev)` (from last to first) or `lv_obj_get_child_back(obj, child_prev)` (from first to last).
To get the first child, pass `NULL` as the second parameter and use the return value to iterate through the children. The function will return `NULL` if there are no more children. For example:
```c
lv_obj_t * child = lv_obj_get_child(parent, NULL);
while(child) {
/*Do something with "child" */
child = lv_obj_get_child(parent, child);
}
```
`lv_obj_count_children(obj)` tells the number of children on an object. `lv_obj_count_children_recursive(obj)` also tells the number of children but counts children of children recursively.
### Screens
When you have created a screen like `lv_obj_t * screen = lv_obj_create(NULL, NULL)`, you can load it with `lv_scr_load(screen)`. The `lv_scr_act()` function gives you a pointer to the current screen.
If you have more display then it's important to know that these functions operate on the lastly created or the explicitly selected (with `lv_disp_set_default`) display.
To get an object's screen use the `lv_obj_get_screen(obj)` function.
### Layers
There are two automatically generated layers:
- top layer
- system layer
They are independent of the screens and they will be shown on every screen. The *top layer* is above every object on the screen and the *system layer* is above the *top layer* too.
You can add any pop-up windows to the *top layer* freely. But, the *system layer* is restricted to system-level things (e.g. mouse cursor will be placed here in `lv_indev_set_cursor()`).
The `lv_layer_top()` and `lv_layer_sys()` functions gives a pointer to the top or system layer.
You can bring an object to the foreground or send it to the background with `lv_obj_move_foreground(obj)` and `lv_obj_move_background(obj)`.
Read the [Layer overview](/overview/layer) section to learn more about layers.
### Events
To set an event callback for an object, use `lv_obj_set_event_cb(obj, event_cb)`,
To manually send an event to an object, use `lv_event_send(obj, LV_EVENT_..., data)`
Read the [Event overview](/overview/event) to learn more about the events.
## Parts
The widgets can have multiple parts. For example a [Button](/widgets/btn) has only a main part but a [Slider](/widgets/slider) is built from a background, an indicator and a knob.
The name of the parts is constructed like `LV_ + <TYPE> _PART_ <NAME>`. For example `LV_BTN_PART_MAIN` or `LV_SLIDER_PART_KNOB`. The parts are usually used when styles are add to the objects.
Using parts different styles can be assigned to the different parts of the objects.
To learn more about the parts read the related section of the [Style overview](/overview/style#parts).
### States
The object can be in a combinations of the following states:
- **LV_STATE_DEFAULT** Normal, released
- **LV_STATE_CHECKED** Toggled or checked
- **LV_STATE_FOCUSED** Focused via keypad or encoder or clicked via touchpad/mouse
- **LV_STATE_EDITED**  Edit by an encoder
- **LV_STATE_HOVERED** Hovered by mouse (not supported now)
- **LV_STATE_PRESSED** Pressed
- **LV_STATE_DISABLED** Disabled or inactive
The states are usually automatically changed by the library as the user presses, releases, focuses etc an object.
However, the states can be changed manually too. To completely overwrite the current state use `lv_obj_set_state(obj, part, LV_STATE...)`.
To set or clear given state (but leave to other states untouched) use `lv_obj_add/clear_state(obj, part, LV_STATE_...)`
In both cases ORed state values can be used as well. E.g. `lv_obj_set_state(obj, part, LV_STATE_PRESSED | LV_PRESSED_CHECKED)`.
To learn more about the states read the related section of the [Style overview](/overview/style#states).
### Style
Be sure to read the [Style overview](/overview/style) first.
To add a style to an object use `lv_obj_add_style(obj, part, &new_style)` function. The Base object use all the rectangle-like style properties.
To remove all styles from an object use `lv_obj_reset_style_list(obj, part)`
If you modify a style, which is already used by objects, in order to refresh the affected objects you can use either `lv_obj_refresh_style(obj)` on each object using it or
to notify all objects with a given style use `lv_obj_report_style_mod(&style)`. If the parameter of `lv_obj_report_style_mod` is `NULL`, all objects will be notified.
### Attributes
There are some attributes which can be enabled/disabled by `lv_obj_set_...(obj, true/false)`:
- **hidden** - Hide the object. It will not be drawn and will be considered by input devices as if it doesn't exist., Its children will be hidden too.
- **click** - Allows you to click the object via input devices. If disabled, then click events are passed to the object behind this one. (E.g. [Labels](/widgets/label) are not clickable by default)
- **top** - If enabled then when this object or any of its children is clicked then this object comes to the foreground.
- **drag** - Enable dragging (moving by an input device)
- **drag_dir** - Enable dragging only in specific directions. Can be `LV_DRAG_DIR_HOR/VER/ALL`.
- **drag_throw** - Enable "throwing" with dragging as if the object would have momentum
- **drag_parent** - If enabled then the object's parent will be moved during dragging. It will look like as if the parent is dragged. Checked recursively, so can propagate to grandparents too.
- **parent_event** - Propagate the events to the parents too. Checked recursively, so can propagate to grandparents too.
- **opa_scale_enable** - Enable opacity scaling. See the [#opa-scale](Opa scale) section.
### Protect
There are some specific actions which happen automatically in the library.
To prevent one or more that kind of actions, you can protect the object against them. The following protections exists:
- **LV_PROTECT_NONE** No protection
- **LV_PROTECT_POS** Prevent automatic positioning (e.g. Layout in [Containers](/widgets/cont))
- **LV_PROTECT_FOLLOW** Prevent the object be followed (make a "line break") in automatic ordering (e.g. Layout in [Containers](/widgets/cont))
- **LV_PROTECT_PARENT** Prevent automatic parent change. (e.g. [Page](/widgets/page) moves the children created on the background to the scrollable)
- **LV_PROTECT_PRESS_LOST** Prevent losing press when the press is slid out of the objects. (E.g. a [Button](/widgets/btn) can be released out of it if it was being pressed)
- **LV_PROTECT_CLICK_FOCUS** Prevent automatically focusing the object if it's in a *Group* and click focus is enabled.
- **LV_PROTECT_CHILD_CHG** Disable the child change signal. Used internally by the library
The `lv_obj_add/clear_protect(obj, LV_PROTECT_...)` sets/clears the protection. You can use *'OR'ed* values of protection types too.
### Groups
Once, an object is added to *group* with `lv_group_add_obj(group, obj)` the object's current group can be get with `lv_obj_get_group(obj)`.
`lv_obj_is_focused(obj)` tells if the object is currently focused on its group or not. If the object is not added to a group, `false` will be returned.
Read the [Input devices overview](/overview/indev) to learn more about the *Groups*.
### Extended click area
By default, the objects can be clicked only on their coordinates, however, this area can be extended with `lv_obj_set_ext_click_area(obj, left, right, top, bottom)`.
`left/right/top/bottom` describes how far the clickable area should extend past the default in each direction.
This feature needs to enabled in *lv_conf.h* with `LV_USE_EXT_CLICK_AREA`. The possible values are:
- **LV_EXT_CLICK_AREA_FULL** store all 4 coordinates as `lv_coord_t`
- **LV_EXT_CLICK_AREA_TINY** store only horizontal and vertical coordinates (use the greater value of left/right and top/bottom) as `uint8_t`
- **LV_EXT_CLICK_AREA_OFF** Disable this feature
## Events
Only the [Generic events](../overview/event.html#generic-events) are sent by the object type.
Learn more about [Events](/overview/event).
## Keys
No *Keys* are processed by the object type.
Learn more about [Keys](/overview/indev).
## Example
```eval_rst
.. include:: /lv_examples/src/lv_ex_widgets/lv_ex_obj/index.rst
```
## API
```eval_rst
.. doxygenfile:: lv_obj.h
:project: lvgl
```

70
docs/widgets/objmask.md Normal file
View File

@@ -0,0 +1,70 @@
```eval_rst
.. include:: /header.rst
:github_url: |github_link_base|/widgets/objmask.md
```
# Object mask (lv_objmask)
## Overview
The *Object mask* is capable of add some mask to drawings when its children is drawn.
## Parts and Styles
The Object mask has only a main part called `LV_OBJMASK_PART_BG` and it uses the typical background style properties.
## Usage
### Adding mask
Before adding a mask to the *Object mask* the mask should be initialized:
```c
lv_draw_mask_<type>_param_t mask_param;
lv_draw_mask_<type>_init(&mask_param, ...);
lv_objmask_mask_t * mask_p = lv_objmask_add_mask(objmask, &mask_param);
```
Lvgl supports the following mask types:
- **line** clip the pixels on the top/bottom left/right of a line. Can be initialized from two points or a point and an angle:
- **angle** keep the pixels only between a given start and end angle
- **radius** keep the pixel only inside a rectangle which can have radius (can for a circle too). Can be inverted to keep the pixel outside of the rectangle.
- **fade** fade vertically (change the pixels opacity according to their y position)
- **map** use an alpha mask (a byte array) to describe the pixels opacity.
The coordinates in the mask are relative to the Object. That is if the object moves the masks move with it.
For the details of the mask *init* function see the [API](#api) documentation below.
### Update mask
AN existing mask can be updated with `lv_objmask_update_mask(objmask, mask_p, new_param)`, where `mask_p` is return value of `lv_objmask_add_mask`.
### Remove mask
A mask can be removed with `lv_objmask_remove_mask(objmask, mask_p)`
## Events
Only the [Generic events](../overview/event.html#generic-events) are sent by the object type.
Learn more about [Events](/overview/event).
## Keys
No *Keys* are processed by the object type.
Learn more about [Keys](/overview/indev).
## Example
```eval_rst
.. include:: /lv_examples/src/lv_ex_widgets/lv_ex_objmask/index.rst
```
## API
```eval_rst
.. doxygenfile:: lv_objmask.h
:project: lvgl
.. doxygenfile:: lv_draw_mask.h
:project: lvgl
```

111
docs/widgets/page.md Normal file
View File

@@ -0,0 +1,111 @@
```eval_rst
.. include:: /header.rst
:github_url: |github_link_base|/widgets/page.md
```
# Page (lv_page)
## Overview
The Page consist of two [Containers](/widgets/cont) on each other:
- a **background**
- a top which is **scrollable**.
## Parts and Styles
The Page's main part is called `LV_PAGE_PART_BG` which is the background of the Page. It uses all the typical background style properties. Using padding will add space on the sides.
The scrollable object can be referenced via the `LV_PAGE_PART_SCRL` part. It also uses all the typical background style properties and padding to add space on the sides.
`LV_LIST_PART_SCROLLBAR` is a virtual part of the background to draw the scroll bars. Uses all the typical background style properties, *size* to set the width of the scroll bars, and *pad_right* and *pad_bottom* to set the spacing.
`LV_LIST_PART_EDGE_FLASH`is also a virtual part of the background to draw a semicircle on the sides when the list can not be scrolled in that direction further. Uses all the typical background properties.
## Usage
The background object can be referenced as the page itself like. E.g. to set the page's width: `lv_obj_set_width(page, 100)`.
If a child is created on the page it will be automatically moved to the scrollable container.
If the scrollable container becomes larger then the background it can be scrolled by dragging (like the lists on smartphones).
By default, the scrollable's has `LV_FIT_MAX` fit in all directions.
It means the scrollable size will be the same as the background's size (minus the padding) while the children are in the background.
But when an object is positioned out of the background the scrollable size will be increased to involve it.
### Scrollbars
Scrollbars can be shown according to four policies:
- `LV_SCRLBAR_MODE_OFF` Never show scroll bars
- `LV_SCRLBAR_MODE_ON` Always show scroll bars
- `LV_SCRLBAR_MODE_DRAG` Show scroll bars when the page is being dragged
- `LV_SCRLBAR_MODE_AUTO` Show scroll bars when the scrollable container is large enough to be scrolled
- `LV_SCRLBAR_MODE_HIDE` Hide the scroll bar temporally
- `LV_SCRLBAR_MODE_UNHIDE` Unhide the previously hidden scrollbar. Recover the original mode too
The scroll bar show policy can be changed by: `lv_page_set_scrlbar_mode(page, SB_MODE)`. The default value is `LV_SCRLBAR_MODE_AUTO`.
### Glue object
A children can be "glued" to the page. In this case, if the page can be scrolled by dragging that object.
It can be enabled by the `lv_page_glue_obj(child, true)`.
### Focus object
An object on a page can be focused with `lv_page_focus(page, child, LV_ANIM_ONO/FF)`.
It will move the scrollable container to show a child. The time of the animation can be set by `lv_page_set_anim_time(page, anim_time)` in milliseconds.
`child` doesn't have to be a direct child of the page. This is it works if the scrollable object is the grandparent of the object too.
### Manual navigation
You can move the scrollable object manually using `lv_page_scroll_hor(page, dist)` and `lv_page_scroll_ver(page, dist)`
### Edge flash
A circle-like effect can be shown if the list reached the most top/bottom/left/right position. `lv_page_set_edge_flash(list, en)` enables this feature.
### Scroll propagation
If the list is created on an other scrollable element (like an other page) and the Page can't be scrolled further the scrolling can be propagated to the parent to continue the scrolling on the parent.
It can be enabled with `lv_page_set_scroll_propagation(list, true)`
## Clean the page
All the object created on the page can be clean with `lv_page_clean(page)`. Note that `lv_obj_clean(page)` doesn't work here because it would delete the scrollable object too.
### Scrollable API
There are functions to directly set/get the scrollable's attributes:
- `lv_page_get_scrl()`
- `lv_page_set_scrl_fit/fint2/fit4()`
- `lv_page_set_scrl_width()`
- `lv_page_set_scrl_height()`
- `lv_page_set_scrl_fit_width()`
- `lv_page_set_scrl_fit_height()`
- `lv_page_set_scrl_layout()`
## Events
Only the [Generic events](../overview/event.html#generic-events) are sent by the object type.
The scrollable object has a default event callback which propagates the following events to the background object:
`LV_EVENT_PRESSED`, `LV_EVENT_PRESSING`, `LV_EVENT_PRESS_LOST`,`LV_EVENT_RELEASED`, `LV_EVENT_SHORT_CLICKED`, `LV_EVENT_CLICKED`, `LV_EVENT_LONG_PRESSED`, `LV_EVENT_LONG_PRESSED_REPEAT`
Learn more about [Events](/overview/event).
##Keys
The following *Keys* are processed by the Page:
- **LV_KEY_RIGHT/LEFT/UP/DOWN** Scroll the page
Learn more about [Keys](/overview/indev).
## Example
```eval_rst
.. include:: /lv_examples/src/lv_ex_widgets/lv_ex_page/index.rst
```
## API
```eval_rst
.. doxygenfile:: lv_page.h
:project: lvgl
```

70
docs/widgets/roller.md Normal file
View File

@@ -0,0 +1,70 @@
```eval_rst
.. include:: /header.rst
:github_url: |github_link_base|/widgets/roller.md
```
# Roller (lv_roller)
## Overview
Roller allows you to simply select one option from more with scrolling.
## Parts and Styles
The Roller's main part is called `LV_ROLLER_PART_BG`. It's a rectangle and uses all the typical background properties.
The style of the Roller's label is inherited from the *text* style properties of the background.
To adjust the space between the options use the *text_line_space* style property.
The *padding* style properties set the space on the sides.
The selected option in the middle can be referenced with `LV_ROLLER_PART_SELECTED` virtual part. Besides the typical background properties it uses the *text* properties to change the appearance of the text in the selected area.
## Usage
### Set options
The options are passed to the Roller as a string with `lv_roller_set_options(roller, options, LV_ROLLER_MODE_NORMAL/INFINITE)`. The options should be separated by `\n`. For example: `"First\nSecond\nThird"`.
`LV_ROLLER_MODE_INFINITE` make the roller circular.
You can select an option manually with `lv_roller_set_selected(roller, id, LV_ANIM_ON/OFF)`, where *id* is the index of an option.
### Get selected option
The get the currently selected option use `lv_roller_get_selected(roller)` it will return the *index* of the selected option.
`lv_roller_get_selected_str(roller, buf, buf_size)` copy the name of the selected option to `buf`.
### Align the options
To align the label horizontally use `lv_roller_set_align(roller, LV_LABEL_ALIGN_LEFT/CENTER/RIGHT)`.
### Visible rows
The number of visible rows can be adjusted with `lv_roller_set_visible_row_count(roller, num)`
### Animation time
When the Roller is scrolled and doesn't stop exactly on an option it will scroll to the nearest valid option automatically.
The time of this scroll animation can be changed by `lv_roller_set_anim_time(roller, anim_time)`. Zero animation time means no animation.
## 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 a new option is selected
Learn more about [Events](/overview/event).
## Keys
The following *Keys* are processed by the Buttons:
- **LV_KEY_RIGHT/DOWN** Select the next option
- **LV_KEY_LEFT/UP** Select the previous option
- **LY_KEY_ENTER** Apply the selected option (Send `LV_EVENT_VALUE_CHANGED` event)
## Example
```eval_rst
.. include:: /lv_examples/src/lv_ex_widgets/lv_ex_roller/index.rst
```
## API
```eval_rst
.. doxygenfile:: lv_roller.h
:project: lvgl
```

71
docs/widgets/slider.md Normal file
View File

@@ -0,0 +1,71 @@
```eval_rst
.. include:: /header.rst
:github_url: |github_link_base|/widgets/slider.md
```
# Slider (lv_slider)
## Overview
The Slider object looks like a [Bar](/widgets/bar) supplemented with a knob. The knob can be dragged to set a value. The Slider also can be vertical or horizontal.
## Parts and Styles
The Slider's main part is called `LV_SLIDER_PART_BG` and it uses the typical background style properties.
`LV_SLIDER_PART_INDIC` is a virtual part which also uses all the typical background properties.
By default, the indicator maximal size is the same as the background's size but setting positive padding values in `LV_SLIDER_PART_BG` will make the indicator smaller. (negative values will make it larger)
If the *value* style property is used on the indicator the alignment will be calculated based on the current size of the indicator.
For example a center aligned value is always shown in the middle of the indicator regardless it's current size.
`LV_SLIDER_PART_KNOB` is a virtual part using all the typical background properties to describe the knob(s). Similarly to the *indicator* the *value* text is also aligned to the current position and size of the knob.
By default the knob is square (with a radius) with side length equal to the smaller side of the slider. The knob can be made larger with the *padding* values. Padding values can be asymmetric too.
## Usage
### Value and range
To set an initial value use `lv_slider_set_value(slider, new_value, LV_ANIM_ON/OFF)`.
`lv_slider_set_anim_time(slider, anim_time)` sets the animation time in milliseconds.
To specify the range (min, max values) the `lv_slider_set_range(slider, min , max)` can be used.
### Symmetrical and Range
Besides the normal type the Slider can be configured in two additional types:
- `LV_SLIDER_TYPE_NORMAL` normal type
- `LV_SLIDER_TYPE_SYMMETRICAL` draw the indicator symmetrical to zero (drawn from zero, left to right)
- `LV_SLIDER_TYPE_RANGE` allow the use of an additional knob for the left (start) value. (Can be used with `lv_slider_set/get_left_value()`)
The type can be changed with `lv_slider_set_type(slider, LV_SLIDER_TYPE_...)`
### Knob-only mode
Normally, the slider can be adjusted either by dragging the knob, or clicking on the slider bar.
In the latter case the knob moves to the point clicked and slider value changes accordingly. In some cases it is desirable to set the slider to react on dragging the knob only.
This feature is enabled by calling `lv_obj_set_adv_hittest(slider, true);`.
## 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 while the slider is being dragged or changed with keys. The event is sent continuously while the slider is dragged and only when it is released. Use `lv_slider_is_dragged` to decide whether is slider is being dragged or just released.
## 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
Learn more about [Keys](/overview/indev).
## Example
```eval_rst
.. include:: /lv_examples/src/lv_ex_widgets/lv_ex_slider/index.rst
```
## API
```eval_rst
.. doxygenfile:: lv_slider.h
:project: lvgl
```

62
docs/widgets/spinbox.md Normal file
View File

@@ -0,0 +1,62 @@
```eval_rst
.. include:: /header.rst
:github_url: |github_link_base|/widgets/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).
## 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.
`LV_SPINBOX_PART_CURSOR` is a virtual part describing the cursor. Read the [Text area](/widgets/textarea) documentation for a detailed description.
### 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_set_padding_left(spinbox, cnt)` add `cnt` "space" characters between the sign an the most left digit.
### Value and ranges
`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.
`lv_spinbox_increment(spinbox)` and `lv_spinbox_decrement(spinbox)` increments/decrements the value of the Spinbox.
`lv_spinbox_set_step(spinbox, step)` sets the amount to increment decrement.
## 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.
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.
## Example
```eval_rst
.. include:: /lv_examples/src/lv_ex_widgets/lv_ex_spinbox/index.rst
```
## API
```eval_rst
.. doxygenfile:: lv_spinbox.h
:project: lvgl
```
## Example

66
docs/widgets/spinner.md Normal file
View File

@@ -0,0 +1,66 @@
```eval_rst
.. include:: /header.rst
:github_url: |github_link_base|/widgets/spinner.md
```
# Spinner (lv_spinner)
## Overview
The Spinner object is a spinning arc over a border.
## 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.
## 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)`.
## Events
Only the [Generic events](../overview/event.html#generic-events) are sent by the object type.
## Keys
No *Keys* are processed by the object type.
Learn more about [Keys](/overview/indev).
## Example
```eval_rst
.. include:: /lv_examples/src/lv_ex_widgets/lv_ex_spinner/index.rst
```
### MicroPython
No examples yet.
## API
```eval_rst
.. doxygenfile:: lv_spinner.h
:project: lvgl
```

57
docs/widgets/switch.md Normal file
View File

@@ -0,0 +1,57 @@
```eval_rst
.. include:: /header.rst
:github_url: |github_link_base|/widgets/switch.md
```
# Switch (lv_switch)
## Overview
The Switch can be used to turn on/off something. It looks like a little slider.
## Parts and Styles
The Switch uses the the following parts:
- `LV_SWITCH_PART_BG`: main part
- `LV_SWITCH_PART_INDIC`: the indicator (virtual part)
- `LV_SWITCH_PART_KNOB`: the knob (virtual part)
The parts and style works the same as in case of [Slider](/widgets/slider). Read its documentation for a details description.
##Usage
### Change state
The state of the Switch can be changed by clicking on it or by `lv_switch_on(switch, LV_ANIM_ON/OFF)`, `lv_switch_off(switch, LV_ANIM_ON/OFF)` or `lv_switch_toggle(switch, LV_ANOM_ON/OFF)` functions
### Animation time
The time of animations, when the switch changes state, can be adjusted with `lv_switch_set_anim_time(switch, anim_time)`.
## Events
Besides the [Generic events](../overview/event.html#generic-events) the following [Special events](../overview/event.html#special-events) are sent by the Switch:
- **LV_EVENT_VALUE_CHANGED** Sent when the switch changes state.
## Keys
- **LV_KEY_UP**, **LV_KEY_RIGHT** Turn on the slider
- **LV_KEY_DOWN**, **LV_KEY_LEFT** Turn off the slider
Learn more about [Keys](/overview/indev).
## Example
```eval_rst
.. include:: /lv_examples/src/lv_ex_widgets/lv_ex_switch/index.rst
```
## API
```eval_rst
.. doxygenfile:: lv_switch.h
:project: lvgl
```

106
docs/widgets/table.md Normal file
View File

@@ -0,0 +1,106 @@
```eval_rst
.. include:: /header.rst
:github_url: |github_link_base|/widgets/table.md
```
# Table (lv_table)
## Overview
Tables, as usual, are built from rows, columns, and cells containing texts.
The Table object is very light weighted because only the texts are stored. No real objects are created for cells but they are just drawn on the fly.
## Parts and Styles
The main part of the Table is called `LV_TABLE_PART_BG`. It's a rectangle like background and uses all the typical background style properties.
For the cells there are 4 virtual parts. Every cell has type (1, 2, ... 16) which tells which part's styles to apply on them. The cell parts can be referenced by `LV_TABLE_PART_CELL1 + x` where `x` is between `0..15`.
The number of cell types can be adjusted in `lv_conf.h` by `LV_TABLE_CELL_STYLE_CNT`. By default it's 4. The default 4 cell types' part be referenced with dedicated names too:
- `LV_TABLE_PART_CELL1`
- `LV_TABLE_PART_CELL2`
- `LV_TABLE_PART_CELL3`
- `LV_TABLE_PART_CELL4`
The cells also use all the typical background style properties. If there is a line break (`\n`) in a cell's content then a horizontal division line will drawn after the line break using the *line* style properties.
The style of texts in the cells are inherited from the cell parts or the background part.
## Usage
### Rows and Columns
To set number of rows and columns use `lv_table_set_row_cnt(table, row_cnt)` and `lv_table_set_col_cnt(table, col_cnt)`
### Width and Height
The width of the columns can be set with `lv_table_set_col_width(table, col_id, width)`. The overall width of the Table object will be set to the sum of columns widths.
The height is calculated automatically from the cell styles (font, padding etc) and the number of rows.
### Set cell value
The cells can store only texts so numbers needs to be converted to text before displaying them in a table.
`lv_table_set_cell_value(table, row, col, "Content")`. The text is saved by the table so it can be even a local variable.
Line break can be used in the text like `"Value\n60.3"`.
### Align
The text alignment in cells can be adjusted individually with `lv_table_set_cell_align(table, row, col, LV_LABEL_ALIGN_LEFT/CENTER/RIGHT)`.
### Cell type
You can use 4 different cell types. Each has its own style.
Cell types can be used to add different style for example to:
- table header
- first column
- highlight a cell
- etc
The type can be selected with `lv_table_set_cell_type(table, row, col, type)` `type` can be 1, 2, 3 or 4.
### Merge cells
Cells can be merged horizontally with `lv_table_set_cell_merge_right(table, col, row, true)`. To merge more adjacent cells apply this function for each cell.
### Crop text
By default, the texts are word-wrapped to fit into the width of the cell and the height of the cell is set automatically.
To disable this and keep the text as it is enable `lv_table_set_cell_crop(table, row, col, true)`.
### Scroll
The make the Table scrollable place it on a [Page](/widgets/page)
## Events
Only the [Generic events](../overview/event.html#generic-events) are sent by the object type.
Learn more about [Events](/overview/event).
## Keys
No *Keys* are processed by the object type.
Learn more about [Keys](/overview/indev).
## Example
```eval_rst
.. include:: /lv_examples/src/lv_ex_widgets/lv_ex_table/index.rst
```
### MicroPython
No examples yet.
## API
```eval_rst
.. doxygenfile:: lv_table.h
:project: lvgl
```

104
docs/widgets/tabview.md Normal file
View File

@@ -0,0 +1,104 @@
```eval_rst
.. include:: /header.rst
:github_url: |github_link_base|/widgets/tabview.md
```
# Tabview (lv_tabview)
## Overview
The Tab view object can be used to organize content in tabs.
## 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.
## Usage
### Adding tab
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.
### Change tab
To select a new tab you can:
- Click on it on the Button matrix part
- Slide
- Use `lv_tabview_set_tab_act(tabview, id, LV_ANIM_ON/OFF)` function
### 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)`.
## 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
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
Learn more about [Keys](/overview/indev).
## Example
```eval_rst
.. include:: /lv_examples/src/lv_ex_widgets/lv_ex_tabview/index.rst
```
## API
```eval_rst
.. doxygenfile:: lv_tabview.h
:project: lvgl
```

147
docs/widgets/textarea.md Normal file
View File

@@ -0,0 +1,147 @@
```eval_rst
.. include:: /header.rst
:github_url: |github_link_base|/widgets/textarea.md
```
# Text area (lv_textarea)
## Overview
The Text Area is a [Page](/widgets/page) with a [Label](/widgets/label) and a cursor on it.
Texts or characters can be added to it.
Long lines are wrapped and when the text becomes long enough the Text area can be scrolled.
## Parts and Styles
The Text area 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.
Besides the Page parts the virtual `LV_TEXTAREA_PART_CURSOR` part exists to draw the cursor.
The cursor's area is always the bounding box of the current character.
A block cursor can be created by adding a background color and background opa to `LV_TEXTAREA_PART_CURSOR`'s style.
The create line cursor let the cursor transparent and set the *border_side* property.
## Usage
### Add text
You can insert text or characters to the current cursor's position with:
- `lv_textarea_add_char(textarea, 'c')`
- `lv_textarea_add_text(textarea, "insert this text")`
To add wide characters like `'á'`, `'ß'` or CJK characters use `lv_textarea_add_text(ta, "á")`.
`lv_textarea_set_text(ta, "New text")` changes the whole text.
### Placeholder
A placeholder text can be specified - which is displayed when the Text area is empty - with `lv_textarea_set_placeholder_text(ta, "Placeholder text")`
### Delete character
To delete a character from the left of the current cursor position use `lv_textarea_del_char(textarea)`.
To delete from the right use `lv_textarea_del_char_forward(textarea)`
### Move the cursor
The cursor position can be modified directly with `lv_textarea_set_cursor_pos(textarea, 10)`.
The `0` position means "before the first characters",
`LV_TA_CURSOR_LAST` means "after the last character"
You can step the cursor with
- `lv_textarea_cursor_right(textarea)`
- `lv_textarea_cursor_left(textarea)`
- `lv_textarea_cursor_up(textarea)`
- `lv_textarea_cursor_down(textarea)`
If `lv_textarea_set_cursor_click_pos(textarea, true)` is called the cursor will jump to the position where the Text area was clicked.
### Hide the cursor
The cursor can be hidden with `lv_textarea_set_cursor_hidden(textarea, true)`.
### Cursor blink time
The blink time of the cursor can be adjusted with `lv_textarea_set_cursor_blink_time(textarea, time_ms)`.
### One line mode
The Text area can be configures to be one lined with `lv_textarea_set_one_line(ta, true)`.
In this mode the height is set automatically to show only one line, line break character are ignored, and word wrap is disabled.
### Password mode
The text area supports password mode which can be enabled with `lv_textarea_set_pwd_mode(textarea, true)`.
If the `•` ([Bullet, U+2022](http://www.fileformat.info/info/unicode/char/2022/index.htm)) character exists in the font, the entered characters are converted to it after some time or when a new character is entered.
If `•` not exists, `*` will be used.
In password mode `lv_textarea_get_text(textarea)` gives the real text, not the bullet characters.
The visibility time can be adjusted with `lv_textarea_set_pwd_show_time(textarea, time_ms)`.
### Text align
The text can be aligned to the left, center or right with `lv_textarea_set_text_align(textarea, LV_LABEL_ALIGN_LET/CENTER/RIGHT)`.
In one line mode, the text can be scrolled horizontally only if the text is left aligned.
### Accepted characters
You can set a list of accepted characters with `lv_textarae_set_accepted_chars(ta, "0123456789.+-")`.
Other characters will be ignored.
### Max text length
The maximum number of characters can be limited with `lv_textarea_set_max_length(textarea, max_char_num)`
### Very long texts
If there is a very long text in the Text area (e. g. > 20k characters) its scrolling and drawing might be slow.
However, by enabling `LV_LABEL_LONG_TXT_HINT 1` in *lv_conf.h* it can be hugely improved.
It will save some info about the label to speed up its drawing.
Using `LV_LABEL_LONG_TXT_HINT` the scrolling and drawing will as fast as with "normal" short texts.
### Select text
A part of text can be selected if enabled with `lv_textarea_set_text_sel(textarea, true)`.
It works like when you select a text on your PC with your mouse.
### Scrollbars
The scrollbars can shown according to different policies set by `lv_textarea_set_scrollbar_mode(textarea, LV_SCRLBAR_MODE_...)`.
Learn more at the [Page](/widgets/page) object.
### Scroll propagation
When the Text area is scrolled on an other scrollable object (like a Page) and the scrolling has reached the edge of the Text area, the scrolling can be propagated to the parent.
In other words, when the Text area can be scrolled further, the parent will be scrolled instead.
It can be enabled with `lv_ta_set_scroll_propagation(ta, true)`.
Learn more at the [Page](/widgets/page) object.
### Edge flash
When the Text area is scrolled to edge a circle like flash animation can be shown if it is enabled with `lv_ta_set_edge_flash(ta, true)`
## 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_INSERT** Sent when before a character or text is inserted.
The event data is the text planned to insert. `lv_ta_set_insert_replace(ta, "New text")` replaces the text to insert.
The new text can't be in a local variable which is destroyed when the event callback exists. `""` means do not insert anything.
- **LV_EVENT_VALUE_CHANGED** When the content of the text area has been changed.
- **LV_EVENT_APPLY** When LV_KEY_ENTER is sent to a text area which is in one line mode.
## Keys
- **LV_KEY_UP/DOWN/LEFT/RIGHT** Move the cursor
- **Any character** Add the character to the current cursor position
Learn more about [Keys](/overview/indev).
## Example
```eval_rst
.. include:: /lv_examples/src/lv_ex_widgets/lv_ex_textarea/index.rst
```
## API
```eval_rst
.. doxygenfile:: lv_textarea.h
:project: lvgl
```

101
docs/widgets/tileview.md Normal file
View File

@@ -0,0 +1,101 @@
```eval_rst
.. include:: /header.rst
:github_url: |github_link_base|/widgets/tileview.md
```
# Tile view (lv_tileview)
## Overview
The Tileview 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.
If the Tileview is screen sized it gives a user interface you might have seen on the smartwatches.
## Parts and Styles
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
### Valid positions
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.
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.
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
### 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 *`)
## 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
Learn more about [Keys](/overview/indev).
## Example
```eval_rst
.. include:: /lv_examples/src/lv_ex_widgets/lv_ex_tileview/index.rst
```
## API
```eval_rst
.. doxygenfile:: lv_tileview.h
:project: lvgl
```

82
docs/widgets/win.md Normal file
View File

@@ -0,0 +1,82 @@
```eval_rst
.. include:: /header.rst
:github_url: |github_link_base|/widgets/win.md
```
# Window (lv_win)
## 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.
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.
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*.
### Title
On the header, there is a title which can be modified by: `lv_win_set_title(win, "New title")`.
### 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.
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.
`lv_win_close_event_cb` can be used as an event callback to close the Window.
### Scrollbars
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.
## Events
Only the [Generic events](../overview/event.html#generic-events) are sent by the object type.
Learn more about [Events](/overview/event).
## Keys
The following *Keys* are processed by the Page:
- **LV_KEY_RIGHT/LEFT/UP/DOWN** Scroll the page
Learn more about [Keys](/overview/indev).
## Example
```eval_rst
.. include:: /lv_examples/src/lv_ex_widgets/lv_ex_win/index.rst
```
## API
```eval_rst
.. doxygenfile:: lv_win.h
:project: lvgl
```