Base object (lv_obj)¶

Overview¶

The ‘Base Object’ implements the basic properties of an object 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 which all other objects in LittlevGL inherit from. This, among another things, helps reduce code duplication.

Coordinates¶

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).

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).

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

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:

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 rather than the top-left corner.

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;
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_create(NULL, NULL), you can load it with lv_scr_load(screen1). 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 the screen an object is assigned to, 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 the same layers 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.

Style¶

The base object stores the Main style of the object. To set a new style, use lv_obj_set_style(obj, &new_style) function. If NULL is set as style, then the object will inherit its parent’s style.

Note that, you should use lv_obj_set_style only for “Base objects”. Every other object type has its own style set function which should be used for them. For example, a button should use lv_btn_set_style().

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.

Read the Style overview to learn more about styles.

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.

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.

Opa scale¶

If lv_obj_set_opa_scale_enable(obj, true) is set for an object, then the object’s and all of its children’s opacity can be adjusted with lv_obj_set_opa_scale(obj, LV_OPA_...). The opacities stored in the styles will be scaled down by this factor.

It is very useful to fade in/out an object with some children using an Animation.

A little bit of technical background: during the rendering process, the opacity of the object is decided by searching recursively up the object’s family tree to find the first object with opacity scaling (Opa scale) enabled.

If an object is found with an enabled Opa scale, then that Opa scale will be used by the rendered object too.

Therefore, if you want to disable the Opa scaling for an object when the parent has Opa scale, just enable Opa scaling for the object and set its value to LV_OPA_COVER. It will overwrite the parent’s settings.

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

Styles¶

Use lv_obj_set_style(obj, &style) to set a style for a base object.

All style.body properties are used. The default style for screens is lv_style_scr and lv_style_plain_color for normal objects

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

#include "lvgl/lvgl.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_set_style(obj1, &lv_style_plain_color);
    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_set_style(obj2, &lv_style_pretty_color);
    lv_obj_align(obj2, NULL, LV_ALIGN_CENTER, 0, 0);
    lv_obj_set_drag(obj2, true);

    static lv_style_t style_shadow;
    lv_style_copy(&style_shadow, &lv_style_pretty);
    style_shadow.body.shadow.width = 6;
    style_shadow.body.radius = LV_RADIUS_CIRCLE;

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

MicroPython¶

Base obejcts with custom styles¶

obj1 = lv.obj(lv.scr_act())
obj1.set_size(100, 50)
obj1.set_style(lv.style_plain_color)
obj1.align(None, lv.ALIGN.CENTER, -60, -30)

# Copy the previous object and enable drag
obj2 = lv.obj(lv.scr_act(), obj1)
obj2.set_style(lv.style_pretty_color)
obj2.align(None, lv.ALIGN.CENTER, 0, 0)
obj2.set_drag(True)

style_shadow = lv.style_t()
lv.style_copy(style_shadow, lv.style_pretty)
style_shadow.body.shadow.width = 6
style_shadow.body.radius = 800 # large enough to make it round

# Copy the previous object (drag is already enabled)
obj3 = lv.obj(lv.scr_act(), obj2)
obj3.set_style(style_shadow)
obj3.align(None, lv.ALIGN.CENTER, 60, 30)

API¶

Typedefs

typedef uint8_t lv_design_mode_t¶

typedef bool (*lv_design_cb_t)(struct _lv_obj_t *obj, const lv_area_t *mask_p, 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_align_t¶

typedef uint8_t lv_drag_dir_t¶

typedef struct _lv_obj_t lv_obj_t¶

typedef uint8_t lv_protect_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]¶

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_KEY¶

enumerator LV_EVENT_FOCUSED¶

enumerator LV_EVENT_DEFOCUSED¶

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_CORD_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¶: LittlevGL needs to retrieve the object’s type

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_END¶

enumerator LV_SIGNAL_FOCUS¶

enumerator LV_SIGNAL_DEFOCUS¶

enumerator LV_SIGNAL_CONTROL¶

enumerator LV_SIGNAL_GET_EDITABLE¶

enum [anonymous]¶

Object alignment.

Values:

enumerator LV_ALIGN_CENTER = 0¶

enumerator LV_ALIGN_IN_TOP_LEFT¶

enumerator LV_ALIGN_IN_TOP_MID¶

enumerator LV_ALIGN_IN_TOP_RIGHT¶

enumerator LV_ALIGN_IN_BOTTOM_LEFT¶

enumerator LV_ALIGN_IN_BOTTOM_MID¶

enumerator LV_ALIGN_IN_BOTTOM_RIGHT¶

enumerator LV_ALIGN_IN_LEFT_MID¶

enumerator LV_ALIGN_IN_RIGHT_MID¶

enumerator LV_ALIGN_OUT_TOP_LEFT¶

enumerator LV_ALIGN_OUT_TOP_MID¶

enumerator LV_ALIGN_OUT_TOP_RIGHT¶

enumerator LV_ALIGN_OUT_BOTTOM_LEFT¶

enumerator LV_ALIGN_OUT_BOTTOM_MID¶

enumerator LV_ALIGN_OUT_BOTTOM_RIGHT¶

enumerator LV_ALIGN_OUT_LEFT_TOP¶

enumerator LV_ALIGN_OUT_LEFT_MID¶

enumerator LV_ALIGN_OUT_LEFT_BOTTOM¶

enumerator LV_ALIGN_OUT_RIGHT_TOP¶

enumerator LV_ALIGN_OUT_RIGHT_MID¶

enumerator LV_ALIGN_OUT_RIGHT_BOTTOM¶

enum [anonymous]¶

Values:

enumerator LV_DRAG_DIR_HOR = 0x1¶: Object can be dragged horizontally.

enumerator LV_DRAG_DIR_VER = 0x2¶: Object can be dragged vertically.

enumerator LV_DRAG_DIR_ALL = 0x3¶: Object can be dragged in all directions.

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

Functions

void lv_init(void)¶: Init. the ‘lv’ library.

void lv_deinit(void)¶: Deinit the ‘lv’ library Currently only implemented when not using custorm 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_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_align(lv_obj_t *obj, const lv_obj_t *base, lv_align_t align, lv_coord_t x_mod, lv_coord_t y_mod)¶

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_mod: x coordinate shift after alignment
y_mod: y coordinate shift after alignment

void lv_obj_align_origo(lv_obj_t *obj, const lv_obj_t *base, lv_align_t align, lv_coord_t x_mod, lv_coord_t y_mod)¶

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_mod: x coordinate shift after alignment
y_mod: y coordinate shift 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_set_style(lv_obj_t *obj, const lv_style_t *style)¶

Set a new style for an object

Parameters

obj: pointer to an object
style_p: pointer to the new style

void lv_obj_refresh_style(lv_obj_t *obj)¶

Notify an object about its style is modified

Parameters

obj: pointer to an object

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_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_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 dragable

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_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)¶

void lv_obj_set_opa_scale_enable(lv_obj_t *obj, bool en)¶

Set the opa scale enable parameter (required to set opa_scale with lv_obj_set_opa_scale())

Parameters

obj: pointer to an object
en: true: opa scaling is enabled for this object and all children; false: no opa scaling

void lv_obj_set_opa_scale(lv_obj_t *obj, lv_opa_t opa_scale)¶

Set the opa scale of an object. The opacity of this object and all it’s children will be scaled down with this factor. lv_obj_set_opa_scale_enable(obj, true) needs to be called to enable it. (not for all children just for the parent where to start the opa scaling)

Parameters

obj: pointer to an object
opa_scale: a factor to scale down opacity [0..255]

void lv_obj_set_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_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

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

Send an event to the object

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

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

Parameters

scr: pointer to an object

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

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

const lv_style_t *lv_obj_get_style(const lv_obj_t *obj)¶

Get the style pointer of an object (if NULL get style of the parent)

Return

pointer to a style

Parameters

obj: pointer to an object

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_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 dragable

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_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

lv_bidi_dir_t lv_obj_get_base_dir(const lv_obj_t *obj)¶

lv_opa_t lv_obj_get_opa_scale_enable(const lv_obj_t *obj)¶

Get the opa scale enable parameter

Return

true: opa scaling is enabled for this object and all children; false: no opa scaling

Parameters

obj: pointer to an object

lv_opa_t lv_obj_get_opa_scale(const lv_obj_t *obj)¶

Get the opa scale parameter of an object

Return

opa scale [0..255]

Parameters

obj: pointer to an object

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_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

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_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)

struct lv_reailgn_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 *par¶: 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

const lv_style_t *style_p¶: Pointer to the object’s style

void *group_p¶: Pointer to the group of the object

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.

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 opa_scale_en¶: 1: opa_scale is set

uint8_t parent_event¶: 1: Send the object’s events to the parent too.

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

uint8_t reserved¶: Reserved for future use

uint8_t protect¶: Automatically happening actions can be prevented. ‘OR’ed values from lv_protect_t

lv_opa_t opa_scale¶: Scale down the opacity by this factor. Effects all children as well

lv_coord_t ext_draw_pad¶: EXTtend the size in every direction for drawing.

lv_reailgn_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”