Overview

The Base Object contains the the most basic attributes of the objects:

  • Coordinates
  • Parent object
  • Children
  • Style
  • Attributes like Click enable, Drag enable etc.

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 in one function with lv_obj_set_pos(obj, new_x, new_y).

The object size can be modified with lv_obj_set_width(obj, new_width) and lv_obj_set_height(obj, new_height) or in one function with lv_obj_set_size(obj, new_width, new_height).

You can align the object to an other with lv_obj_align(obj1, obj2, LV_ALIGN_TYPE, x_shift, y_shift). The last two argument means an x and y shift after the alignment. The second argument is an other object where to align the first (NULL means: align to the parent). The third argument is the type of alignment: Alignment types

The alignment types build like: LV_ALIGN_OUT_TOP_MID. 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).

You can set a new parent for an object with lv_obj_set_parent(obj, new_parent).

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 then the previous child (return value). The function return with NULL is no more children

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.

There are two layer automatically generated layers:

  • top layer
  • system layer

They are independent from the screens so objects created an that layers will be shown on every screen. The top layer is above every object on the screen and system layer is above top layer too. You can add any pop-up windows top layer freely. But the system layer restricted to system level things (e.g. mouse cursor will be moved here). The lv_layer_top() and lv_layer_sys() functions gives a pointer to the top or system layer.

You can set a new style for an object with the lv_obj_set_style(obj, &new_style) function. If NULL is set as style then the object will inherit its parent's style. If you modify a style you have to notify the objects who are using the modified styled. You can use either lv_obj_refresh_style(obj) or to notify all object with a given style lv_obj_report_style_mod(&style). Set lv_obj_report_style_mod's parameter to NULL to notify all objects.

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 won't occupy space, Its children will be hidden too.
  • click Enabled to click the object via an input device(e.g. touch pad). If disabled then object behind this one will be checked during the input device click handling (useful with typically not clickable objects like Labels)
  • 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 a n input device)
  • drag_throw Enable "throwing" with dragging like the object would have momentum
  • drag_parent If enabled then the object's parent will be moved during dragging.

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 lv_cont)
  • LV_PROTECT_FOLLOW Prevent the object be followed in automatic ordering (e.g. Layout in lv_cont)
  • LV_PROTECT_PARENT Prevent automatic parent change
  • LV_PROTECT_CHILD_CHG Disable the child change signal. Used by the library

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

There are built-in animations for the objects. The following animation types exist:

  • LV_ANIM_FLOAT_TOP Float from/to the top
  • LV_ANIM_FLOAT_LEFT Float from/to the left
  • LV_ANIM_FLOAT_BOTTOM Float from/to the bottom
  • LV_ANIM_FLOAT_RIGHT Float from/to the right
  • LV_ANIM_GROW_H Grow/shrink horizontally
  • LV_ANIM_GROW_V Grow/shrink vertically

The lv_obj_animate(obj, anim_type, time, delay, callback) applies an animation on obj. To determinate the direction of the animation OR ANIM_IN or ANIM_OUT with the animation type. The default is ANIM_IN if not specified. You can learn more about the animations.

Style usage

All style.body properties are used. Default for screens lv_style_plain and lv_style_plain_color for normal objects

Notes

Example of Base obj in Littlev Graphics Library

						/*Create a simple base object*/
lv_obj_t * obj1;
obj1 = lv_obj_create(lv_scr_act(), NULL);
lv_obj_set_size(obj1, 150, 40);
lv_obj_set_style(obj1, &lv_style_plain_color);
lv_obj_align(obj1, NULL, LV_ALIGN_IN_TOP_MID, 0, 40);

/*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_set_drag(obj2, true);
lv_obj_align(obj2, NULL, LV_ALIGN_CENTER, 0, 0);

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_IN_BOTTOM_MID, 0, -40);

void

lv_init

(void);

Init. the 'lv' library.

lv_obj_t *

lv_obj_create

(lv_obj_t * parent, lv_obj_t * copy);

Create a basic object

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

return pointer to the new object

lv_res_t

lv_obj_del

(lv_obj_t * obj);

Delete 'obj' and all of its children

obj pointer to an object to delete

return LV_RES_INV because the object is deleted

void

lv_obj_clean

(lv_obj_t *obj);

Delete all children of an object

obj pointer to an object

void

lv_obj_invalidate

(lv_obj_t * obj);

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

obj pointer to an object

void

lv_scr_load

(lv_obj_t * scr);

Load a new screen

scr pointer to a screen

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.

obj pointer to an object

parent pointer to the new parent 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)

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

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

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

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

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

obj pointer to an object

h new height

void

lv_obj_align

(lv_obj_t * obj,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.

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_set_style

(lv_obj_t * obj, lv_style_t * style);

Set a new style for an object

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

obj pointer to an object

void

lv_obj_report_style_mod

(lv_style_t * style);

Notify all object if a style is modified

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.

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

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

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

obj pointer to an object

en true: make the object dragable

void

lv_obj_set_drag_throw

(lv_obj_t * obj, bool en);

Enable the throwing of an object after is is dragged

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

obj pointer to an object

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

void

lv_obj_set_protect

(lv_obj_t * obj, uint8_t prot);

Set a bit or bits in the protect filed

obj pointer to an object

prot 'OR'-ed values from lv_obj_prot_t

void

lv_obj_clear_protect

(lv_obj_t * obj, uint8_t prot);

Clear a bit or bits in the protect filed

obj pointer to an object

prot 'OR'-ed values from lv_obj_prot_t

void

lv_obj_set_signal_func

(lv_obj_t * obj, lv_signal_func_t fp);

Set the signal function of an object.
Always call the previous signal function in the new.

obj pointer to an object

fp the new signal function

void

lv_obj_set_design_func

(lv_obj_t * obj, lv_design_func_t fp);

Set a new design function for an object

obj pointer to an object

fp 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

obj pointer to an object

ext_size the size of the new ext. data

return pointer to the allocated ext

void

lv_obj_refresh_ext_size

(lv_obj_t * obj);

Send a 'LV_SIGNAL_REFR_EXT_SIZE' signal to the object

obj pointer to an object

void

lv_obj_set_free_num

(lv_obj_t * obj, LV_OBJ_FREE_NUM_TYPE free_num);

Set an application specific number for an object.
It can help to identify objects in the application.

obj pointer to an object

free_num the new free number

void

lv_obj_set_free_ptr

(lv_obj_t * obj, void * free_p);

Set an application specific pointer for an object.
It can help to identify objects in the application.

obj pointer to an object

free_p the new free pinter

void

lv_obj_animate

(lv_obj_t * obj, lv_anim_builtin_t type, uint16_t time, uint16_t delay, void (*cb) (lv_obj_t *));

Animate an object

obj pointer to an object to animate

type type of animation from 'lv_anim_builtin_t'. 'OR' it with ANIM_IN or ANIM_OUT

time time of animation in milliseconds

delay delay before the animation in milliseconds

cb a function to call when the animation is ready

lv_obj_t *

lv_scr_act

(void);

Return with a pointer to the active screen

return pointer to the active screen object (loaded by 'lv_scr_load()')

lv_obj_t *

lv_layer_top

(void);

Return with the top layer. (Same on every screen and it is above the normal screen layer)

return pointer to the top layer object (transparent screen sized lv_obj)

lv_obj_t *

lv_layer_sys

(void);

Return with the system layer. (Same on every screen and it is above the all other layers)
It is used for example by the cursor

return pointer to the system layer object (transparent screen sized lv_obj)

lv_obj_t *

lv_obj_get_screen

(lv_obj_t * obj);

Return with the screen of an object

obj pointer to an object

return pointer to a screen

lv_obj_t *

lv_obj_get_parent

(lv_obj_t * obj);

Returns with the parent of an object

obj pointer to an object

return pointer to the parent of 'obj'

lv_obj_t *

lv_obj_get_child

(lv_obj_t * obj, lv_obj_t * child);

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

obj pointer to an object

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

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

lv_obj_t *

lv_obj_get_child_back

(lv_obj_t * obj, lv_obj_t * child);

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

obj pointer to an object

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

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

uint16_t

lv_obj_count_children

(lv_obj_t * obj);

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

obj pointer to an object

return children number of 'obj'

void

lv_obj_get_coords

(lv_obj_t * obj, lv_area_t * cords_p);

Copy the coordinates of an object to an area

obj pointer to an object

cords_p pointer to an area to store the coordinates

lv_coord_t

lv_obj_get_x

(lv_obj_t * obj);

Get the x coordinate of object

obj pointer to an object

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

lv_coord_t

lv_obj_get_y

(lv_obj_t * obj);

Get the y coordinate of object

obj pointer to an object

return distance of 'obj' from the top of its parent

lv_coord_t

lv_obj_get_width

(lv_obj_t * obj);

Get the width of an object

obj pointer to an object

return the width

lv_coord_t

lv_obj_get_height

(lv_obj_t * obj);

Get the height of an object

obj pointer to an object

return the height

lv_coord_t

lv_obj_get_ext_size

(lv_obj_t * obj);

Get the extended size attribute of an object

obj pointer to an object

return the extended size attribute

lv_style_t *

lv_obj_get_style

(lv_obj_t * obj);

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

obj pointer to an object

return pointer to a style

bool

lv_obj_get_hidden

(lv_obj_t * obj);

Get the hidden attribute of an object

obj pointer to an object

return true: the object is hidden

bool

lv_obj_get_click

(lv_obj_t * obj);

Get the click enable attribute of an object

obj pointer to an object

return true: the object is clickable

bool

lv_obj_get_top

(lv_obj_t * obj);

Get the top enable attribute of an object

obj pointer to an object

return true: the auto top feture is enabled

bool

lv_obj_get_drag

(lv_obj_t * obj);

Get the drag enable attribute of an object

obj pointer to an object

return true: the object is dragable

bool

lv_obj_get_drag_throw

(lv_obj_t * obj);

Get the drag thow enable attribute of an object

obj pointer to an object

return true: drag throw is enabled

bool

lv_obj_get_drag_parent

(lv_obj_t * obj);

Get the drag parent attribute of an object

obj pointer to an object

return true: drag parent is enabled

uint8_t

lv_obj_get_protect

(lv_obj_t * obj);

Get the protect field of an object

obj pointer to an object

return protect field ('OR'ed values of lv_obj_prot_t)

bool

lv_obj_is_protected

(lv_obj_t * obj, uint8_t prot);

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

obj pointer to an object

prot protect bits to test ('OR'ed values of lv_obj_prot_t)

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

lv_signal_func_t

lv_obj_get_signal_func

(lv_obj_t * obj);

Get the signal function of an object

obj pointer to an object

return the signal function

lv_design_func_t

lv_obj_get_design_func

(lv_obj_t * obj);

Get the design function of an object

obj pointer to an object

return the design function

void *

lv_obj_get_ext_attr

(lv_obj_t * obj);

Get the ext pointer

obj pointer to an object

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

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"

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_FREE_NUM_TYPE

lv_obj_get_free_num

(lv_obj_t * obj);

Get the free number

obj pointer to an object

return the free number

void *

lv_obj_get_free_ptr

(lv_obj_t * obj);

Get the free pointer

obj pointer to an object

return the free pointer

void *

lv_obj_get_group

(lv_obj_t * obj);

Get the group of the object

obj pointer to an object

return the pointer to group of the object

LittlevGL - Open-source Embedded GUI Library

LittlevGL is a free and open-source graphics library providing everything you need to create embedded GUI with easy-to-use graphical elements, beautiful visual effects and low memory footprint.

If you like LittlevGL, please
support its deveopment!


The founder of Littlev Graphics Library (LittlevGL) and related software modules is:
Gábor Kiss-Vámosi
All Rights Reserved ©  2018 Hungary