lv_obj.h

Defines

LV_ASSERT_OBJ(obj_p, obj_class)
LV_TRACE_OBJ_CREATE(...)

Enums

enum _lv_state_t

Possible states of a widget. OR-ed values are possible

Values:

enumerator LV_STATE_DEFAULT
enumerator LV_STATE_CHECKED
enumerator LV_STATE_FOCUSED
enumerator LV_STATE_FOCUS_KEY
enumerator LV_STATE_EDITED
enumerator LV_STATE_HOVERED
enumerator LV_STATE_PRESSED
enumerator LV_STATE_SCROLLED
enumerator LV_STATE_DISABLED
enumerator LV_STATE_USER_1
enumerator LV_STATE_USER_2
enumerator LV_STATE_USER_3
enumerator LV_STATE_USER_4
enumerator LV_STATE_ANY

Special value can be used in some functions to target all states

enum _lv_part_t

The possible parts of widgets. The parts can be considered as the internal building block of the widgets. E.g. slider = background + indicator + knob Not all parts are used by every widget

Values:

enumerator LV_PART_MAIN

A background like rectangle

enumerator LV_PART_SCROLLBAR

The scrollbar(s)

enumerator LV_PART_INDICATOR

Indicator, e.g. for slider, bar, switch, or the tick box of the checkbox

enumerator LV_PART_KNOB

Like handle to grab to adjust the value

enumerator LV_PART_SELECTED

Indicate the currently selected option or section

enumerator LV_PART_ITEMS

Used if the widget has multiple similar elements (e.g. table cells)

enumerator LV_PART_CURSOR

Mark a specific place e.g. for text area's cursor or on a chart

enumerator LV_PART_CUSTOM_FIRST

Extension point for custom widgets

enumerator LV_PART_ANY

Special value can be used in some functions to target all parts

enum _lv_obj_flag_t

On/Off features controlling the object's behavior. OR-ed values are possible

Note: update obj flags corresponding properties below whenever add/remove flags or change bit definition of flags.

Values:

enumerator LV_OBJ_FLAG_HIDDEN

Make the object hidden. (Like it wasn't there at all)

enumerator LV_OBJ_FLAG_CLICKABLE

Make the object clickable by the input devices

enumerator LV_OBJ_FLAG_CLICK_FOCUSABLE

Add focused state to the object when clicked

enumerator LV_OBJ_FLAG_CHECKABLE

Toggle checked state when the object is clicked

enumerator LV_OBJ_FLAG_SCROLLABLE

Make the object scrollable

enumerator LV_OBJ_FLAG_SCROLL_ELASTIC

Allow scrolling inside but with slower speed

enumerator LV_OBJ_FLAG_SCROLL_MOMENTUM

Make the object scroll further when "thrown"

enumerator LV_OBJ_FLAG_SCROLL_ONE

Allow scrolling only one snappable children

enumerator LV_OBJ_FLAG_SCROLL_CHAIN_HOR

Allow propagating the horizontal scroll to a parent

enumerator LV_OBJ_FLAG_SCROLL_CHAIN_VER

Allow propagating the vertical scroll to a parent

enumerator LV_OBJ_FLAG_SCROLL_CHAIN
enumerator LV_OBJ_FLAG_SCROLL_ON_FOCUS

Automatically scroll object to make it visible when focused

enumerator LV_OBJ_FLAG_SCROLL_WITH_ARROW

Allow scrolling the focused object with arrow keys

enumerator LV_OBJ_FLAG_SNAPPABLE

If scroll snap is enabled on the parent it can snap to this object

enumerator LV_OBJ_FLAG_PRESS_LOCK

Keep the object pressed even if the press slid from the object

enumerator LV_OBJ_FLAG_EVENT_BUBBLE

Propagate the events to the parent too

enumerator LV_OBJ_FLAG_GESTURE_BUBBLE

Propagate the gestures to the parent

enumerator LV_OBJ_FLAG_ADV_HITTEST

Allow performing more accurate hit (click) test. E.g. consider rounded corners.

enumerator LV_OBJ_FLAG_IGNORE_LAYOUT

Make the object position-able by the layouts

enumerator LV_OBJ_FLAG_FLOATING

Do not scroll the object when the parent scrolls and ignore layout

enumerator LV_OBJ_FLAG_SEND_DRAW_TASK_EVENTS

Send LV_EVENT_DRAW_TASK_ADDED events

enumerator LV_OBJ_FLAG_OVERFLOW_VISIBLE

Do not clip the children to the parent's ext draw size

enumerator LV_OBJ_FLAG_FLEX_IN_NEW_TRACK

Start a new flex track on this item

enumerator LV_OBJ_FLAG_LAYOUT_1

Custom flag, free to use by layouts

enumerator LV_OBJ_FLAG_LAYOUT_2

Custom flag, free to use by layouts

enumerator LV_OBJ_FLAG_WIDGET_1

Custom flag, free to use by widget

enumerator LV_OBJ_FLAG_WIDGET_2

Custom flag, free to use by widget

enumerator LV_OBJ_FLAG_USER_1

Custom flag, free to use by user

enumerator LV_OBJ_FLAG_USER_2

Custom flag, free to use by user

enumerator LV_OBJ_FLAG_USER_3

Custom flag, free to use by user

enumerator LV_OBJ_FLAG_USER_4

Custom flag, free to use by user

enum [anonymous]

Values:

enumerator LV_PROPERTY_OBJ_FLAG_START
enumerator LV_PROPERTY_OBJ_FLAG_HIDDEN
enumerator LV_PROPERTY_OBJ_FLAG_CLICKABLE
enumerator LV_PROPERTY_OBJ_FLAG_CLICK_FOCUSABLE
enumerator LV_PROPERTY_OBJ_FLAG_CHECKABLE
enumerator LV_PROPERTY_OBJ_FLAG_SCROLLABLE
enumerator LV_PROPERTY_OBJ_FLAG_SCROLL_ELASTIC
enumerator LV_PROPERTY_OBJ_FLAG_SCROLL_MOMENTUM
enumerator LV_PROPERTY_OBJ_FLAG_SCROLL_ONE
enumerator LV_PROPERTY_OBJ_FLAG_SCROLL_CHAIN_HOR
enumerator LV_PROPERTY_OBJ_FLAG_SCROLL_CHAIN_VER
enumerator LV_PROPERTY_OBJ_FLAG_SCROLL_ON_FOCUS
enumerator LV_PROPERTY_OBJ_FLAG_SCROLL_WITH_ARROW
enumerator LV_PROPERTY_OBJ_FLAG_SNAPPABLE
enumerator LV_PROPERTY_OBJ_FLAG_PRESS_LOCK
enumerator LV_PROPERTY_OBJ_FLAG_EVENT_BUBBLE
enumerator LV_PROPERTY_OBJ_FLAG_GESTURE_BUBBLE
enumerator LV_PROPERTY_OBJ_FLAG_ADV_HITTEST
enumerator LV_PROPERTY_OBJ_FLAG_IGNORE_LAYOUT
enumerator LV_PROPERTY_OBJ_FLAG_FLOATING
enumerator LV_PROPERTY_OBJ_FLAG_SEND_DRAW_TASK_EVENTS
enumerator LV_PROPERTY_OBJ_FLAG_OVERFLOW_VISIBLE
enumerator LV_PROPERTY_OBJ_FLAG_FLEX_IN_NEW_TRACK
enumerator LV_PROPERTY_OBJ_FLAG_LAYOUT_1
enumerator LV_PROPERTY_OBJ_FLAG_LAYOUT_2
enumerator LV_PROPERTY_OBJ_FLAG_WIDGET_1
enumerator LV_PROPERTY_OBJ_FLAG_WIDGET_2
enumerator LV_PROPERTY_OBJ_FLAG_USER_1
enumerator LV_PROPERTY_OBJ_FLAG_USER_2
enumerator LV_PROPERTY_OBJ_FLAG_USER_3
enumerator LV_PROPERTY_OBJ_FLAG_USER_4
enumerator LV_PROPERTY_OBJ_FLAG_END
enumerator LV_PROPERTY_OBJ_STATE_START
enumerator LV_PROPERTY_OBJ_STATE_CHECKED
enumerator LV_PROPERTY_OBJ_STATE_FOCUSED
enumerator LV_PROPERTY_OBJ_STATE_FOCUS_KEY
enumerator LV_PROPERTY_OBJ_STATE_EDITED
enumerator LV_PROPERTY_OBJ_STATE_HOVERED
enumerator LV_PROPERTY_OBJ_STATE_PRESSED
enumerator LV_PROPERTY_OBJ_STATE_SCROLLED
enumerator LV_PROPERTY_OBJ_STATE_DISABLED
enumerator LV_PROPERTY_OBJ_STATE_USER_1
enumerator LV_PROPERTY_OBJ_STATE_USER_2
enumerator LV_PROPERTY_OBJ_STATE_USER_3
enumerator LV_PROPERTY_OBJ_STATE_USER_4
enumerator LV_PROPERTY_OBJ_STATE_ANY
enumerator LV_PROPERTY_OBJ_STATE_END
enumerator LV_PROPERTY_OBJ_PARENT
enumerator LV_PROPERTY_OBJ_END

Functions

lv_obj_t *lv_obj_create(lv_obj_t *parent)

Create a base object (a rectangle)

Parameters:

parent -- pointer to a parent object. If NULL then a screen will be created.

Returns:

pointer to the new object

void lv_obj_add_flag(lv_obj_t *obj, lv_obj_flag_t f)

Set one or more flags

Parameters:
  • obj -- pointer to an object

  • f -- OR-ed values from lv_obj_flag_t to set.

void lv_obj_remove_flag(lv_obj_t *obj, lv_obj_flag_t f)

Remove one or more flags

Parameters:
  • obj -- pointer to an object

  • f -- OR-ed values from lv_obj_flag_t to clear.

void lv_obj_update_flag(lv_obj_t *obj, lv_obj_flag_t f, bool v)

Set add or remove one or more flags.

Parameters:
  • obj -- pointer to an object

  • f -- OR-ed values from lv_obj_flag_t to update.

  • v -- true: add the flags; false: remove the flags

void lv_obj_add_state(lv_obj_t *obj, lv_state_t state)

Add one or more states to the object. The other state bits will remain unchanged. If specified in the styles, transition animation will be started from the previous state to the current.

Parameters:
  • obj -- pointer to an object

  • state -- the states to add. E.g LV_STATE_PRESSED | LV_STATE_FOCUSED

void lv_obj_remove_state(lv_obj_t *obj, lv_state_t state)

Remove one or more states to the object. The other state bits will remain unchanged. If specified in the styles, transition animation will be started from the previous state to the current.

Parameters:
  • obj -- pointer to an object

  • state -- the states to add. E.g LV_STATE_PRESSED | LV_STATE_FOCUSED

void lv_obj_set_state(lv_obj_t *obj, lv_state_t state, bool v)

Add or remove one or more states to the object. The other state bits will remain unchanged.

Parameters:
  • obj -- pointer to an object

  • state -- the states to add. E.g LV_STATE_PRESSED | LV_STATE_FOCUSED

  • v -- true: add the states; false: remove the states

static inline void lv_obj_set_user_data(lv_obj_t *obj, void *user_data)

Set the user_data field of the object

Parameters:
  • obj -- pointer to an object

  • user_data -- pointer to the new user_data.

bool lv_obj_has_flag(const lv_obj_t *obj, lv_obj_flag_t f)

Check if a given flag or all the given flags are set on an object.

Parameters:
  • obj -- pointer to an object

  • f -- the flag(s) to check (OR-ed values can be used)

Returns:

true: all flags are set; false: not all flags are set

bool lv_obj_has_flag_any(const lv_obj_t *obj, lv_obj_flag_t f)

Check if a given flag or any of the flags are set on an object.

Parameters:
  • obj -- pointer to an object

  • f -- the flag(s) to check (OR-ed values can be used)

Returns:

true: at lest one flag flag is set; false: none of the flags are set

lv_state_t lv_obj_get_state(const lv_obj_t *obj)

Get the state of an object

Parameters:

obj -- pointer to an object

Returns:

the state (OR-ed values from lv_state_t)

bool lv_obj_has_state(const lv_obj_t *obj, lv_state_t state)

Check if the object is in a given state or not.

Parameters:
  • obj -- pointer to an object

  • state -- a state or combination of states to check

Returns:

true: obj is in state; false: obj is not in state

lv_group_t *lv_obj_get_group(const lv_obj_t *obj)

Get the group of the object

Parameters:

obj -- pointer to an object

Returns:

the pointer to group of the object

static inline void *lv_obj_get_user_data(lv_obj_t *obj)

Get the user_data field of the object

Parameters:

obj -- pointer to an object

Returns:

the pointer to the user_data of the object

void lv_obj_allocate_spec_attr(lv_obj_t *obj)

Allocate special data for an object if not allocated yet.

Parameters:

obj -- pointer to an object

bool lv_obj_check_type(const lv_obj_t *obj, const lv_obj_class_t *class_p)

Check the type of obj.

Parameters:
  • obj -- pointer to an object

  • class_p -- a class to check (e.g. lv_slider_class)

Returns:

true: class_p is the obj class.

bool lv_obj_has_class(const lv_obj_t *obj, const lv_obj_class_t *class_p)

Check if any object has a given class (type). It checks the ancestor classes too.

Parameters:
  • obj -- pointer to an object

  • class_p -- a class to check (e.g. lv_slider_class)

Returns:

true: obj has the given class

const lv_obj_class_t *lv_obj_get_class(const lv_obj_t *obj)

Get the class (type) of the object

Parameters:

obj -- pointer to an object

Returns:

the class (type) of the object

bool lv_obj_is_valid(const lv_obj_t *obj)

Check if any object is still "alive".

Parameters:

obj -- pointer to an object

Returns:

true: valid

void lv_obj_set_id(lv_obj_t *obj, void *id)

Set an id for an object.

Parameters:
  • obj -- pointer to an object

  • id -- the id of the object

void *lv_obj_get_id(const lv_obj_t *obj)

Get the id of an object.

Parameters:

obj -- pointer to an object

Returns:

the id of the object

lv_obj_t *lv_obj_get_child_by_id(const lv_obj_t *obj, void *id)

Get the child object by its id. It will check children and grandchildren recursively. Function lv_obj_id_compare is used to matched obj id with given id.

Parameters:
  • obj -- pointer to an object

  • id -- the id of the child object

Returns:

pointer to the child object or NULL if not found

void lv_obj_assign_id(const lv_obj_class_t *class_p, lv_obj_t *obj)

Assign id to object if not previously assigned. This function gets called automatically when LV_OBJ_ID_AUTO_ASSIGN is enabled.

Set LV_USE_OBJ_ID_BUILTIN to use the builtin method to generate object ID. Otherwise, these functions including lv_obj_[assign|free|stringify]_id and lv_obj_id_compareshould be implemented externally.

Parameters:
  • class_p -- the class this obj belongs to. Note obj->class_p is the class currently being constructed.

  • obj -- pointer to an object

void lv_obj_free_id(lv_obj_t *obj)

Free resources allocated by lv_obj_assign_id. This function gets called automatically when object is deleted.

Parameters:

obj -- pointer to an object

int lv_obj_id_compare(void *id1, void *id2)

Compare two obj id, return 0 if they are equal.

Set LV_USE_OBJ_ID_BUILTIN to use the builtin method for compare. Otherwise, it must be implemented externally.

Parameters:
  • id1 -- the first id

  • id2 -- the second id

Returns:

0 if they are equal, non-zero otherwise.

const char *lv_obj_stringify_id(lv_obj_t *obj, char *buf, uint32_t len)

Format an object's id into a string.

Parameters:
  • obj -- pointer to an object

  • buf -- buffer to write the string into

  • len -- length of the buffer

void lv_objid_builtin_destroy(void)

Free resources used by builtin ID generator.

Variables

const lv_obj_class_t lv_obj_class

Make the base object's class publicly available.

struct _lv_obj_spec_attr_t
#include <lv_obj.h>

Special, rarely used attributes. They are allocated automatically if any elements is set.

Public Members

lv_obj_t **children

Store the pointer of the children in an array.

lv_group_t *group_p
lv_event_list_t event_list
lv_point_t scroll

The current X/Y scroll offset

int32_t ext_click_pad

Extra click padding in all direction

int32_t ext_draw_size

EXTend the size in every direction for drawing.

uint16_t child_cnt

Number of children

uint16_t scrollbar_mode

How to display scrollbars, see lv_scrollbar_mode_t

uint16_t scroll_snap_x

Where to align the snappable children horizontally, see lv_scroll_snap_t

uint16_t scroll_snap_y

Where to align the snappable children vertically

uint16_t scroll_dir

The allowed scroll direction(s), see lv_dir_t

uint16_t layer_type

Cache the layer type here. Element of @lv_intermediate_layer_type_t

struct _lv_obj_t

Public Members

const lv_obj_class_t *class_p
lv_obj_t *parent
_lv_obj_spec_attr_t *spec_attr
_lv_obj_style_t *styles
void *user_data
void *id
lv_area_t coords
lv_obj_flag_t flags
lv_state_t state
uint16_t layout_inv
uint16_t readjust_scroll_after_layout
uint16_t scr_layout_inv
uint16_t skip_trans
uint16_t style_cnt
uint16_t h_layout
uint16_t w_layout
uint16_t is_deleting