klubhaus/klubhaus-doorbell
3
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

initial commit

Browse Source
This commit is contained in:
David Gwilliam
2026-02-12 00:45:31 -08:00
commit 5f168f370b
3024 changed files with 804889 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

116
libraries/lvgl/docs/widgets/core/arc.md Normal file
View File

@@ -0,0 +1,116 @@
# Arc (lv_arc)
## Overview
The Arc consists of a background and a foreground arc. The foreground (indicator) can be touch-adjusted.
## Parts and Styles
- `LV_PART_MAIN` Draws a background using the typical background style properties and an arc using the arc style properties. The arc's size and position will respect the *padding* style properties.
- `LV_PART_INDICATOR` Draws another arc using the *arc* style properties. Its padding values are interpreted relative to the background arc.
- `LV_PART_KNOB` Draws a handle on the end of the indicator using 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
### Value and range
A new value can be set using `lv_arc_set_value(arc, new_value)`.
The value is interpreted in a range (minimum and maximum values) which can be modified with `lv_arc_set_range(arc, min, max)`.
The default range is 0..100.
The indicator arc is drawn on the main part's arc. This if the value is set to maximum the indicator arc will cover the entire "background" arc.
To set the start and end angle of the background arc use the `lv_arc_set_bg_angles(arc, start_angle, end_angle)` functions or `lv_arc_set_bg_start/end_angle(arc, angle)`.
Zero degrees is at the middle right (3 o'clock) of the object and the degrees are increasing in clockwise direction.
The angles should be in the [0;360] range.
### Rotation
An offset to the 0 degree position can be added with `lv_arc_set_rotation(arc, deg)`.
### Mode
The arc can be one of the following modes:
- `LV_ARC_MODE_NORMAL` The indicator arc is drawn from the minimum value to the current.
- `LV_ARC_MODE_REVERSE` The indicator arc is drawn counter-clockwise from the maximum value to the current.
- `LV_ARC_MODE_SYMMETRICAL` The indicator arc is drawn from the middle point to the current value.
The mode can be set by `lv_arc_set_mode(arc, LV_ARC_MODE_...)` and used only if the angle is set by `lv_arc_set_value()` or the arc is adjusted by finger.
### Change rate
If the arc is pressed the current value will set with a limited speed according to the set *change rate*.
The change rate is defined in degree/second unit and can be set with `lv_arc_set_change_rage(arc, rate)`
### Setting the indicator manually
It's also possible to set the angles of the indicator arc directly with `lv_arc_set_angles(arc, start_angle, end_angle)` function or `lv_arc_set_start/end_angle(arc, start_angle)`.
In this case the set "value" and "mode" are ignored.
In other words, the angle and value settings are independent. You should exclusively use one or the other. Mixing the two might result in unintended behavior.
To make the arc non-adjustable, remove the style of the knob and make the object non-clickable:
```c
lv_obj_remove_style(arc, NULL, LV_PART_KNOB);
lv_obj_clear_flag(arc, LV_OBJ_FLAG_CLICKABLE);
```
### Advanced hit test
If the `LV_OBJ_FLAG_ADV_HITTEST` flag is enabled the arc can be clicked through in the middle. Clicks are recognized only on the ring of the background arc. `lv_obj_set_ext_click_size()` makes the sensitive area larger inside and outside with the given number of pixels.
### Place another object to the knob
Another object can be positioned according to the current position of the arc in order to follow the arc's current value (angle).
To do this use `lv_arc_align_obj_to_angle(arc, obj_to_align, radius_offset)`.
Similarly `lv_arc_rotate_obj_to_angle(arc, obj_to_rotate, radius_offset)` can be used to rotate the object to the current value of the arc.
It's a typical use case to call these functions in the `VALUE_CHANGED` event of the arc.
## Events
- `LV_EVENT_VALUE_CHANGED` sent when the arc is pressed/dragged to set a new value.
- `LV_EVENT_DRAW_PART_BEGIN` and `LV_EVENT_DRAW_PART_END` are sent with the following types:
- `LV_ARC_DRAW_PART_BACKGROUND` The background arc.
- `part`: `LV_PART_MAIN`
- `p1`: center of the arc
- `radius`: radius of the arc
- `arc_dsc`
- `LV_ARC_DRAW_PART_FOREGROUND` The foreground arc.
- `part`: `LV_PART_INDICATOR`
- `p1`: center of the arc
- `radius`: radius of the arc
- `arc_dsc`
- LV_ARC_DRAW_PART_KNOB The knob
- `part`: `LV_PART_KNOB`
- `draw_area`: the area of the knob
- `rect_dsc`:
See the events of the [Base object](/widgets/obj) too.
Learn more about [Events](/overview/event).
## Keys
- `LV_KEY_RIGHT/UP` Increases the value by one.
- `LV_KEY_LEFT/DOWN` Decreases the value by one.
Learn more about [Keys](/overview/indev).
## Example
```eval_rst
.. include:: ../../../examples/widgets/arc/index.rst
```
## API
```eval_rst
.. doxygenfile:: lv_arc.h
:project: lvgl
```

62
libraries/lvgl/docs/widgets/core/bar.md Normal file
View File

@@ -0,0 +1,62 @@
# 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 the end, but also the start value of the bar can be set, which changes the start position of the indicator.
## Parts and Styles
- `LV_PART_MAIN` The background of the bar and it uses the typical background style properties. Adding padding makes the indicator smaller or larger. The `anim_time` style property sets the animation time if the values set with `LV_ANIM_ON`.
- `LV_PART_INDICATOR` The indicator itself; also uses all the typical background properties.
## 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 0..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`).
### Modes
The bar can be one of the following modes:
- `LV_BAR_MODE_NORMAL` A normal bar as described above
- `LV_BAR_MODE_SYMMETRICAL` Draw the indicator from the zero value to current value. Requires a negative minimum range and positive maximum range.
- `LV_BAR_MODE_RANGE` Allows setting the start value too by `lv_bar_set_start_value(bar, new_value, LV_ANIM_ON/OFF)`. The start value always has to be smaller than the end value.
## Events
- `LV_EVENT_DRAW_PART_BEGIN` and `LV_EVENT_DRAW_PART_END` are sent for the following parts:
- `LV_BAR_DRAW_PART_INDICATOR` The indicator of the bar
- `part`: `LV_PART_INDICATOR`
- `draw_area`: area of the indicator
- `rect_dsc`
See the events of the [Base object](/widgets/obj) too.
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:: ../../../examples/widgets/bar/index.rst
```
## API
```eval_rst
.. doxygenfile:: lv_bar.h
:project: lvgl
```

46
libraries/lvgl/docs/widgets/core/btn.md Normal file
View File

@@ -0,0 +1,46 @@
# Button (lv_btn)
## Overview
Buttons have no new features compared to the [Base object](/widgets/obj). They are useful for semantic purposes and have slightly different default settings.
Buttons, by default, differ from Base object in the following ways:
- Not scrollable
- Added to the default group
- Default height and width set to `LV_SIZE_CONTENT`
## Parts and Styles
- `LV_PART_MAIN` The background of the button. Uses the typical background style properties.
## Usage
There are no new features compared to [Base object](/widgets/obj).
## Events
- `LV_EVENT_VALUE_CHANGED` when the `LV_OBJ_FLAG_CHECKABLE` flag is enabled and the object is clicked. The event happens on transition to/from the checked state.
Learn more about [Events](/overview/event).
## Keys
Note that the state of `LV_KEY_ENTER` is translated to `LV_EVENT_PRESSED/PRESSING/RELEASED` etc.
See the events of the [Base object](/widgets/obj) too.
Learn more about [Keys](/overview/indev).
## Example
```eval_rst
.. include:: ../../../examples/widgets/btn/index.rst
```
## API
```eval_rst
.. doxygenfile:: lv_btn.h
:project: lvgl
```

95
libraries/lvgl/docs/widgets/core/btnmatrix.md Normal file
View File

@@ -0,0 +1,95 @@
# Button matrix (lv_btnmatrix)
## Overview
The Button Matrix object is a lightweight way to display multiple buttons in rows and columns. Lightweight because the buttons are not actually created but just virtually drawn on the fly. This way, one button use only eight extra bytes of memory instead of the ~100-150 bytes a normal [Button](/widgets/core/btn) object plus the 100 or so bytes for the [Label](/widgets/core/label) object.
The Button matrix is added to the default group (if one is set). Besides the Button matrix is an editable object to allow selecting and clicking the buttons with encoder navigation too.
## Parts and Styles
- `LV_PART_MAIN` The background of the button matrix, uses the typical background style properties. `pad_row` and `pad_column` sets the space between the buttons.
- `LV_PART_ITEMS` The buttons all use the text and typical background style properties except translations and transformations.
## 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", NULL}`.
Note that the last element has to be either `NULL` or an empty string (`""`)!
Use `"\n"` in the map to insert a **line break**. E.g. `{"btn1", "btn2", "\n", "btn3", ""}`. Each line's buttons have their width calculated automatically.
So in the example the first row will have 2 buttons each with 50% width and a second row with 1 button having 100% width.
### Control buttons
The buttons' width can be set relative to the other button in the same row 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.
The width must be in the \[1..15\] range and the default width is 1.
In addition to the width, each button can be customized with the following parameters:
- `LV_BTNMATRIX_CTRL_HIDDEN` Makes 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` Makes a button disabled Like `LV_STATE_DISABLED` on normal objects
- `LV_BTNMATRIX_CTRL_CHECKABLE` Enable toggling of a button. I.e. `LV_STATE_CHECHED` will be added/removed as the button is clicked
- `LV_BTNMATRIX_CTRL_CHECKED` Make the button checked. It will use the `LV_STATE_CHECHKED` styles.
- `LV_BTNMATRIX_CTRL_CLICK_TRIG` Enabled: send LV_EVENT_VALUE_CHANGE on CLICK, Disabled: send LV_EVENT_VALUE_CHANGE on PRESS
- `LV_BTNMATRIX_CTRL_POPOVER` Show the button label in a popover when pressing this key
- `LV_BTNMATRIX_CTRL_RECOLOR` Enable recoloring of button texts with `#`. E.g. `"It's #ff0000 red#"`
- `LV_BTNMATRIX_CTRL_CUSTOM_1` Custom free to use flag
- `LV_BTNMATRIX_CTRL_CUSTOM_2` Custom free to use flag
By default, all flags are disabled.
To 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_BTNMATRIX_CTRL_...)` respectively. More `LV_BTNM_CTRL_...` values can be OR-ed
To set/clear the same control attribute for all buttons of a button matrix, use `lv_btnmatrix_set_btn_ctrl_all(btnm, LV_BTNM_CTRL_...)` and
`lv_btnmatrix_clear_btn_ctrl_all(btnm, LV_BTNMATRIX_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_CHECHKABLE`.
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_checked(btnm, true)` to allow only one button to be checked at a time.
## Events
- `LV_EVENT_VALUE_CHANGED` Sent when a button is pressed/released or repeated after long press. The event parameter is set to the ID of the pressed/released button.
- `LV_EVENT_DRAW_PART_BEGIN` and `LV_EVENT_DRAW_PART_END` are sent for the following types:
- `LV_BTNMATRIX_DRAW_PART_BTN` The individual buttons.
- `part`: `LV_PART_ITEMS`
- `id`:index of the button being drawn
- `draw_area`: the area of teh button
- `rect_dsc`
See the events of the [Base object](/widgets/obj) too.
`lv_btnmatrix_get_selected_btn(btnm)` returns the index of the most recently released or focused button or `LV_BTNMATRIX_BTN_NONE` if no such button.
`lv_btnmatrix_get_btn_text(btnm, btn_id)` returns a pointer to the text of `btn_id`th button.
Learn more about [Events](/overview/event).
## Keys
- `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:: ../../../examples/widgets/btnmatrix/index.rst
```
## API
```eval_rst
.. doxygenfile:: lv_btnmatrix.h
:project: lvgl
```

103
libraries/lvgl/docs/widgets/core/canvas.md Normal file
View File

@@ -0,0 +1,103 @@
# Canvas (lv_canvas)
## Overview
A Canvas inherits from [Image](/widgets/core/img) where the user can draw anything.
Rectangles, texts, images, lines, arcs can be drawn here using lvgl's drawing engine.
Additionally "effects" can be applied, such as rotation, zoom and blur.
## Parts and Styles
`LV_PART_MAIN` Uses the typical rectangle style properties and image style properties.
## Usage
### Buffer
The Canvas needs a buffer in 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.
### Indexed colors
For `LV_IMG_CF_INDEXED_1/2/4/8` 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's color on the canvas, use `lv_canvas_set_px_color(canvas, x, y, LV_COLOR_RED)`.
With `LV_IMG_CF_INDEXED_...` the index of the color needs to be passed as color.
E.g. `lv_color_t c; c.full = 3;`
To set a pixel's opacity with `LV_IMG_CF_TRUE_COLOR_ALPHA` or `LV_IMG_CF_ALPHA_...` format on the canvas, use `lv_canvas_set_px_opa(canvas, x, y, opa)`.
`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`) the 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_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/arc_dsc_t` variable which should be first initialized with one of `lv_draw_rect/label/img/line/arc_dsc_init()` and then 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 [draw mask](/overview/drawing) 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 another 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)` or 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
No special events are sent by canvas objects.
The same events are sent as for the
See the events of the [Images](/widgets/core/img) too.
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:: ../../../examples/widgets/canvas/index.rst
```
## API
```eval_rst
.. doxygenfile:: lv_canvas.h
:project: lvgl
```

72
libraries/lvgl/docs/widgets/core/checkbox.md Normal file
View File

@@ -0,0 +1,72 @@
# Checkbox (lv_checkbox)
## Overview
The Checkbox object is created from a "tick box" and a label. When the Checkbox is clicked the tick box is toggled.
## Parts and Styles
- `LV_PART_MAIN` The is the background of the Checkbox and it uses the text and all the typical background style properties.
`pad_column` adjusts the spacing between the tickbox and the label
- `LV_PART_INDICATOR` The "tick box" is a square that uses all the typical background style properties.
By default, its size is equal to the height of the main part's font. Padding properties make the tick box larger in the respective directions.
The Checkbox is added to the default group (if it is set).
## Usage
### Text
The text can be modified with the `lv_checkbox_set_text(cb, "New text")` function and will be dynamically allocated.
To set a static text,
use `lv_checkbox_set_static_text(cb, txt)`. This way, only a pointer to `txt` will be stored. The text then shouldn't be deallocated while the checkbox exists.
### Check, uncheck, disable
You can manually check, un-check, and disable the Checkbox by using the common state add/clear function:
```c
lv_obj_add_state(cb, LV_STATE_CHECKED); /*Make the chekbox checked*/
lv_obj_clear_state(cb, LV_STATE_CHECKED); /*MAke the checkbox unchecked*/
lv_obj_add_state(cb, LV_STATE_CHECKED | LV_STATE_DISABLED); /*Make the checkbox checked and disabled*/
```
## Events
- `LV_EVENT_VALUE_CHANGED` Sent when the checkbox is toggled.
- `LV_EVENT_DRAW_PART_BEGIN` and `LV_EVENT_DRAW_PART_END` are sent for the following types:
- `LV_CHECKBOX_DRAW_PART_BOX` The tickbox of the checkbox
- `part`: `LV_PART_INDICATOR`
- `draw_area`: the area of the tickbox
- `rect_dsc`
See the events of the [Base object](/widgets/obj) too.
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
- `LV_KEY_ENTER` Clicks the checkbox and toggles it
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:: ../../../examples/widgets/checkbox/index.rst
```
## API
```eval_rst
.. doxygenfile:: lv_checkbox.h
:project: lvgl
```

105
libraries/lvgl/docs/widgets/core/dropdown.md Normal file
View File

@@ -0,0 +1,105 @@
# 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 again.
The Drop-down list is added to the default group (if it is set). Besides the Drop-down list is an editable object to allow selecting an option with encoder navigation too.
## Parts and Styles
The Dropdown widget is built from the elements: "button" and "list" (both not related to the button and list widgets)
### Button
- `LV_PART_MAIN` The background of the button. Uses the typical background properties and text properties for the text on it.
- `LV_PART_INDICATOR` Typically an arrow symbol that can be an image or a text (`LV_SYMBOL`).
The button goes to `LV_STATE_CHECKED` when it's opened.
### List
- `LV_PART_MAIN` The list itself. Uses the typical background properties. `max_height` can be used to limit the height of the list.
- `LV_PART_SCROLLBAR` The scrollbar background, border, shadow properties and width (for its own width) and right padding for the spacing on the right.
- `LV_PART_SELECTED` Refers to the currently pressed, checked or pressed+checked option. Also uses the typical background properties.
The list is hidden/shown on open/close. To add styles to it use `lv_dropdown_get_list(dropdown)` to get the list object. For example:
```c
lv_obj_t * list = lv_dropdown_get_list(dropdown) /*Get the list*/
lv_obj_add_style(list, &my_style, ...) /*Add the styles to the list*/}`
```
Alternatively the theme can be extended with the new styles.
## Usage
## Overview
### Set options
Options are passed to the drop-down list as a string with `lv_dropdown_set_options(dropdown, options)`. Options should be separated by `\n`. For example: `"First\nSecond\nThird"`. This string will be saved in the drop-down list, so it can in a local variable.
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_options_static(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 *index* of the selected option, use `lv_dropdown_get_selected(dropdown)`.
`lv_dropdown_get_selected_str(dropdown, buf, buf_size)` copies the *name* of the selected option to `buf`.
### Direction
The list can be created on any side. The default `LV_DIR_BOTTOM` can be modified by `lv_dropdown_set_dir(dropdown, LV_DIR_LEFT/RIGHT/UP/BOTTOM)` function.
If the list would be vertically out of the screen, it will be aligned to the edge.
### Symbol
A symbol (typically an arrow) can be added to the dropdown list with `lv_dropdown_set_symbol(dropdown, LV_SYMBOL_...)`
If the direction of the drop-down list is `LV_DIR_LEFT` the symbol will be shown on the left, otherwise on the right.
### Show selected
The main part can either show the selected option or a static text. If a static is set with `lv_dropdown_set_text(dropdown, "Some text")` it will be shown regardless to th selected option.
If the text is `NULL` the selected option is displayed on the button.
### Manually open/close
To manually open or close the drop-down list the `lv_dropdown_open/close(dropdown)` function can be used.
## Events
Apart from 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 or the list is opened/closed.
- `LV_EVENT_CANCEL` Sent when the list is closed
- `LV_EVENT_READY` Sent when the list is opened
See the events of the [Base object](/widgets/obj) too.
Learn more about [Events](/overview/event).
## Keys
- `LV_KEY_RIGHT/DOWN` Select the next option.
- `LV_KEY_LEFT/UP` Select the previous option.
- `LY_KEY_ENTER` Apply the selected option (Sends `LV_EVENT_VALUE_CHANGED` event and closes the drop-down list).
Learn more about [Keys](/overview/indev).
## Example
```eval_rst
.. include:: ../../../examples/widgets/dropdown/index.rst
```
## API
```eval_rst
.. doxygenfile:: lv_dropdown.h
:project: lvgl
```

139
libraries/lvgl/docs/widgets/core/img.md Normal file
View File

@@ -0,0 +1,139 @@
# Image (lv_img)
## Overview
Images are the basic object to display images from flash (as arrays) or from 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
- `LV_PART_MAIN` A background rectangle that uses the typical background style properties and the image itself using the image style properties.
## Usage
### Image source
To provide maximum flexibility, the source of the image can be:
- a variable in code (a C array with the pixels).
- a file stored externally (e.g. 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. Go 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 also set a symbol similarly to [Labels](/widgets/core/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-weight monochrome "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, that is the images can 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:
- **Chroma-keying** - Pixels with `LV_COLOR_CHROMA_KEY` (*lv_conf.h*) color will be transparent.
- **Alpha byte** - An alpha byte is added to every pixel that contains the pixel's opacity
### Palette and Alpha index
Besides the *True color* (RGB) color format, the following formats are supported:
- **Indexed** - Image has a palette.
- **Alpha indexed** - Only alpha values are stored.
These options can be selected in the image converter. To learn more about the color formats, read the [Images](/overview/image) section.
### Recolor
A color can be mixed with every pixel of an image with a given intensity.
This can be useful to show different states (checked, 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_recolor_opa` 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.
The color to mix is set by `img_recolor`.
### Auto-size
If the width or height of the image object is set to `LV_SIZE_CONTENT` the object's size will be set according to the size of the image source in the respective direction.
### Mosaic
If the object's size is greater than the image size in any directions, then the image will be repeated like a mosaic.
This allows creation a large image from only a very narrow source.
For example, you can have a *300 x 5* 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.
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.
The `transform_zoom` and `transform_angle` style properties are also used to determine the final zoom and angle.
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 are higher quality but 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 objects won't change during transformation. That is `lv_obj_get_width/height/x/y()` will return the original, non-zoomed coordinates.
**IMPORTANT**
The transformation of the image is independent of the transformation properties coming from styles. (See [here](/overview/style#opacity-and-transformations)). The main differences are that pure image widget transformation
- doesn't transform the children of the image widget
- image is transformed directly without creating an intermediate layer (buffer) to snapshot the widget
### Size mode
By default, when the image is zoomed or rotated the real coordinates of the image object are not changed.
The larger content simply overflows the object's boundaries.
It also means the layouts are not affected the by the transformations.
If you need the object size to be updated to the transformed size set `lv_img_set_size_mode(img, LV_IMG_SIZE_MODE_REAL)`. (The previous mode is the default and called `LV_IMG_SIZE_MODE_VIRTUAL`).
In this case if the width/height of the object is set to `LV_SIZE_CONTENT` the object's size will be set to the zoomed and rotated size.
If an explicit size is set then the overflowing content will be cropped.
### Rounded image
You can use `lv_obj_set_style_radius` to set radius to an image, and enable `lv_obj_set_style_clip_corner` to clip the
content to rounded rectangle or circular shape. Please note this will have some negative performance impact to CPU
based renderers.
## Events
No special events are sent by image objects.
See the events of the [Base object](/widgets/obj) too.
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:: ../../../examples/widgets/img/index.rst
```
## API
```eval_rst
.. doxygenfile:: lv_img.h
:project: lvgl
```

26
libraries/lvgl/docs/widgets/core/index.md Normal file
View File

@@ -0,0 +1,26 @@
# Core widgets
```eval_rst
.. toctree::
:maxdepth: 1
arc
bar
btn
btnmatrix
canvas
checkbox
dropdown
img
label
line
roller
slider
switch
table
textarea
```

94
libraries/lvgl/docs/widgets/core/label.md Normal file
View File

@@ -0,0 +1,94 @@
# Label (lv_label)
## Overview
A label is the basic object type that is used to display text.
## Parts and Styles
- `LV_PART_MAIN` Uses all the typical background properties and the text properties. The padding values can be used to add space between the text and the background.
- `LV_PART_SCROLLBAR` The scrollbar that is shown when the text is larger than the widget's size.
- `LV_PART_SELECTED` Tells the style of the [selected text](#text-selection). Only `text_color` and `bg_color` style properties can be used.
## Usage
### Set text
You can set the text on a label at runtime with `lv_label_set_text(label, "New text")`.
This 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. 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.
### Newline
Newline characters 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 and height of the label is set to `LV_SIZE_CONTENT`. Therefore, the size of the label is automatically expanded to the text size.
Otherwise, if the width or height are explicitly set (using e.g.`lv_obj_set_width` or a layout), the lines wider than the label's width can be manipulated according to several long mode policies.
Similarly, the policies can be applied if the height of the text is greater than the height of the label.
- `LV_LABEL_LONG_WRAP` Wrap too long lines. If the height is `LV_SIZE_CONTENT` the label's height will be expanded, otherwise the text will be clipped. (Default)
- `LV_LABEL_LONG_DOT` Replaces the last 3 characters from bottom right corner of the label with dots (`.`)
- `LV_LABEL_LONG_SCROLL` If the text is wider than the label scroll it horizontally back and forth. If it's higher, scroll vertically. Only one direction is scrolled and horizontal scrolling has higher precedence.
- `LV_LABEL_LONG_SCROLL_CIRCULAR` If the text is wider than the label scroll it horizontally continuously. If it's higher, scroll vertically. Only one direction is scrolled and horizontal scrolling has higher precedence.
- `LV_LABEL_LONG_CLIP` Simply clip the parts of the text outside the label.
You can specify the long mode with `lv_label_set_long_mode(label, LV_LABEL_LONG_...)`
Note 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 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,
recoloring is only supported when the text wrapped with `##ff0000 ... #`sintax is in one line,
it is not supported in wrapped text, see example `Line wrap, recoloring and scrolling`.
### Text selection
If enabled by `LV_LABEL_TEXT_SELECTION` part of the text can be selected. It's similar to when you use your mouse on a PC to select a text.
The whole mechanism (click and select the text as you drag your finger/mouse) is implemented in [Text area](/widgets/core/textarea) and the Label widget only allows manual text selection with
`lv_label_get_text_selection_start(label, start_char_index)` and `lv_label_get_text_selection_start(label, end_char_index)`.
### Very long texts
LVGL can efficiently handle very long (e.g. > 40k characters) labels 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`.
### Custom scrolling animations
Some aspects of the scrolling animations in long modes `LV_LABEL_LONG_SCROLL` and `LV_LABEL_LONG_SCROLL_CIRCULAR` can be customized by setting the animation property of a style, using `lv_style_set_anim()`.
Currently, only the start and repeat delay of the circular scrolling animation can be customized. If you need to customize another aspect of the scrolling animation, feel free to open an [issue on Github](https://github.com/lvgl/lvgl/issues) to request the feature.
### 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
No special events are sent by the Label.
See the events of the [Base object](/widgets/obj) too.
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:: ../../../examples/widgets/label/index.rst
```
## API
```eval_rst
.. doxygenfile:: lv_label.h
:project: lvgl
```

48
libraries/lvgl/docs/widgets/core/line.md Normal file
View File

@@ -0,0 +1,48 @@
# Line (lv_line)
## Overview
The Line object is capable of drawing straight lines between a set of points.
## Parts and Styles
- `LV_PART_MAIN` uses all the typical background properties and line style properties.
## Usage
### Set points
The points have 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
By default, the Line's width and height are set to `LV_SIZE_CONTENT`. This means it will automatically set its size to fit all the points. If the size is set explicitly, parts on the line may not be visible.
### Invert y
By default, the *y == 0* point is in the top of the object. It might be counter-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 the object.
*y invert* is disabled by default.
## Events
Only the [Generic events](../overview/event.html#generic-events) are sent by the object type.
See the events of the [Base object](/widgets/obj) too.
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:: ../../../examples/widgets/line/index.rst
```
## API
```eval_rst
.. doxygenfile:: lv_line.h
:project: lvgl
```

58
libraries/lvgl/docs/widgets/core/roller.md Normal file
View File

@@ -0,0 +1,58 @@
# Roller (lv_roller)
## Overview
Roller allows you to simply select one option from a list by scrolling.
## Parts and Styles
- `LV_PART_MAIN` The background of the roller uses all the typical background properties and text style properties. `style_text_line_space` adjusts the space between the options.
When the Roller is scrolled and doesn't stop exactly on an option it will scroll to the nearest valid option automatically in `anim_time` milliseconds as specified in the style.
- `LV_PART_SELECTED` The selected option in the middle. Besides the typical background properties it uses the text style properties to change the appearance of the text in the selected area.
## Usage
### Set options
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` makes 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
To get the *index* of the currently selected option use `lv_roller_get_selected(roller)`.
`lv_roller_get_selected_str(roller, buf, buf_size)` will copy the name of the selected option to `buf`.
### Visible rows
The number of visible rows can be adjusted with `lv_roller_set_visible_row_count(roller, num)`.
This function calculates the height with the current style. If the font, line space, border width, etc. of the roller changes this function needs to be called again.
## Events
- `LV_EVENT_VALUE_CHANGED` Sent when a new option is selected.
See the events of the [Base object](/widgets/obj) too.
Learn more about [Events](/overview/event).
## Keys
- `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:: ../../../examples/widgets/roller/index.rst
```
## API
```eval_rst
.. doxygenfile:: lv_roller.h
:project: lvgl
```

74
libraries/lvgl/docs/widgets/core/slider.md Normal file
View File

@@ -0,0 +1,74 @@
# Slider (lv_slider)
## Overview
The Slider object looks like a [Bar](/widgets/core/bar) supplemented with a knob. The knob can be dragged to set a value. Just like Bar, Slider can be vertical or horizontal.
## Parts and Styles
- `LV_PART_MAIN` The background of the slider. Uses all the typical background style properties. `padding` makes the indicator smaller in the respective direction.
- `LV_PART_INDICATOR` The indicator that shows the current state of the slider. Also uses all the typical background style properties.
- `LV_PART_KNOB` A rectangle (or circle) drawn at the current value. Also uses all the typical background properties to describe the knob(s). By default, the knob is square (with an optional corner 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)`. The animation time is set by the styles' `anim_time` property.
To specify the range (min, max values), `lv_slider_set_range(slider, min , max)` can be used.
### Modes
The slider can be one of the following modes:
- `LV_SLIDER_MODE_NORMAL` A normal slider as described above
- `LV_SLIDER_SYMMETRICAL` Draw the indicator form the zero value to current value. Requires negative minimum range and positive maximum range.
- `LV_SLIDER_RANGE` Allows setting the start value too by `lv_bar_set_start_value(bar, new_value, LV_ANIM_ON/OFF)`. The start value has to be always smaller than the end value.
The mode can be changed with `lv_slider_set_mode(slider, LV_SLIDER_MODE_...)`
### Knob-only mode
Normally, the slider can be adjusted either by dragging the knob, or by 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 adding the `LV_OBJ_FLAG_ADV_HITTEST`: `lv_obj_add_flag(slider, LV_OBJ_FLAG_ADV_HITTEST)`.
The extended click area (set by `lv_obj_set_ext_click_area(slider, value)`) increases to knob's click area.
## Events
- `LV_EVENT_VALUE_CHANGED` Sent while the slider is being dragged or changed with keys. The event is sent continuously while the slider is being dragged.
- `LV_EVENT_RELEASED` Sent when the slider has just been released.
- `LV_EVENT_DRAW_PART_BEGIN` and `LV_EVENT_DRAW_PART_END` are sent for the following parts.
- `LV_SLIDER_DRAW_PART_KNOB` The main (right) knob of the slider
- `part`: `LV_PART_KNOB`
- `draw_area`: area of the indicator
- `rect_dsc`
- `id`: 0
- `LV_SLIDER_DRAW_PART_KNOB` The left knob of the slider
- `part`: `LV_PART_KNOB`
- `draw_area`: area of the indicator
- `rect_dsc`
- `id`: 1
See the events of the [Bar](/widgets/core/bar) too.
Learn more about [Events](/overview/event).
## Keys
- `LV_KEY_UP/RIGHT` Increment the slider's value by 1
- `LV_KEY_DOWN/LEFT` Decrement the slider's value by 1
Learn more about [Keys](/overview/indev).
## Example
```eval_rst
.. include:: ../../../examples/widgets/slider/index.rst
```
## API
```eval_rst
.. doxygenfile:: lv_slider.h
:project: lvgl
```

53
libraries/lvgl/docs/widgets/core/switch.md Normal file
View File

@@ -0,0 +1,53 @@
# Switch (lv_switch)
## Overview
The Switch looks like a little slider and can be used to turn something on and off.
## Parts and Styles
- `LV_PART_MAIN` The background of the switch uses all the typical background style properties. `padding` makes the indicator smaller in the respective direction.
- `LV_PART_INDICATOR` The indicator that shows the current state of the switch. Also uses all the typical background style properties.
- `LV_PART_KNOB` A rectangle (or circle) drawn at left or right side of the indicator. Also uses all the typical background properties to describe the knob(s). By default, the knob is square (with an optional corner 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
### Change state
The switch uses the standard `LV_STATE_CHECKED` state.
To get the current state of the switch (with `true` being on), use `lv_obj_has_state(switch, LV_STATE_CHECKED)`.
Call `lv_obj_add_state(switch, LV_STATE_CHECKED)` to turn it on, or `lv_obj_clear_state(switch, LV_STATE_CHECKED)` to turn it off.
## Events
- `LV_EVENT_VALUE_CHANGED` Sent when the switch changes state.
See the events of the [Base object](/widgets/obj) too.
Learn more about [Events](/overview/event).
## Keys
- `LV_KEY_UP/RIGHT` Turns on the slider
- `LV_KEY_DOWN/LEFT` Turns off the slider
- `LV_KEY_ENTER` Toggles the switch
Learn more about [Keys](/overview/indev).
## Example
```eval_rst
.. include:: ../../../examples/widgets/switch/index.rst
```
## API
```eval_rst
.. doxygenfile:: lv_switch.h
:project: lvgl
```

91
libraries/lvgl/docs/widgets/core/table.md Normal file
View File

@@ -0,0 +1,91 @@
# Table (lv_table)
## Overview
Tables, as usual, are built from rows, columns, and cells containing texts.
The Table object is very lightweight because only the texts are stored. No real objects are created for cells but they are just drawn on the fly.
The Table is added to the default group (if it is set). Besides the Table is an editable object to allow selecting a cell with encoder navigation too.
## Parts and Styles
- `LV_PART_MAIN` The background of the table uses all the typical background style properties.
- `LV_PART_ITEMS` The cells of the table also use all the typical background style properties and the text properties.
## Usage
### Set cell value
The cells can store only text so numbers need 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 breaks can be used in the text like `"Value\n60.3"`.
New rows and columns are automatically added is required
### Rows and Columns
To explicitly 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.
### Merge cells
Cells can be merged horizontally with `lv_table_add_cell_ctrl(table, row, col, LV_TABLE_CELL_CTRL_MERGE_RIGHT)`. To merge more adjacent cells call this function for each cell.
### Scroll
If the label's width or height is set to `LV_SIZE_CONTENT` that size will be used to show the whole table in the respective direction.
E.g. `lv_obj_set_size(table, LV_SIZE_CONTENT, LV_SIZE_CONTENT)` automatically sets the table size to show all the columns and rows.
If the width or height is set to a smaller number than the "intrinsic" size then the table becomes scrollable.
## Events
- `LV_EVENT_VALUE_CHANGED` Sent when a new cell is selected with keys.
- `LV_EVENT_DRAW_PART_BEGIN` and `LV_EVENT_DRAW_PART_END` are sent for the following types:
- `LV_TABLE_DRAW_PART_CELL` The individual cells of the table
- `part`: `LV_PART_ITEMS`
- `draw_area`: area of the indicator
- `rect_dsc`
- `label_dsc`
- `id`: current row × col count + current column
See the events of the [Base object](/widgets/obj) too.
Learn more about [Events](/overview/event).
## Keys
The following *Keys* are processed by the Tables:
- `LV_KEY_RIGHT/LEFT/UP/DOWN/` Select a cell.
Note that, as usual, the state of `LV_KEY_ENTER` is translated to `LV_EVENT_PRESSED/PRESSING/RELEASED` etc.
`lv_table_get_selected_cell(table, &row, &col)` can be used to get the currently selected cell. Row and column will be set to `LV_TABLE_CELL_NONE` no cell is selected.
Learn more about [Keys](/overview/indev).
## Example
```eval_rst
.. include:: ../../../examples/widgets/table/index.rst
```
### MicroPython
No examples yet.
## API
```eval_rst
.. doxygenfile:: lv_table.h
:project: lvgl
```

122
libraries/lvgl/docs/widgets/core/textarea.md Normal file
View File

@@ -0,0 +1,122 @@
# Text area (lv_textarea)
## Overview
The Text Area is a [Base object](widgets/obj) with a [Label](/widgets/core/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.
One line mode and password modes are supported.
## Parts and Styles
- `LV_PART_MAIN` The background of the text area. Uses all the typical background style properties and the text related style properties including `text_align` to align the text to the left, right or center.
- `LV_PART_SCROLLBAR` The scrollbar that is shown when the text is too long.
- `LV_PART_SELECTED` Determines the style of the [selected text](/widgets/core/label.html#text-selection). Only `text_color` and `bg_color` style properties can be used. `bg_color` should be set directly on the label of the text area.
- `LV_PART_CURSOR` Marks the position where the characters are inserted. The cursor's area is always the bounding box of the current character.
A block cursor can be created by adding a background color and background opacity to `LV_PART_CURSOR`'s style. The create line cursor leave the cursor transparent and set a left border.
The `anim_time` style property sets the cursor's blink time.
- `LV_PART_TEXTAREA_PLACEHOLDER` Unique to Text Area, allows styling the placeholder text.
## 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 like `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 applied the cursor will jump to the position where the Text area was clicked.
### Hide the cursor
The cursor is always visible, however it can be a good idea to style it to be visible only in `LV_STATE_FOCUSED` state.
### One line mode
The Text area can be configured to be on a single line with `lv_textarea_set_one_line(textarea, true)`.
In this mode the height is set automatically to show only one line, line break characters are ignored, and word wrap is disabled.
### Password mode
The text area supports password mode which can be enabled with `lv_textarea_set_password_mode(textarea, true)`.
By default, 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 `•` does not exist in the font, `*` will be used. You can override the default character with `lv_textarea_set_password_bullet(textarea, "x")`.
In password mode `lv_textarea_get_text(textarea)` returns the actual text entered, not the bullet characters.
The visibility time can be adjusted with `LV_TEXTAREA_DEF_PWD_SHOW_TIME)` in `lv_conf.h`.
### Accepted characters
You can set a list of accepted characters with `lv_textarea_set_accepted_chars(textarea, "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), scrolling and drawing might be slow.
However, by enabling `LV_LABEL_LONG_TXT_HINT 1` in `lv_conf.h` the performance can be hugely improved.
This will save some additional information about the label to speed up its drawing.
Using `LV_LABEL_LONG_TXT_HINT` the scrolling and drawing will as fast as with "normal" short texts.
### Select text
Any part of the text can be selected if enabled with `lv_textarea_set_text_selection(textarea, true)`.
This works much like when you select text on your PC with your mouse.
## Events
- `LV_EVENT_INSERT` Sent right before a character or text is inserted.
The event parameter is the text about to be inserted. `lv_textarea_set_insert_replace(textarea, "New text")` replaces the text to insert.
The new text cannot be in a local variable which is destroyed when the event callback exists. `""` means do not insert anything.
- `LV_EVENT_VALUE_CHANGED` Sent when the content of the text area has been changed.
- `LV_EVENT_READY` Sent when `LV_KEY_ENTER` is pressed (or sent) to a one line text area.
See the events of the [Base object](/widgets/obj) too.
Learn more about [Events](/overview/event).
## 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:: ../../../examples/widgets/textarea/index.rst
```
## API
```eval_rst
.. doxygenfile:: lv_textarea.h
:project: lvgl
```