Parts and States

Widgets are built from multiple parts. For example, a Base Widget has "main" and "scrollbar" parts, while a Slider has "main", "indicator", and "knob" parts.

Parts

Widgets are built from multiple parts. For example, a Base Widget has "main" and "scrollbar" parts, while a Slider has "main", "indicator", and "knob" parts. Parts are similar to pseudo-elements in CSS.

The following predefined parts exist in LVGL:

• LV_PART_MAIN: A background-like rectangle.
• LV_PART_SCROLLBAR: The scrollbar(s).
• LV_PART_INDICATOR: The indicator, e.g., for sliders, bars, switches, or the tick box of a checkbox.
• LV_PART_KNOB: A handle used to adjust a value.
• LV_PART_SELECTED: Indicates the currently selected option or section.
• LV_PART_ITEMS: Used if the widget has multiple similar elements (e.g., table cells).
• LV_PART_CURSOR: Marks a specific position, e.g., the cursor in a text area or chart.
• LV_PART_CUSTOM_FIRST: Custom parts can be added starting from here.

The main purpose of parts is to allow styling individual "components" of a widget. They are described in more detail in the Style overview section.

States

A widget can be in a combination of the following states:

• LV_STATE_DEFAULT: Normal, released state.
• LV_STATE_ALT: Alternative style settings, e.g. dark mode.
• LV_STATE_CHECKED: Toggled or checked state.
• LV_STATE_FOCUSED: Focused via keypad, encoder, or clicked via touchpad/mouse.
• LV_STATE_FOCUS_KEY: Focused via keypad or encoder but not via touchpad/mouse.
• LV_STATE_EDITED: Being edited by an encoder.
• LV_STATE_HOVERED: Hovered by a mouse (currently not supported).
• LV_STATE_PRESSED: Being pressed.
• LV_STATE_SCROLLED: Being scrolled.
• LV_STATE_DISABLED: Disabled state.
• LV_STATE_USER_1: Custom state.
• LV_STATE_USER_2: Custom state.
• LV_STATE_USER_3: Custom state.
• LV_STATE_USER_4: Custom state.

States are usually changed automatically by the library as the user interacts with a widget (e.g., pressing, releasing, focusing). However, states can also be modified manually. To set or clear a given state (while leaving other states untouched), use:

• lv_obj_add_state(widget, LV_STATE_...)
• lv_obj_remove_state(widget, LV_STATE_...)

In both cases, you can bit-wise OR multiple state values. For example:

Every state also has a dedicated setter and getter for a single state, which is usually more convenient:

lv_obj_set_checked(widget, true);
if(lv_obj_is_disabled(widget)) { ... }

lv_obj_set_<state>() and lv_obj_is_<state>() exist for all states, e.g. lv_obj_set_alt, lv_obj_set_focused, lv_obj_set_pressed, lv_obj_is_edited. The custom states are named lv_obj_set_state_user_1...lv_obj_set_state_user_4() and lv_obj_is_state_user_1...lv_obj_is_state_user_4().

To learn more about states, see the related section in Styles Overview.