lvgl/docs/widgets/checkbox.md

.. include:: /header.rst 
:github_url: |github_link_base|/widgets/checkbox.md

Checkbox (lv_cb)

Overview

The Checkbox objects are built from a Button background which contains an also Button bullet and a 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 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 the following 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.

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.

Example

.. include:: /lv_examples/src/lv_ex_widgets/lv_ex_checkbox/index.rst

API

.. doxygenfile:: lv_checkbox.h
  :project: lvgl