1.. _lv_checkbox:
2
3======================
4Checkbox (lv_checkbox)
5======================
6
7Overview
8********
9
10The Checkbox Widget is created from a "tick box" and a label. When the
11Checkbox is clicked the tick box is toggled.
12
13
14.. _lv_checkbox_parts_and_styles:
15
16Parts and Styles
17****************
18
19-  :cpp:enumerator:`LV_PART_MAIN` Background of Checkbox and it uses
20   the text and the :ref:`typical background style properties <typical bg props>`.
21   ``pad_column`` adjusts spacing between tickbox and label
22-  :cpp:enumerator:`LV_PART_INDICATOR` The "tick box" is a square that uses the
23   :ref:`typical background style properties <typical bg props>`.  By default, its
24   size is equal to the height of the main part's font. Padding properties make the
25   tick box larger in the respective directions.
26
27The Checkbox is added to the default group (if one is set).
28
29
30.. _lv_checkbox_usage:
31
32Usage
33*****
34
35Text
36----
37
38The text can be modified with
39:cpp:expr:`lv_checkbox_set_text(cb, "New text")` and will be
40dynamically allocated.
41
42To set static text, use :cpp:expr:`lv_checkbox_set_text_static(cb, txt)`. This
43way, only a pointer to ``txt`` will be stored.  The provided text buffer must remain
44available for the life of the Checkbox.
45
46Check, uncheck, disable
47-----------------------
48
49You can programmatically check, un-check, and disable the Checkbox by using the
50common state add/clear function:
51
52.. code-block:: c
53
54   lv_obj_add_state(cb, LV_STATE_CHECKED);    /* Make Checkbox checked */
55   lv_obj_remove_state(cb, LV_STATE_CHECKED); /* Make Checkbox unchecked */
56   lv_obj_add_state(cb, LV_STATE_CHECKED | LV_STATE_DISABLED); /* Make Checkbox checked and disabled */
57
58To find out whether the Checkbox is checked use
59:cpp:expr:`lv_obj_has_state(cb, LV_STATE_CHECKED)`.
60
61
62
63.. _lv_checkbox_events:
64
65Events
66******
67
68-  :cpp:enumerator:`LV_EVENT_VALUE_CHANGED` Sent when Checkbox is toggled.
69
70.. admonition::  Further Reading
71
72    Learn more about :ref:`lv_obj_events` emitted by all Widgets.
73
74    Learn more about :ref:`events`.
75
76
77
78.. _lv_checkbox_keys:
79
80Keys
81****
82
83The following *Keys* are processed by Checkbox:
84
85- ``LV_KEY_RIGHT/UP`` Go to CHECKED state if Checkbox is enabled
86- ``LV_KEY_LEFT/DOWN`` Go to non-CHECKED state if Checkbox is enabled
87- :cpp:enumerator:`LV_KEY_ENTER` Clicks the Checkbox and toggles its value.
88
89Note that, as usual, the state of :cpp:enumerator:`LV_KEY_ENTER` is translated to
90``LV_EVENT_PRESSED/PRESSING/RELEASED`` etc.
91
92.. admonition::  Further Reading
93
94    Learn more about :ref:`indev_keys`.
95
96
97
98.. _lv_checkbox_example:
99
100Example
101*******
102
103.. include:: ../../examples/widgets/checkbox/index.rst
104
105
106
107.. _lv_checkboxapi:
108
109API
110***
111