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: Alignment types in LittlevGL

    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

code

#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

Simeple Base object example in LittlevGL with MicroPython

code

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:

LV_DESIGN_DRAW_MAIN

Draw the main portion of the object

LV_DESIGN_DRAW_POST

Draw extras on the object

LV_DESIGN_COVER_CHK

Check if the object fully covers the ‘mask_p’ area

enum [anonymous]

Values:

LV_EVENT_PRESSED

The object has been pressed

LV_EVENT_PRESSING

The object is being pressed (called continuously while pressing)

LV_EVENT_PRESS_LOST

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

LV_EVENT_SHORT_CLICKED

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

LV_EVENT_LONG_PRESSED

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

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.

LV_EVENT_CLICKED

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

LV_EVENT_RELEASED

Called in every cases when the object has been released

LV_EVENT_DRAG_BEGIN
LV_EVENT_DRAG_END
LV_EVENT_DRAG_THROW_BEGIN
LV_EVENT_KEY
LV_EVENT_FOCUSED
LV_EVENT_DEFOCUSED
LV_EVENT_VALUE_CHANGED

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

LV_EVENT_INSERT
LV_EVENT_REFRESH
LV_EVENT_APPLY

“Ok”, “Apply” or similar specific button has clicked

LV_EVENT_CANCEL

“Close”, “Cancel” or similar specific button has clicked

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:

LV_SIGNAL_CLEANUP

Object is being deleted

LV_SIGNAL_CHILD_CHG

Child was removed/added

LV_SIGNAL_CORD_CHG

Object coordinates/size have changed

LV_SIGNAL_PARENT_SIZE_CHG

Parent’s size has changed

LV_SIGNAL_STYLE_CHG

Object’s style has changed

LV_SIGNAL_BASE_DIR_CHG

The base dir has changed

LV_SIGNAL_REFR_EXT_DRAW_PAD

Object’s extra padding has changed

LV_SIGNAL_GET_TYPE

LittlevGL needs to retrieve the object’s type

LV_SIGNAL_PRESSED

The object has been pressed

LV_SIGNAL_PRESSING

The object is being pressed (called continuously while pressing)

LV_SIGNAL_PRESS_LOST

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

LV_SIGNAL_RELEASED

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

LV_SIGNAL_LONG_PRESS

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

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.

LV_SIGNAL_DRAG_BEGIN
LV_SIGNAL_DRAG_END
LV_SIGNAL_FOCUS
LV_SIGNAL_DEFOCUS
LV_SIGNAL_CONTROL
LV_SIGNAL_GET_EDITABLE
enum [anonymous]

Object alignment.

Values:

LV_ALIGN_CENTER = 0
LV_ALIGN_IN_TOP_LEFT
LV_ALIGN_IN_TOP_MID
LV_ALIGN_IN_TOP_RIGHT
LV_ALIGN_IN_BOTTOM_LEFT
LV_ALIGN_IN_BOTTOM_MID
LV_ALIGN_IN_BOTTOM_RIGHT
LV_ALIGN_IN_LEFT_MID
LV_ALIGN_IN_RIGHT_MID
LV_ALIGN_OUT_TOP_LEFT
LV_ALIGN_OUT_TOP_MID
LV_ALIGN_OUT_TOP_RIGHT
LV_ALIGN_OUT_BOTTOM_LEFT
LV_ALIGN_OUT_BOTTOM_MID
LV_ALIGN_OUT_BOTTOM_RIGHT
LV_ALIGN_OUT_LEFT_TOP
LV_ALIGN_OUT_LEFT_MID
LV_ALIGN_OUT_LEFT_BOTTOM
LV_ALIGN_OUT_RIGHT_TOP
LV_ALIGN_OUT_RIGHT_MID
LV_ALIGN_OUT_RIGHT_BOTTOM
enum [anonymous]

Values:

LV_DRAG_DIR_HOR = 0x1

Object can be dragged horizontally.

LV_DRAG_DIR_VER = 0x2

Object can be dragged vertically.

LV_DRAG_DIR_ALL = 0x3

Object can be dragged in all directions.

enum [anonymous]

Values:

LV_PROTECT_NONE = 0x00
LV_PROTECT_CHILD_CHG = 0x01

Disable the child change signal. Used by the library

LV_PROTECT_PARENT = 0x02

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

LV_PROTECT_POS = 0x04

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

LV_PROTECT_FOLLOW = 0x08

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

LV_PROTECT_PRESS_LOST = 0x10

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

LV_PROTECT_CLICK_FOCUS = 0x20

Prevent focusing the object by clicking on it

Functions

void lv_init(void)

Init. the ‘lv’ library.

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(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(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(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(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(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(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(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 i nteh signal callback)

  • name: name of the object. E.g. “lv_btn”. (Only teh 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”