1# Checkbox (lv_checkbox)
2
3
4## Overview
5
6The Checkbox object is created from a "tick box" and a label. When the Checkbox is clicked the tick box is toggled.
7
8## Parts and Styles
9- `LV_PART_MAIN` The is the background of the Checkbox and it uses the text and all the typical background style properties.
10`pad_column` adjusts the spacing between the tickbox and the label
11- `LV_PART_INDICATOR` The "tick box" is a square that uses all the typical background style properties.
12By 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.
13
14The Checkbox is added to the default group (if it is set).
15
16## Usage
17
18
19### Text
20The text can be modified with the `lv_checkbox_set_text(cb, "New text")` function and will be dynamically allocated.
21
22To set a static text,
23use `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.
24
25### Check, uncheck, disable
26You can manually check, un-check, and disable the Checkbox by using the common state add/clear function:
27```c
28lv_obj_add_state(cb, LV_STATE_CHECKED);   /*Make the chekbox checked*/
29lv_obj_clear_state(cb, LV_STATE_CHECKED); /*MAke the checkbox unchecked*/
30lv_obj_add_state(cb, LV_STATE_CHECKED | LV_STATE_DISABLED); /*Make the checkbox checked and disabled*/
31```
32
33## Events
34- `LV_EVENT_VALUE_CHANGED` Sent when the checkbox is toggled.
35- `LV_EVENT_DRAW_PART_BEGIN` and `LV_EVENT_DRAW_PART_END` are sent for the following types:
36    - `LV_CHECKBOX_DRAW_PART_BOX` The tickbox of the checkbox
37        - `part`: `LV_PART_INDICATOR`
38        - `draw_area`: the area of the tickbox
39        - `rect_dsc`
40
41See the events of the [Base object](/widgets/obj) too.
42
43Learn more about [Events](/overview/event).
44
45
46## Keys
47The following *Keys* are processed by the 'Buttons':
48- `LV_KEY_RIGHT/UP` Go to toggled state if toggling is enabled
49- `LV_KEY_LEFT/DOWN` Go to non-toggled state if toggling is  enabled
50- `LV_KEY_ENTER` Clicks the checkbox and toggles it
51
52Note that, as usual, the state of `LV_KEY_ENTER` is translated to `LV_EVENT_PRESSED/PRESSING/RELEASED` etc.
53
54Learn more about [Keys](/overview/indev).
55
56
57## Example
58
59```eval_rst
60
61.. include:: ../../../examples/widgets/checkbox/index.rst
62
63```
64
65## API
66
67```eval_rst
68
69.. doxygenfile:: lv_checkbox.h
70  :project: lvgl
71
72```
73