Base object (lv_obj)

Overview

The 'Base Object' implements the basic properties of widgets on a screen, such as:

  • coordinates

  • parent object

  • children

  • main style

  • attributes like Click enable, Drag enable, etc.

In object-oriented thinking, it is the base class from which all other objects in LVGL are inherited. This, among another things, helps reduce code duplication.

The functions and functionalities of Base object can be used with other widgets too. For example lv_obj_set_width(slider, 100)

The Base object can be directly used as a simple widgets. It nothing else then a rectangle.

Coordinates

Size

The object size can be modified on individual axes with lv_obj_set_width(obj, new_width) and lv_obj_set_height(obj, new_height), or both axes can be modified at the same time with lv_obj_set_size(obj, new_width, new_height).

Styles can add Margin to the objects. Margin tells that "I want this space around me". To set width or height reduced by the margin lv_obj_set_width_margin(obj, new_width) or lv_obj_set_height_margin(obj, new_height). In more exact way: new_width = left_margin + object_width + right_margin.

To get the width or height which includes the margins use lv_obj_get_width/height_margin(obj).

Styles can add Padding to the object as well. Padding means "I don't want my children too close to my sides, so keep this space". To set width or height reduced by the padding lv_obj_set_width_fit(obj, new_width) or lv_obj_set_height_fit(obj, new_height).In a more exact way: new_width = left_pad + object_width + right_pad To get the width or height which is REDUCED by padding use lv_obj_get_width/height_fit(obj). It can be considered the "useful size of the object".

Margin and padding gets important when Layout or Auto-fit is used by other widgets.

Position

You can set the x and y coordinates relative to the parent with lv_obj_set_x(obj, new_x) and lv_obj_set_y(obj, new_y), or both at the same time with lv_obj_set_pos(obj, new_x, new_y).

Alignment

You can align the object to another with lv_obj_align(obj, obj_ref, LV_ALIGN_..., x_ofs, y_ofs).

  • obj is the object to align.

  • obj_ref is a reference object. obj will be aligned to it. If obj_ref = NULL, then the parent of obj will be used.

  • The third argument is the type of alignment. These are the possible options: Alignment types in LVGL

    The alignment types build like LV_ALIGN_OUT_TOP_MID.

  • The last two arguments allow you to shift the object by a specified number of pixels after aligning it.

For example, to align a text below an image: lv_obj_align(text, image, LV_ALIGN_OUT_BOTTOM_MID, 0, 10). Or to align a text in the middle of its parent: lv_obj_align(text, NULL, LV_ALIGN_CENTER, 0, 0).

lv_obj_align_origo works similarly to lv_obj_align but it aligns the center of the object.

For example, lv_obj_align_origo(btn, image, LV_ALIGN_OUT_BOTTOM_MID, 0, 0) will align the center of the button the bottom of the image.

The parameters of the alignment will be saved in the object if LV_USE_OBJ_REALIGN is enabled in lv_conf.h. You can then realign the objects simply by calling lv_obj_realign(obj). It's equivalent to calling lv_obj_align again with the same parameters.

If the alignment happened with lv_obj_align_origo, then it will be used when the object is realigned.

If lv_obj_set_auto_realign(obj, true) is used the object will be realigned automatically, if its size changes in lv_obj_set_width/height/size() functions. It's very useful when size animations are applied to the object and the original position needs to be kept.

Note that the coordinates of screens can't be changed. Attempting to use these functions on screens will result in undefined behavior.

Parents and children

You can set a new parent for an object with lv_obj_set_parent(obj, new_parent). To get the current parent, use lv_obj_get_parent(obj).

To get the children of an object, use lv_obj_get_child(obj, child_prev) (from last to first) or lv_obj_get_child_back(obj, child_prev) (from first to last). To get the first child, pass NULL as the second parameter and use the return value to iterate through the children. The function will return NULL if there are no more children. For example:

lv_obj_t * child = lv_obj_get_child(parent, NULL);
while(child) {
    /*Do something with "child" */
    child = lv_obj_get_child(parent, child);
}

lv_obj_count_children(obj) tells the number of children on an object. lv_obj_count_children_recursive(obj) also tells the number of children but counts children of children recursively.

Screens

When you have created a screen like lv_obj_t * screen = lv_obj_create(NULL, NULL), you can load it with lv_scr_load(screen). The lv_scr_act() function gives you a pointer to the current screen.

If you have more display then it's important to know that these functions operate on the lastly created or the explicitly selected (with lv_disp_set_default) display.

To get an object's screen use the lv_obj_get_screen(obj) function.

Layers

There are two automatically generated layers:

  • top layer

  • system layer

They are independent of the screens and they will be shown on every screen. The top layer is above every object on the screen and the system layer is above the top layer too. You can add any pop-up windows to the top layer freely. But, the system layer is restricted to system-level things (e.g. mouse cursor will be placed here in lv_indev_set_cursor()).

The lv_layer_top() and lv_layer_sys() functions gives a pointer to the top or system layer.

You can bring an object to the foreground or send it to the background with lv_obj_move_foreground(obj) and lv_obj_move_background(obj).

Read the Layer overview section to learn more about layers.

Events

To set an event callback for an object, use lv_obj_set_event_cb(obj, event_cb),

To manually send an event to an object, use lv_event_send(obj, LV_EVENT_..., data)

Read the Event overview to learn more about the events.

Parts

The widgets can have multiple parts. For example a Button has only a main part but a Slider is built from a background, an indicator and a knob.

The name of the parts is constructed like LV_ + <TYPE> _PART_ <NAME>. For example LV_BTN_PART_MAIN or LV_SLIDER_PART_KNOB. The parts are usually used when styles are add to the objects. Using parts different styles can be assigned to the different parts of the objects.

To learn more about the parts read the related section of the Style overview.

States

The object can be in a combinations of the following states:

  • LV_STATE_DEFAULT Normal, released

  • LV_STATE_CHECKED Toggled or checked

  • LV_STATE_FOCUSED Focused via keypad or encoder or clicked via touchpad/mouse

  • LV_STATE_EDITED  Edit by an encoder

  • LV_STATE_HOVERED Hovered by mouse (not supported now)

  • LV_STATE_PRESSED Pressed

  • LV_STATE_DISABLED Disabled or inactive

The states are usually automatically changed by the library as the user presses, releases, focuses etc an object. However, the states can be changed manually too. To completely overwrite the current state use lv_obj_set_state(obj, part, LV_STATE...). To set or clear given state (but leave to other states untouched) use lv_obj_add/clear_state(obj, part, LV_STATE_...) In both cases ORed state values can be used as well. E.g. lv_obj_set_state(obj, part, LV_STATE_PRESSED | LV_PRESSED_CHECKED).

To learn more about the states read the related section of the Style overview.

Style

Be sure to read the Style overview first.

To add a style to an object use lv_obj_add_style(obj, part, &new_style) function. The Base object use all the rectangle-like style properties.

To remove all styles from an object use lv_obj_reset_style_list(obj, part)

If you modify a style, which is already used by objects, in order to refresh the affected objects you can use either lv_obj_refresh_style(obj) on each object using it or to notify all objects with a given style use lv_obj_report_style_mod(&style). If the parameter of lv_obj_report_style_mod is NULL, all objects will be notified.

Attributes

There are some attributes which can be enabled/disabled by lv_obj_set_...(obj, true/false):

  • hidden - Hide the object. It will not be drawn and will be considered by input devices as if it doesn't exist., Its children will be hidden too.

  • click - Allows you to click the object via input devices. If disabled, then click events are passed to the object behind this one. (E.g. Labels are not clickable by default)

  • top - If enabled then when this object or any of its children is clicked then this object comes to the foreground.

  • drag - Enable dragging (moving by an input device)

  • drag_dir - Enable dragging only in specific directions. Can be LV_DRAG_DIR_HOR/VER/ALL.

  • drag_throw - Enable "throwing" with dragging as if the object would have momentum

  • drag_parent - If enabled then the object's parent will be moved during dragging. It will look like as if the parent is dragged. Checked recursively, so can propagate to grandparents too.

  • parent_event - Propagate the events to the parents too. Checked recursively, so can propagate to grandparents too.

  • opa_scale_enable - Enable opacity scaling. See the [#opa-scale](Opa scale) section.

Protect

There are some specific actions which happen automatically in the library. To prevent one or more that kind of actions, you can protect the object against them. The following protections exists:

  • LV_PROTECT_NONE No protection

  • LV_PROTECT_POS Prevent automatic positioning (e.g. Layout in Containers)

  • LV_PROTECT_FOLLOW Prevent the object be followed (make a "line break") in automatic ordering (e.g. Layout in Containers)

  • LV_PROTECT_PARENT Prevent automatic parent change. (e.g. Page moves the children created on the background to the scrollable)

  • LV_PROTECT_PRESS_LOST Prevent losing press when the press is slid out of the objects. (E.g. a Button can be released out of it if it was being pressed)

  • LV_PROTECT_CLICK_FOCUS Prevent automatically focusing the object if it's in a Group and click focus is enabled.

  • LV_PROTECT_CHILD_CHG Disable the child change signal. Used internally by the library

The lv_obj_set/clear_protect(obj, LV_PROTECT_...) sets/clears the protection. You can use 'OR'ed values of protection types too.

Groups

Once, an object is added to group with lv_group_add_obj(group, obj) the object's current group can be get with lv_obj_get_group(obj).

lv_obj_is_focused(obj) tells if the object is currently focused on its group or not. If the object is not added to a group, false will be returned.

Read the Input devices overview to learn more about the Groups.

Extended click area

By default, the objects can be clicked only on their coordinates, however, this area can be extended with lv_obj_set_ext_click_area(obj, left, right, top, bottom). left/right/top/bottom describes how far the clickable area should extend past the default in each direction.

This feature needs to enabled in lv_conf.h with LV_USE_EXT_CLICK_AREA. The possible values are:

  • LV_EXT_CLICK_AREA_FULL store all 4 coordinates as lv_coord_t

  • LV_EXT_CLICK_AREA_TINY store only horizontal and vertical coordinates (use the greater value of left/right and top/bottom) as uint8_t

  • LV_EXT_CLICK_AREA_OFF Disable this feature

Events

Only the Generic events are sent by the object type.

Learn more about Events.

Keys

No Keys are processed by the object type.

Learn more about Keys.

Example

C

Base obejcts with custom styles

Simeple Base object example in LittlevGL

code

#include "../../../lv_examples.h"

void lv_ex_obj_1(void)
{
    lv_obj_t * obj1;
    obj1 = lv_obj_create(lv_scr_act(), NULL);
    lv_obj_set_size(obj1, 100, 50);
    lv_obj_align(obj1, NULL, LV_ALIGN_CENTER, -60, -30);

    /*Copy the previous object and enable drag*/
    lv_obj_t * obj2;
    obj2 = lv_obj_create(lv_scr_act(), obj1);
    lv_obj_align(obj2, NULL, LV_ALIGN_CENTER, 0, 0);
    lv_obj_set_drag(obj2, true);

    static lv_style_t style_shadow;
    lv_style_init(&style_shadow);
    lv_style_set_shadow_width(&style_shadow, LV_STATE_DEFAULT, 10);
    lv_style_set_shadow_spread(&style_shadow, LV_STATE_DEFAULT, 5);
    lv_style_set_shadow_color(&style_shadow, LV_STATE_DEFAULT, LV_COLOR_BLUE);

    /*Copy the previous object (drag is already enabled)*/
    lv_obj_t * obj3;
    obj3 = lv_obj_create(lv_scr_act(), obj2);
    lv_obj_add_style(obj3, LV_OBJ_PART_MAIN, &style_shadow);
    lv_obj_align(obj3, NULL, LV_ALIGN_CENTER, 60, 30);
}

MicroPython

No examples yet.

API

Typedefs

typedef uint8_t lv_design_mode_t
typedef uint8_t lv_design_res_t
typedef lv_design_res_t (*lv_design_cb_t)(struct _lv_obj_t *obj, const lv_area_t *clip_area, lv_design_mode_t mode)

The design callback is used to draw the object on the screen. It accepts the object, a mask area, and the mode in which to draw the object.

typedef uint8_t lv_event_t

Type of event being sent to the object.

typedef void (*lv_event_cb_t)(struct _lv_obj_t *obj, lv_event_t event)

Event callback. Events are used to notify the user of some action being taken on the object. For details, see lv_event_t.

typedef uint8_t lv_signal_t
typedef lv_res_t (*lv_signal_cb_t)(struct _lv_obj_t *obj, lv_signal_t sign, void *param)
typedef uint8_t lv_protect_t
typedef uint8_t lv_state_t
typedef struct _lv_obj_t lv_obj_t
typedef uint8_t lv_obj_part_t

Enums

enum [anonymous]

Design modes

Values:

enumerator LV_DESIGN_DRAW_MAIN

Draw the main portion of the object

enumerator LV_DESIGN_DRAW_POST

Draw extras on the object

enumerator LV_DESIGN_COVER_CHK

Check if the object fully covers the 'mask_p' area

enum [anonymous]

Design results

Values:

enumerator LV_DESIGN_RES_OK

Draw ready

enumerator LV_DESIGN_RES_COVER

Returned on LV_DESIGN_COVER_CHK if the areas is fully covered

enumerator LV_DESIGN_RES_NOT_COVER

Returned on LV_DESIGN_COVER_CHK if the areas is not covered

enumerator LV_DESIGN_RES_MASKED

Returned on LV_DESIGN_COVER_CHK if the areas is masked out (children also not cover)

enum [anonymous]

Values:

enumerator LV_EVENT_PRESSED

The object has been pressed

enumerator LV_EVENT_PRESSING

The object is being pressed (called continuously while pressing)

enumerator LV_EVENT_PRESS_LOST

User is still pressing but slid cursor/finger off of the object

enumerator LV_EVENT_SHORT_CLICKED

User pressed object for a short period of time, then released it. Not called if dragged.

enumerator LV_EVENT_LONG_PRESSED

Object has been pressed for at least LV_INDEV_LONG_PRESS_TIME. Not called if dragged.

enumerator LV_EVENT_LONG_PRESSED_REPEAT

Called after LV_INDEV_LONG_PRESS_TIME in every LV_INDEV_LONG_PRESS_REP_TIME ms. Not called if dragged.

enumerator LV_EVENT_CLICKED

Called on release if not dragged (regardless to long press)

enumerator LV_EVENT_RELEASED

Called in every cases when the object has been released

enumerator LV_EVENT_DRAG_BEGIN
enumerator LV_EVENT_DRAG_END
enumerator LV_EVENT_DRAG_THROW_BEGIN
enumerator LV_EVENT_GESTURE

The object has been gesture

enumerator LV_EVENT_KEY
enumerator LV_EVENT_FOCUSED
enumerator LV_EVENT_DEFOCUSED
enumerator LV_EVENT_LEAVE
enumerator LV_EVENT_VALUE_CHANGED

The object's value has changed (i.e. slider moved)

enumerator LV_EVENT_INSERT
enumerator LV_EVENT_REFRESH
enumerator LV_EVENT_APPLY

"Ok", "Apply" or similar specific button has clicked

enumerator LV_EVENT_CANCEL

"Close", "Cancel" or similar specific button has clicked

enumerator LV_EVENT_DELETE

Object is being deleted

enum [anonymous]

Signals are for use by the object itself or to extend the object's functionality. Applications should use lv_obj_set_event_cb to be notified of events that occur on the object.

Values:

enumerator LV_SIGNAL_CLEANUP

Object is being deleted

enumerator LV_SIGNAL_CHILD_CHG

Child was removed/added

enumerator LV_SIGNAL_COORD_CHG

Object coordinates/size have changed

enumerator LV_SIGNAL_PARENT_SIZE_CHG

Parent's size has changed

enumerator LV_SIGNAL_STYLE_CHG

Object's style has changed

enumerator LV_SIGNAL_BASE_DIR_CHG

The base dir has changed

enumerator LV_SIGNAL_REFR_EXT_DRAW_PAD

Object's extra padding has changed

enumerator LV_SIGNAL_GET_TYPE

LVGL needs to retrieve the object's type

enumerator LV_SIGNAL_GET_STYLE

Get the style of an object

enumerator LV_SIGNAL_GET_STATE_DSC

Get the state of the object

enumerator LV_SIGNAL_HIT_TEST

Advanced hit-testing

enumerator LV_SIGNAL_PRESSED

The object has been pressed

enumerator LV_SIGNAL_PRESSING

The object is being pressed (called continuously while pressing)

enumerator LV_SIGNAL_PRESS_LOST

User is still pressing but slid cursor/finger off of the object

enumerator LV_SIGNAL_RELEASED

User pressed object for a short period of time, then released it. Not called if dragged.

enumerator LV_SIGNAL_LONG_PRESS

Object has been pressed for at least LV_INDEV_LONG_PRESS_TIME. Not called if dragged.

enumerator LV_SIGNAL_LONG_PRESS_REP

Called after LV_INDEV_LONG_PRESS_TIME in every LV_INDEV_LONG_PRESS_REP_TIME ms. Not called if dragged.

enumerator LV_SIGNAL_DRAG_BEGIN
enumerator LV_SIGNAL_DRAG_THROW_BEGIN
enumerator LV_SIGNAL_DRAG_END
enumerator LV_SIGNAL_GESTURE

The object has been gesture

enumerator LV_SIGNAL_LEAVE

Another object is clicked or chosen via an input device

enumerator LV_SIGNAL_FOCUS
enumerator LV_SIGNAL_DEFOCUS
enumerator LV_SIGNAL_CONTROL
enumerator LV_SIGNAL_GET_EDITABLE
enum [anonymous]

Values:

enumerator LV_PROTECT_NONE = 0x00
enumerator LV_PROTECT_CHILD_CHG = 0x01

Disable the child change signal. Used by the library

enumerator LV_PROTECT_PARENT = 0x02

Prevent automatic parent change (e.g. in lv_page)

enumerator LV_PROTECT_POS = 0x04

Prevent automatic positioning (e.g. in lv_cont layout)

enumerator LV_PROTECT_FOLLOW = 0x08

Prevent the object be followed in automatic ordering (e.g. in lv_cont PRETTY layout)

enumerator LV_PROTECT_PRESS_LOST = 0x10

If the indev was pressing this object but swiped out while pressing do not search other object.

enumerator LV_PROTECT_CLICK_FOCUS = 0x20

Prevent focusing the object by clicking on it

enum [anonymous]

Values:

enumerator LV_STATE_DEFAULT = 0x00
enumerator LV_STATE_CHECKED = 0x01
enumerator LV_STATE_FOCUSED = 0x02
enumerator LV_STATE_EDITED = 0x04
enumerator LV_STATE_HOVERED = 0x08
enumerator LV_STATE_PRESSED = 0x10
enumerator LV_STATE_DISABLED = 0x20
enum [anonymous]

Values:

enumerator LV_OBJ_PART_MAIN
enumerator _LV_OBJ_PART_VIRTUAL_LAST = 0x01
enumerator _LV_OBJ_PART_REAL_LAST = 0x40
enumerator LV_OBJ_PART_ALL = 0xFF

Functions

void lv_init(void)

Init. the 'lv' library.

void lv_deinit(void)

Deinit the 'lv' library Currently only implemented when not using custom allocators, or GC is enabled.

lv_obj_t *lv_obj_create(lv_obj_t *parent, const lv_obj_t *copy)

Create a basic object

Return

pointer to the new object

Parameters
  • parent: pointer to a parent object. If NULL then a screen will be created

  • copy: pointer to a base object, if not NULL then the new object will be copied from it

lv_res_t lv_obj_del(lv_obj_t *obj)

Delete 'obj' and all of its children

Return

LV_RES_INV because the object is deleted

Parameters
  • obj: pointer to an object to delete

void lv_obj_del_anim_ready_cb(lv_anim_t *a)

A function to be easily used in animation ready callback to delete an object when the animation is ready

Parameters
  • a: pointer to the animation

void lv_obj_del_async(struct _lv_obj_t *obj)

Helper function for asynchronously deleting objects. Useful for cases where you can't delete an object directly in an LV_EVENT_DELETE handler (i.e. parent).

See

lv_async_call

Parameters
  • obj: object to delete

void lv_obj_clean(lv_obj_t *obj)

Delete all children of an object

Parameters
  • obj: pointer to an object

void lv_obj_invalidate_area(const lv_obj_t *obj, const lv_area_t *area)

Mark an area of an object as invalid. This area will be redrawn by 'lv_refr_task'

Parameters
  • obj: pointer to an object

  • area: the area to redraw

void lv_obj_invalidate(const lv_obj_t *obj)

Mark the object as invalid therefore its current position will be redrawn by 'lv_refr_task'

Parameters
  • obj: pointer to an object

void lv_obj_set_parent(lv_obj_t *obj, lv_obj_t *parent)

Set a new parent for an object. Its relative position will be the same.

Parameters
  • obj: pointer to an object. Can't be a screen.

  • parent: pointer to the new parent object. (Can't be NULL)

void lv_obj_move_foreground(lv_obj_t *obj)

Move and object to the foreground

Parameters
  • obj: pointer to an object

void lv_obj_move_background(lv_obj_t *obj)

Move and object to the background

Parameters
  • obj: pointer to an object

void lv_obj_set_pos(lv_obj_t *obj, lv_coord_t x, lv_coord_t y)

Set relative the position of an object (relative to the parent)

Parameters
  • obj: pointer to an object

  • x: new distance from the left side of the parent

  • y: new distance from the top of the parent

void lv_obj_set_x(lv_obj_t *obj, lv_coord_t x)

Set the x coordinate of a object

Parameters
  • obj: pointer to an object

  • x: new distance from the left side from the parent

void lv_obj_set_y(lv_obj_t *obj, lv_coord_t y)

Set the y coordinate of a object

Parameters
  • obj: pointer to an object

  • y: new distance from the top of the parent

void lv_obj_set_size(lv_obj_t *obj, lv_coord_t w, lv_coord_t h)

Set the size of an object

Parameters
  • obj: pointer to an object

  • w: new width

  • h: new height

void lv_obj_set_width(lv_obj_t *obj, lv_coord_t w)

Set the width of an object

Parameters
  • obj: pointer to an object

  • w: new width

void lv_obj_set_height(lv_obj_t *obj, lv_coord_t h)

Set the height of an object

Parameters
  • obj: pointer to an object

  • h: new height

void lv_obj_set_width_fit(lv_obj_t *obj, lv_coord_t w)

Set the width reduced by the left and right padding.

Parameters
  • obj: pointer to an object

  • w: the width without paddings

void lv_obj_set_height_fit(lv_obj_t *obj, lv_coord_t h)

Set the height reduced by the top and bottom padding.

Parameters
  • obj: pointer to an object

  • h: the height without paddings

void lv_obj_set_width_margin(lv_obj_t *obj, lv_coord_t w)

Set the width of an object by taking the left and right margin into account. The object width will be obj_w = w - margin_left - margin_right

Parameters
  • obj: pointer to an object

  • w: new height including margins

void lv_obj_set_height_margin(lv_obj_t *obj, lv_coord_t h)

Set the height of an object by taking the top and bottom margin into account. The object height will be obj_h = h - margin_top - margin_bottom

Parameters
  • obj: pointer to an object

  • h: new height including margins

void lv_obj_align(lv_obj_t *obj, const lv_obj_t *base, lv_align_t align, lv_coord_t x_ofs, lv_coord_t y_ofs)

Align an object to an other object.

Parameters
  • obj: pointer to an object to align

  • base: pointer to an object (if NULL the parent is used). 'obj' will be aligned to it.

  • align: type of alignment (see 'lv_align_t' enum)

  • x_ofs: x coordinate offset after alignment

  • y_ofs: y coordinate offset after alignment

void lv_obj_align_origo(lv_obj_t *obj, const lv_obj_t *base, lv_align_t align, lv_coord_t x_ofs, lv_coord_t y_ofs)

Align an object to an other object.

Parameters
  • obj: pointer to an object to align

  • base: pointer to an object (if NULL the parent is used). 'obj' will be aligned to it.

  • align: type of alignment (see 'lv_align_t' enum)

  • x_ofs: x coordinate offset after alignment

  • y_ofs: y coordinate offset after alignment

void lv_obj_realign(lv_obj_t *obj)

Realign the object based on the last lv_obj_align parameters.

Parameters
  • obj: pointer to an object

void lv_obj_set_auto_realign(lv_obj_t *obj, bool en)

Enable the automatic realign of the object when its size has changed based on the last lv_obj_align parameters.

Parameters
  • obj: pointer to an object

  • en: true: enable auto realign; false: disable auto realign

void lv_obj_set_ext_click_area(lv_obj_t *obj, lv_coord_t left, lv_coord_t right, lv_coord_t top, lv_coord_t bottom)

Set the size of an extended clickable area

Parameters
  • obj: pointer to an object

  • left: extended clickable are on the left [px]

  • right: extended clickable are on the right [px]

  • top: extended clickable are on the top [px]

  • bottom: extended clickable are on the bottom [px]

void lv_obj_add_style(lv_obj_t *obj, uint8_t part, lv_style_t *style)

Add a new style to the style list of an object.

Parameters
  • obj: pointer to an object

  • part: the part of the object which style property should be set. E.g. LV_OBJ_PART_MAIN, LV_BTN_PART_MAIN, LV_SLIDER_PART_KNOB

  • style: pointer to a style to add (Only its pointer will be saved)

void lv_obj_remove_style(lv_obj_t *obj, uint8_t part, lv_style_t *style)

Remove a style from the style list of an object.

Parameters
  • obj: pointer to an object

  • part: the part of the object which style property should be set. E.g. LV_OBJ_PART_MAIN, LV_BTN_PART_MAIN, LV_SLIDER_PART_KNOB

  • style: pointer to a style to remove

void lv_obj_clean_style_list(lv_obj_t *obj, uint8_t part)

Reset a style to the default (empty) state. Release all used memories and cancel pending related transitions. Typically used in `LV_SIGN_CLEAN_UP.

Parameters
  • obj: pointer to an object

  • part: the part of the object which style list should be reseted. E.g. LV_OBJ_PART_MAIN, LV_BTN_PART_MAIN, LV_SLIDER_PART_KNOB

void lv_obj_reset_style_list(lv_obj_t *obj, uint8_t part)

Reset a style to the default (empty) state. Release all used memories and cancel pending related transitions. Also notifies the object about the style change.

Parameters
  • obj: pointer to an object

  • part: the part of the object which style list should be reseted. E.g. LV_OBJ_PART_MAIN, LV_BTN_PART_MAIN, LV_SLIDER_PART_KNOB

void lv_obj_refresh_style(lv_obj_t *obj, lv_style_property_t prop)

Notify an object (and its children) about its style is modified

Parameters
  • obj: pointer to an object

  • prop: LV_STYLE_PROP_ALL or an LV_STYLE_... property. It is used to optimize what needs to be refreshed.

void lv_obj_report_style_mod(lv_style_t *style)

Notify all object if a style is modified

Parameters
  • style: pointer to a style. Only the objects with this style will be notified (NULL to notify all objects)

void _lv_obj_set_style_local_color(lv_obj_t *obj, uint8_t type, lv_style_property_t prop, lv_color_t color)

Set a local style property of a part of an object in a given state.

Note

shouldn't be used directly. Use the specific property get functions instead. For example: lv_obj_style_get_border_opa()

Note

for performance reasons it's not checked if the property really has color type

Parameters
  • obj: pointer to an object

  • part: the part of the object which style property should be set. E.g. LV_OBJ_PART_MAIN, LV_BTN_PART_MAIN, LV_SLIDER_PART_KNOB

  • prop: a style property ORed with a state. E.g. LV_STYLE_BORDER_COLOR | (LV_STATE_PRESSED << LV_STYLE_STATE_POS)

  • the: value to set

void _lv_obj_set_style_local_int(lv_obj_t *obj, uint8_t type, lv_style_property_t prop, lv_style_int_t value)

Set a local style property of a part of an object in a given state.

Note

shouldn't be used directly. Use the specific property get functions instead. For example: lv_obj_style_get_border_opa()

Note

for performance reasons it's not checked if the property really has integer type

Parameters
  • obj: pointer to an object

  • part: the part of the object which style property should be set. E.g. LV_OBJ_PART_MAIN, LV_BTN_PART_MAIN, LV_SLIDER_PART_KNOB

  • prop: a style property ORed with a state. E.g. LV_STYLE_BORDER_WIDTH | (LV_STATE_PRESSED << LV_STYLE_STATE_POS)

  • the: value to set

void _lv_obj_set_style_local_opa(lv_obj_t *obj, uint8_t type, lv_style_property_t prop, lv_opa_t opa)

Set a local style property of a part of an object in a given state.

Note

shouldn't be used directly. Use the specific property get functions instead. For example: lv_obj_style_get_border_opa()

Note

for performance reasons it's not checked if the property really has opacity type

Parameters
  • obj: pointer to an object

  • part: the part of the object which style property should be set. E.g. LV_OBJ_PART_MAIN, LV_BTN_PART_MAIN, LV_SLIDER_PART_KNOB

  • prop: a style property ORed with a state. E.g. LV_STYLE_BORDER_OPA | (LV_STATE_PRESSED << LV_STYLE_STATE_POS)

  • the: value to set

void _lv_obj_set_style_local_ptr(lv_obj_t *obj, uint8_t type, lv_style_property_t prop, const void *value)

Set a local style property of a part of an object in a given state.

Note

shouldn't be used directly. Use the specific property get functions instead. For example: lv_obj_style_get_border_opa()

Note

for performance reasons it's not checked if the property really has pointer type

Parameters
  • obj: pointer to an object

  • part: the part of the object which style property should be set. E.g. LV_OBJ_PART_MAIN, LV_BTN_PART_MAIN, LV_SLIDER_PART_KNOB

  • prop: a style property ORed with a state. E.g. LV_STYLE_TEXT_FONT | (LV_STATE_PRESSED << LV_STYLE_STATE_POS)

  • the: value to set

bool lv_obj_remove_style_local_prop(lv_obj_t *obj, uint8_t part, lv_style_property_t prop)

Remove a local style property from a part of an object with a given state.

Note

shouldn't be used directly. Use the specific property remove functions instead. For example: lv_obj_style_remove_border_opa()

Return

true: the property was found and removed; false: the property was not found

Parameters
  • obj: pointer to an object

  • part: the part of the object which style property should be removed. E.g. LV_OBJ_PART_MAIN, LV_BTN_PART_MAIN, LV_SLIDER_PART_KNOB

  • prop: a style property ORed with a state. E.g. LV_STYLE_TEXT_FONT | (LV_STATE_PRESSED << LV_STYLE_STATE_POS)

void lv_obj_set_hidden(lv_obj_t *obj, bool en)

Hide an object. It won't be visible and clickable.

Parameters
  • obj: pointer to an object

  • en: true: hide the object

void lv_obj_set_adv_hittest(lv_obj_t *obj, bool en)

Set whether advanced hit-testing is enabled on an object

Parameters
  • obj: pointer to an object

  • en: true: advanced hit-testing is enabled

void lv_obj_set_click(lv_obj_t *obj, bool en)

Enable or disable the clicking of an object

Parameters
  • obj: pointer to an object

  • en: true: make the object clickable

void lv_obj_set_top(lv_obj_t *obj, bool en)

Enable to bring this object to the foreground if it or any of its children is clicked

Parameters
  • obj: pointer to an object

  • en: true: enable the auto top feature

void lv_obj_set_drag(lv_obj_t *obj, bool en)

Enable the dragging of an object

Parameters
  • obj: pointer to an object

  • en: true: make the object draggable

void lv_obj_set_drag_dir(lv_obj_t *obj, lv_drag_dir_t drag_dir)

Set the directions an object can be dragged in

Parameters
  • obj: pointer to an object

  • drag_dir: bitwise OR of allowed drag directions

void lv_obj_set_drag_throw(lv_obj_t *obj, bool en)

Enable the throwing of an object after is is dragged

Parameters
  • obj: pointer to an object

  • en: true: enable the drag throw

void lv_obj_set_drag_parent(lv_obj_t *obj, bool en)

Enable to use parent for drag related operations. If trying to drag the object the parent will be moved instead

Parameters
  • obj: pointer to an object

  • en: true: enable the 'drag parent' for the object

void lv_obj_set_focus_parent(lv_obj_t *obj, bool en)

Enable to use parent for focus state. When object is focused the parent will get the state instead (visual only)

Parameters
  • obj: pointer to an object

  • en: true: enable the 'focus parent' for the object

void lv_obj_set_gesture_parent(lv_obj_t *obj, bool en)

Enable to use parent for gesture related operations. If trying to gesture the object the parent will be moved instead

Parameters
  • obj: pointer to an object

  • en: true: enable the 'gesture parent' for the object

void lv_obj_set_parent_event(lv_obj_t *obj, bool en)

Propagate the events to the parent too

Parameters
  • obj: pointer to an object

  • en: true: enable the event propagation

void lv_obj_set_base_dir(lv_obj_t *obj, lv_bidi_dir_t dir)

Set the base direction of the object

Parameters
  • obj: pointer to an object

  • dir: the new base direction. LV_BIDI_DIR_LTR/RTL/AUTO/INHERIT

void lv_obj_add_protect(lv_obj_t *obj, uint8_t prot)

Set a bit or bits in the protect filed

Parameters
  • obj: pointer to an object

  • prot: 'OR'-ed values from lv_protect_t

void lv_obj_clear_protect(lv_obj_t *obj, uint8_t prot)

Clear a bit or bits in the protect filed

Parameters
  • obj: pointer to an object

  • prot: 'OR'-ed values from lv_protect_t

void lv_obj_set_state(lv_obj_t *obj, lv_state_t state)

Set the state (fully overwrite) of an object. If specified in the styles a transition animation will be started from the previous state to the current

Parameters
  • obj: pointer to an object

  • state: the new state

void lv_obj_add_state(lv_obj_t *obj, lv_state_t state)

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

Parameters
  • obj: pointer to an object

  • state: the state bits to add. E.g LV_STATE_PRESSED | LV_STATE_FOCUSED

void lv_obj_clear_state(lv_obj_t *obj, lv_state_t state)

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

Parameters
  • obj: pointer to an object

  • state: the state bits to remove. E.g LV_STATE_PRESSED | LV_STATE_FOCUSED

void lv_obj_finish_transitions(lv_obj_t *obj, uint8_t part)

Finish all pending transitions on a part of an object

Parameters
  • obj: pointer to an object

  • part: part of the object, e.g LV_BRN_PART_MAIN or LV_OBJ_PART_ALL for all parts

void lv_obj_set_event_cb(lv_obj_t *obj, lv_event_cb_t event_cb)

Set a an event handler function for an object. Used by the user to react on event which happens with the object.

Parameters
  • obj: pointer to an object

  • event_cb: the new event function

lv_res_t lv_event_send(lv_obj_t *obj, lv_event_t event, const void *data)

Send an event to the object

Return

LV_RES_OK: obj was not deleted in the event; LV_RES_INV: obj was deleted in the event

Parameters
  • obj: pointer to an object

  • event: the type of the event from lv_event_t.

  • data: arbitrary data depending on the object type and the event. (Usually NULL)

lv_res_t lv_event_send_func(lv_event_cb_t event_xcb, lv_obj_t *obj, lv_event_t event, const void *data)

Call an event function with an object, event, and data.

Return

LV_RES_OK: obj was not deleted in the event; LV_RES_INV: obj was deleted in the event

Parameters
  • event_xcb: an event callback function. If NULL LV_RES_OK will return without any actions. (the 'x' in the argument name indicates that its not a fully generic function because it not follows the func_name(object, callback, ...) convention)

  • obj: pointer to an object to associate with the event (can be NULL to simply call the event_cb)

  • event: an event

  • data: pointer to a custom data

const void *lv_event_get_data(void)

Get the data parameter of the current event

Return

the data parameter

void lv_obj_set_signal_cb(lv_obj_t *obj, lv_signal_cb_t signal_cb)

Set the a signal function of an object. Used internally by the library. Always call the previous signal function in the new.

Parameters
  • obj: pointer to an object

  • signal_cb: the new signal function

lv_res_t lv_signal_send(lv_obj_t *obj, lv_signal_t signal, void *param)

Send an event to the object

Return

LV_RES_OK or LV_RES_INV

Parameters
  • obj: pointer to an object

  • event: the type of the event from lv_event_t.

void lv_obj_set_design_cb(lv_obj_t *obj, lv_design_cb_t design_cb)

Set a new design function for an object

Parameters
  • obj: pointer to an object

  • design_cb: the new design function

void *lv_obj_allocate_ext_attr(lv_obj_t *obj, uint16_t ext_size)

Allocate a new ext. data for an object

Return

pointer to the allocated ext

Parameters
  • obj: pointer to an object

  • ext_size: the size of the new ext. data

void lv_obj_refresh_ext_draw_pad(lv_obj_t *obj)

Send a 'LV_SIGNAL_REFR_EXT_SIZE' signal to the object to refresh the extended draw area. he object needs to be invalidated by lv_obj_invalidate(obj) manually after this function.

Parameters
  • obj: pointer to an object

lv_obj_t *lv_obj_get_screen(const lv_obj_t *obj)

Return with the screen of an object

Return

pointer to a screen

Parameters
  • obj: pointer to an object

lv_disp_t *lv_obj_get_disp(const lv_obj_t *obj)

Get the display of an object

Return

pointer the object's display

lv_obj_t *lv_obj_get_parent(const lv_obj_t *obj)

Returns with the parent of an object

Return

pointer to the parent of 'obj'

Parameters
  • obj: pointer to an object

lv_obj_t *lv_obj_get_child(const lv_obj_t *obj, const lv_obj_t *child)

Iterate through the children of an object (start from the "youngest, lastly created")

Return

the child after 'act_child' or NULL if no more child

Parameters
  • obj: pointer to an object

  • child: NULL at first call to get the next children and the previous return value later

lv_obj_t *lv_obj_get_child_back(const lv_obj_t *obj, const lv_obj_t *child)

Iterate through the children of an object (start from the "oldest", firstly created)

Return

the child after 'act_child' or NULL if no more child

Parameters
  • obj: pointer to an object

  • child: NULL at first call to get the next children and the previous return value later

uint16_t lv_obj_count_children(const lv_obj_t *obj)

Count the children of an object (only children directly on 'obj')

Return

children number of 'obj'

Parameters
  • obj: pointer to an object

uint16_t lv_obj_count_children_recursive(const lv_obj_t *obj)

Recursively count the children of an object

Return

children number of 'obj'

Parameters
  • obj: pointer to an object

void lv_obj_get_coords(const lv_obj_t *obj, lv_area_t *cords_p)

Copy the coordinates of an object to an area

Parameters
  • obj: pointer to an object

  • cords_p: pointer to an area to store the coordinates

void lv_obj_get_inner_coords(const lv_obj_t *obj, lv_area_t *coords_p)

Reduce area retried by lv_obj_get_coords() the get graphically usable area of an object. (Without the size of the border or other extra graphical elements)

Parameters
  • coords_p: store the result area here

lv_coord_t lv_obj_get_x(const lv_obj_t *obj)

Get the x coordinate of object

Return

distance of 'obj' from the left side of its parent

Parameters
  • obj: pointer to an object

lv_coord_t lv_obj_get_y(const lv_obj_t *obj)

Get the y coordinate of object

Return

distance of 'obj' from the top of its parent

Parameters
  • obj: pointer to an object

lv_coord_t lv_obj_get_width(const lv_obj_t *obj)

Get the width of an object

Return

the width

Parameters
  • obj: pointer to an object

lv_coord_t lv_obj_get_height(const lv_obj_t *obj)

Get the height of an object

Return

the height

Parameters
  • obj: pointer to an object

lv_coord_t lv_obj_get_width_fit(const lv_obj_t *obj)

Get that width reduced by the left and right padding.

Return

the width which still fits into the container

Parameters
  • obj: pointer to an object

lv_coord_t lv_obj_get_height_fit(const lv_obj_t *obj)

Get that height reduced by the top an bottom padding.

Return

the height which still fits into the container

Parameters
  • obj: pointer to an object

lv_coord_t lv_obj_get_height_margin(lv_obj_t *obj)

Get the height of an object by taking the top and bottom margin into account. The returned height will be obj_h + margin_top + margin_bottom

Return

the height including thee margins

Parameters
  • obj: pointer to an object

lv_coord_t lv_obj_get_width_margin(lv_obj_t *obj)

Get the width of an object by taking the left and right margin into account. The returned width will be obj_w + margin_left + margin_right

Return

the height including thee margins

Parameters
  • obj: pointer to an object

lv_coord_t lv_obj_get_width_grid(lv_obj_t *obj, uint8_t div, uint8_t span)

Divide the width of the object and get the width of a given number of columns. Take paddings into account.

Return

the width according to the given parameters

Parameters
  • obj: pointer to an object

  • div: indicates how many columns are assumed. If 1 the width will be set the the parent's width If 2 only half parent width - inner padding of the parent If 3 only third parent width - 2 * inner padding of the parent

  • span: how many columns are combined

lv_coord_t lv_obj_get_height_grid(lv_obj_t *obj, uint8_t div, uint8_t span)

Divide the height of the object and get the width of a given number of columns. Take paddings into account.

Return

the height according to the given parameters

Parameters
  • obj: pointer to an object

  • div: indicates how many rows are assumed. If 1 the height will be set the the parent's height If 2 only half parent height - inner padding of the parent If 3 only third parent height - 2 * inner padding of the parent

  • span: how many rows are combined

bool lv_obj_get_auto_realign(const lv_obj_t *obj)

Get the automatic realign property of the object.

Return

true: auto realign is enabled; false: auto realign is disabled

Parameters
  • obj: pointer to an object

lv_coord_t lv_obj_get_ext_click_pad_left(const lv_obj_t *obj)

Get the left padding of extended clickable area

Return

the extended left padding

Parameters
  • obj: pointer to an object

lv_coord_t lv_obj_get_ext_click_pad_right(const lv_obj_t *obj)

Get the right padding of extended clickable area

Return

the extended right padding

Parameters
  • obj: pointer to an object

lv_coord_t lv_obj_get_ext_click_pad_top(const lv_obj_t *obj)

Get the top padding of extended clickable area

Return

the extended top padding

Parameters
  • obj: pointer to an object

lv_coord_t lv_obj_get_ext_click_pad_bottom(const lv_obj_t *obj)

Get the bottom padding of extended clickable area

Return

the extended bottom padding

Parameters
  • obj: pointer to an object

lv_coord_t lv_obj_get_ext_draw_pad(const lv_obj_t *obj)

Get the extended size attribute of an object

Return

the extended size attribute

Parameters
  • obj: pointer to an object

lv_style_list_t *lv_obj_get_style_list(const lv_obj_t *obj, uint8_t part)

Get the style list of an object's part.

Return

pointer to the style list. (Can be NULL)

Parameters
  • obj: pointer to an object.

  • part: part the part of the object which style list should be get. E.g. LV_OBJ_PART_MAIN, LV_BTN_PART_MAIN, LV_SLIDER_PART_KNOB

lv_style_int_t _lv_obj_get_style_int(const lv_obj_t *obj, uint8_t part, lv_style_property_t prop)

Get a style property of a part of an object in the object's current state. If there is a running transitions it is taken into account

Return

the value of the property of the given part in the current state. If the property is not found a default value will be returned.

Note

shouldn't be used directly. Use the specific property get functions instead. For example: lv_obj_style_get_border_width()

Note

for performance reasons it's not checked if the property really has integer type

Parameters
  • obj: pointer to an object

  • part: the part of the object which style property should be get. E.g. LV_OBJ_PART_MAIN, LV_BTN_PART_MAIN, LV_SLIDER_PART_KNOB

  • prop: the property to get. E.g. LV_STYLE_BORDER_WIDTH. The state of the object will be added internally

lv_color_t _lv_obj_get_style_color(const lv_obj_t *obj, uint8_t part, lv_style_property_t prop)

Get a style property of a part of an object in the object's current state. If there is a running transitions it is taken into account

Return

the value of the property of the given part in the current state. If the property is not found a default value will be returned.

Note

shouldn't be used directly. Use the specific property get functions instead. For example: lv_obj_style_get_border_color()

Note

for performance reasons it's not checked if the property really has color type

Parameters
  • obj: pointer to an object

  • part: the part of the object which style property should be get. E.g. LV_OBJ_PART_MAIN, LV_BTN_PART_MAIN, LV_SLIDER_PART_KNOB

  • prop: the property to get. E.g. LV_STYLE_BORDER_COLOR. The state of the object will be added internally

lv_opa_t _lv_obj_get_style_opa(const lv_obj_t *obj, uint8_t part, lv_style_property_t prop)

Get a style property of a part of an object in the object's current state. If there is a running transitions it is taken into account

Return

the value of the property of the given part in the current state. If the property is not found a default value will be returned.

Note

shouldn't be used directly. Use the specific property get functions instead. For example: lv_obj_style_get_border_opa()

Note

for performance reasons it's not checked if the property really has opacity type

Parameters
  • obj: pointer to an object

  • part: the part of the object which style property should be get. E.g. LV_OBJ_PART_MAIN, LV_BTN_PART_MAIN, LV_SLIDER_PART_KNOB

  • prop: the property to get. E.g. LV_STYLE_BORDER_OPA. The state of the object will be added internally

const void *_lv_obj_get_style_ptr(const lv_obj_t *obj, uint8_t part, lv_style_property_t prop)

Get a style property of a part of an object in the object's current state. If there is a running transitions it is taken into account

Return

the value of the property of the given part in the current state. If the property is not found a default value will be returned.

Note

shouldn't be used directly. Use the specific property get functions instead. For example: lv_obj_style_get_border_opa()

Note

for performance reasons it's not checked if the property really has pointer type

Parameters
  • obj: pointer to an object

  • part: the part of the object which style property should be get. E.g. LV_OBJ_PART_MAIN, LV_BTN_PART_MAIN, LV_SLIDER_PART_KNOB

  • prop: the property to get. E.g. LV_STYLE_TEXT_FONT. The state of the object will be added internally

lv_style_t *lv_obj_get_local_style(lv_obj_t *obj, uint8_t part)

Get the local style of a part of an object.

Return

pointer to the local style if exists else NULL.

Parameters
  • obj: pointer to an object

  • part: the part of the object which style property should be set. E.g. LV_OBJ_PART_MAIN, LV_BTN_PART_MAIN, LV_SLIDER_PART_KNOB

bool lv_obj_get_hidden(const lv_obj_t *obj)

Get the hidden attribute of an object

Return

true: the object is hidden

Parameters
  • obj: pointer to an object

bool lv_obj_get_adv_hittest(const lv_obj_t *obj)

Get whether advanced hit-testing is enabled on an object

Return

true: advanced hit-testing is enabled

Parameters
  • obj: pointer to an object

bool lv_obj_get_click(const lv_obj_t *obj)

Get the click enable attribute of an object

Return

true: the object is clickable

Parameters
  • obj: pointer to an object

bool lv_obj_get_top(const lv_obj_t *obj)

Get the top enable attribute of an object

Return

true: the auto top feature is enabled

Parameters
  • obj: pointer to an object

bool lv_obj_get_drag(const lv_obj_t *obj)

Get the drag enable attribute of an object

Return

true: the object is draggable

Parameters
  • obj: pointer to an object

lv_drag_dir_t lv_obj_get_drag_dir(const lv_obj_t *obj)

Get the directions an object can be dragged

Return

bitwise OR of allowed directions an object can be dragged in

Parameters
  • obj: pointer to an object

bool lv_obj_get_drag_throw(const lv_obj_t *obj)

Get the drag throw enable attribute of an object

Return

true: drag throw is enabled

Parameters
  • obj: pointer to an object

bool lv_obj_get_drag_parent(const lv_obj_t *obj)

Get the drag parent attribute of an object

Return

true: drag parent is enabled

Parameters
  • obj: pointer to an object

bool lv_obj_get_focus_parent(const lv_obj_t *obj)

Get the focus parent attribute of an object

Return

true: focus parent is enabled

Parameters
  • obj: pointer to an object

bool lv_obj_get_parent_event(const lv_obj_t *obj)

Get the drag parent attribute of an object

Return

true: drag parent is enabled

Parameters
  • obj: pointer to an object

bool lv_obj_get_gesture_parent(const lv_obj_t *obj)

Get the gesture parent attribute of an object

Return

true: gesture parent is enabled

Parameters
  • obj: pointer to an object

lv_bidi_dir_t lv_obj_get_base_dir(const lv_obj_t *obj)
uint8_t lv_obj_get_protect(const lv_obj_t *obj)

Get the protect field of an object

Return

protect field ('OR'ed values of lv_protect_t)

Parameters
  • obj: pointer to an object

bool lv_obj_is_protected(const lv_obj_t *obj, uint8_t prot)

Check at least one bit of a given protect bitfield is set

Return

false: none of the given bits are set, true: at least one bit is set

Parameters
  • obj: pointer to an object

  • prot: protect bits to test ('OR'ed values of lv_protect_t)

lv_state_t lv_obj_get_state(const lv_obj_t *obj, uint8_t part)
lv_signal_cb_t lv_obj_get_signal_cb(const lv_obj_t *obj)

Get the signal function of an object

Return

the signal function

Parameters
  • obj: pointer to an object

lv_design_cb_t lv_obj_get_design_cb(const lv_obj_t *obj)

Get the design function of an object

Return

the design function

Parameters
  • obj: pointer to an object

lv_event_cb_t lv_obj_get_event_cb(const lv_obj_t *obj)

Get the event function of an object

Return

the event function

Parameters
  • obj: pointer to an object

bool lv_obj_is_point_on_coords(lv_obj_t *obj, const lv_point_t *point)

Check if a given screen-space point is on an object's coordinates.

This method is intended to be used mainly by advanced hit testing algorithms to check whether the point is even within the object (as an optimization).

Parameters
  • obj: object to check

  • point: screen-space point

bool lv_obj_hittest(lv_obj_t *obj, lv_point_t *point)

Hit-test an object given a particular point in screen space.

Return

true if the object is considered under the point

Parameters
  • obj: object to hit-test

  • point: screen-space point

void *lv_obj_get_ext_attr(const lv_obj_t *obj)

Get the ext pointer

Return

the ext pointer but not the dynamic version Use it as ext->data1, and NOT da(ext)->data1

Parameters
  • obj: pointer to an object

void lv_obj_get_type(const lv_obj_t *obj, lv_obj_type_t *buf)

Get object's and its ancestors type. Put their name in type_buf starting with the current type. E.g. buf.type[0]="lv_btn", buf.type[1]="lv_cont", buf.type[2]="lv_obj"

Parameters
  • obj: pointer to an object which type should be get

  • buf: pointer to an lv_obj_type_t buffer to store the types

lv_obj_user_data_t lv_obj_get_user_data(const lv_obj_t *obj)

Get the object's user data

Return

user data

Parameters
  • obj: pointer to an object

lv_obj_user_data_t *lv_obj_get_user_data_ptr(const lv_obj_t *obj)

Get a pointer to the object's user data

Return

pointer to the user data

Parameters
  • obj: pointer to an object

void lv_obj_set_user_data(lv_obj_t *obj, lv_obj_user_data_t data)

Set the object's user data. The data will be copied.

Parameters
  • obj: pointer to an object

  • data: user data

void *lv_obj_get_group(const lv_obj_t *obj)

Get the group of the object

Return

the pointer to group of the object

Parameters
  • obj: pointer to an object

bool lv_obj_is_focused(const lv_obj_t *obj)

Tell whether the object is the focused object of a group or not.

Return

true: the object is focused, false: the object is not focused or not in a group

Parameters
  • obj: pointer to an object

lv_obj_t *lv_obj_get_focused_obj(const lv_obj_t *obj)

Get the really focused object by taking focus_parent into account.

Return

the object to really focus

Parameters
  • obj: the start object

lv_res_t lv_obj_handle_get_type_signal(lv_obj_type_t *buf, const char *name)

Used in the signal callback to handle LV_SIGNAL_GET_TYPE signal

Return

LV_RES_OK

Parameters
  • buf: pointer to lv_obj_type_t. (param in the signal callback)

  • name: name of the object. E.g. "lv_btn". (Only the pointer is saved)

void lv_obj_init_draw_rect_dsc(lv_obj_t *obj, uint8_t type, lv_draw_rect_dsc_t *draw_dsc)

Initialize a rectangle descriptor from an object's styles

Note

Only the relevant fields will be set. E.g. if border width == 0 the other border properties won't be evaluated.

Parameters
  • obj: pointer to an object

  • type: type of style. E.g. LV_OBJ_PART_MAIN, LV_BTN_SLIDER_KOB

  • draw_dsc: the descriptor the initialize

void lv_obj_init_draw_label_dsc(lv_obj_t *obj, uint8_t type, lv_draw_label_dsc_t *draw_dsc)
void lv_obj_init_draw_img_dsc(lv_obj_t *obj, uint8_t part, lv_draw_img_dsc_t *draw_dsc)
void lv_obj_init_draw_line_dsc(lv_obj_t *obj, uint8_t part, lv_draw_line_dsc_t *draw_dsc)
lv_coord_t lv_obj_get_draw_rect_ext_pad_size(lv_obj_t *obj, uint8_t part)

Get the required extra size (around the object's part) to draw shadow, outline, value etc.

Parameters
  • obj: pointer to an object

  • part: part of the object

void lv_obj_fade_in(lv_obj_t *obj, uint32_t time, uint32_t delay)

Fade in (from transparent to fully cover) an object and all its children using an opa_scale animation.

Parameters
  • obj: the object to fade in

  • time: duration of the animation [ms]

  • delay: wait before the animation starts [ms]

void lv_obj_fade_out(lv_obj_t *obj, uint32_t time, uint32_t delay)

Fade out (from fully cover to transparent) an object and all its children using an opa_scale animation.

Parameters
  • obj: the object to fade in

  • time: duration of the animation [ms]

  • delay: wait before the animation starts [ms]

bool lv_debug_check_obj_type(const lv_obj_t *obj, const char *obj_type)

Check if any object has a given type

Return

true: valid

Parameters
  • obj: pointer to an object

  • obj_type: type of the object. (e.g. "lv_btn")

bool lv_debug_check_obj_valid(const lv_obj_t *obj)

Check if any object is still "alive", and part of the hierarchy

Return

true: valid

Parameters
  • obj: pointer to an object

  • obj_type: type of the object. (e.g. "lv_btn")

struct lv_realign_t

Public Members

const struct _lv_obj_t *base
lv_coord_t xofs
lv_coord_t yofs
lv_align_t align
uint8_t auto_realign
uint8_t origo_align

1: the origo (center of the object) was aligned with lv_obj_align_origo

struct _lv_obj_t

Public Members

struct _lv_obj_t *parent

Pointer to the parent object

lv_ll_t child_ll

Linked list to store the children objects

lv_area_t coords

Coordinates of the object (x1, y1, x2, y2)

lv_event_cb_t event_cb

Event callback function

lv_signal_cb_t signal_cb

Object type specific signal function

lv_design_cb_t design_cb

Object type specific design function

void *ext_attr

Object type specific extended data

lv_style_list_t style_list
uint8_t ext_click_pad_hor

Extra click padding in horizontal direction

uint8_t ext_click_pad_ver

Extra click padding in vertical direction

lv_area_t ext_click_pad

Extra click padding area.

lv_coord_t ext_draw_pad

EXTend the size in every direction for drawing.

uint8_t click

1: Can be pressed by an input device

uint8_t drag

1: Enable the dragging

uint8_t drag_throw

1: Enable throwing with drag

uint8_t drag_parent

1: Parent will be dragged instead

uint8_t hidden

1: Object is hidden

uint8_t top

1: If the object or its children is clicked it goes to the foreground

uint8_t parent_event

1: Send the object's events to the parent too.

uint8_t adv_hittest

1: Use advanced hit-testing (slower)

uint8_t gesture_parent

1: Parent will be gesture instead

uint8_t focus_parent

1: Parent will be focused instead

lv_drag_dir_t drag_dir

Which directions the object can be dragged in

lv_bidi_dir_t base_dir

Base direction of texts related to this object

void *group_p
uint8_t protect

Automatically happening actions can be prevented. 'OR'ed values from lv_protect_t

lv_state_t state
lv_realign_t realign

Information about the last call to lv_obj_align.

lv_obj_user_data_t user_data

Custom user data for object.

struct lv_obj_type_t
#include <lv_obj.h>

Used by lv_obj_get_type(). The object's and its ancestor types are stored here

Public Members

const char *type[LV_MAX_ANCESTOR_NUM]

[0]: the actual type, [1]: ancestor, [2] #1's ancestor ... [x]: "lv_obj"

struct lv_hit_test_info_t

Public Members

lv_point_t *point
bool result
struct lv_get_style_info_t

Public Members

uint8_t part
lv_style_list_t *result
struct lv_get_state_info_t

Public Members

uint8_t part
lv_state_t result