Base object (lv_obj) — LVGL documentation (2024)

Coordinates

Only a small subset of coordinate settings is described here. To see allthe features of LVGL (padding, coordinates in styles, layouts, etc)visit the Coordinates page.

lv_obj_set_align(obj, LV_ALIGN_CENTER);lv_obj_set_pos(obj, 10, 20);//Or in one functionlv_obj_align(obj, LV_ALIGN_CENTER, 10, 20);

Parents and children

You can set a new parent for an object withlv_obj_set_parent(obj, new_parent). To get the current parent, uselv_obj_get_parent(obj).

To get a specific child of a parent use lv_obj_get_child(parent, idx). Some examples for idx:

• 0 get the child created first

• 1 get the child created second

• -1 get the child created last

The children can be iterated like this:

uint32_t i;for(i = 0; i < lv_obj_get_child_count(parent); i++) { lv_obj_t * child = lv_obj_get_child(parent, i); /*Do something with child*/}

lv_obj_get_index(obj) returns the index of the object in its parent.It is equivalent to the number of younger children in the parent.

You can bring an object to the foreground or send it to the backgroundwith lv_obj_move_foreground(obj) andlv_obj_move_background(obj).

You can change the index of an object in its parent usinglv_obj_move_to_index(obj, index).

You can swap the position of two objects withlv_obj_swap(obj1, obj2).

Display and Screens

At the highest level of the LVGL object hierarchy is the display whichrepresents the driver for a display device (physical display orsimulator). A display can have one or more screens associated with it.Each screen contains a hierarchy of objects for graphical widgetsrepresenting a layout that covers the entire display.

When you have created a screen likelv_obj_t * screen = lv_obj_create(NULL), you can make it active withlv_screen_load(screen). The lv_screen_active() function gives you apointer to the active screen.

If you have multiple displays, it's important to know that the screenfunctions operate on the most recently created display or the oneexplicitly selected with lv_display_set_default().

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

Events

To set an event callback for an object, uselv_obj_add_event_cb(obj, event_cb, LV_EVENT_..., user_data),

To manually send an event to an object, uselv_event_send(obj, LV_EVENT_..., param)

Read the Event overview to learn more aboutevents.

Styles

Be sure to read the Style overview. Here only themost essential functions are described.

A new style can be added to an object with thelv_obj_add_style(obj, &new_style, selector) function. selectoris an ORed combination of part and state(s). E.g.LV_PART_SCROLLBAR | LV_STATE_PRESSED.

The base objects use LV_PART_MAIN style properties andLV_PART_SCROLLBAR with the typical background style properties.

Flags

There are some attributes which can be enabled/disabled bylv_obj_add/remove_flag(obj, LV_OBJ_FLAG_...) and lv_obj_set_flag(obj, LV_OBJ_FLAG_..., true/false)

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

• LV_OBJ_FLAG_CLICKABLE Make the object clickable by input devices

• LV_OBJ_FLAG_CLICK_FOCUSABLE Add focused state to the object when clicked

• LV_OBJ_FLAG_CHECKABLE Toggle checked state when the object is clicked

• LV_OBJ_FLAG_SCROLLABLE Make the object scrollable

• LV_OBJ_FLAG_SCROLL_ELASTIC Allow scrolling inside but with slower speed

• LV_OBJ_FLAG_SCROLL_MOMENTUM Make the object scroll further when "thrown"

• LV_OBJ_FLAG_SCROLL_ONE Allow scrolling only one snappable children

• LV_OBJ_FLAG_SCROLL_CHAIN_HOR Allow propagating the horizontal scroll to a parent

• LV_OBJ_FLAG_SCROLL_CHAIN_VER Allow propagating the vertical scroll to a parent

• LV_OBJ_FLAG_SCROLL_CHAIN Simple packaging for (LV_OBJ_FLAG_SCROLL_CHAIN_HOR | LV_OBJ_FLAG_SCROLL_CHAIN_VER)

• LV_OBJ_FLAG_SCROLL_ON_FOCUS Automatically scroll object to make it visible when focused

• LV_OBJ_FLAG_SCROLL_WITH_ARROW Allow scrolling the focused object with arrow keys

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

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

• LV_OBJ_FLAG_EVENT_BUBBLE Propagate the events to the parent too

  See Also

  lv_obj_pos.h — LVGL documentation

• LV_OBJ_FLAG_GESTURE_BUBBLE Propagate the gestures to the parent

• LV_OBJ_FLAG_ADV_HITTEST Allow performing more accurate hit (click) test. E.g. accounting for rounded corners

• LV_OBJ_FLAG_IGNORE_LAYOUT Make the object positionable by the layouts

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

• LV_OBJ_FLAG_SEND_DRAW_TASK_EVENTS Enable sending LV_EVENT_DRAW_TASK_ADDED events

• LV_OBJ_FLAG_OVERFLOW_VISIBLE Do not clip the children's content to the parent's boundary

• LV_OBJ_FLAG_FLEX_IN_NEW_TRACK Start a new flex track on this item

• LV_OBJ_FLAG_LAYOUT_1 Custom flag, free to use by layouts

• LV_OBJ_FLAG_LAYOUT_2 Custom flag, free to use by layouts

• LV_OBJ_FLAG_WIDGET_1 Custom flag, free to use by widget

• LV_OBJ_FLAG_WIDGET_2 Custom flag, free to use by widget

• LV_OBJ_FLAG_USER_1 Custom flag, free to use by user

• LV_OBJ_FLAG_USER_2 Custom flag, free to use by user

• LV_OBJ_FLAG_USER_3 Custom flag, free to use by user

• LV_OBJ_FLAG_USER_4 Custom flag, free to use by user

Some examples:

/*Hide on object*/lv_obj_add_flag(obj, LV_OBJ_FLAG_HIDDEN);/*Make an object non-clickable*/lv_obj_remove_flag(obj, LV_OBJ_FLAG_CLICKABLE);

Groups

Read the Input devices overview to learn moreabout Groups.

Objects are added to a group with lv_group_add_obj(group, obj),and you can use lv_obj_get_group(obj) to see which group an objectbelongs to.

lv_obj_is_focused(obj) returns if the object is currently focused onits group or not. If the object is not added to a group, false willbe returned.

Extended click area

By default, the objects can be clicked only within their bounding area.However, this can be extended withlv_obj_set_ext_click_area(obj, size).

Base objects with custom styles

#include "../../lv_examples.h"#if LV_BUILD_EXAMPLESvoid lv_example_obj_1(void){ lv_obj_t * obj1; obj1 = lv_obj_create(lv_screen_active()); lv_obj_set_size(obj1, 100, 50); lv_obj_align(obj1, LV_ALIGN_CENTER, -60, -30); static lv_style_t style_shadow; lv_style_init(&style_shadow); lv_style_set_shadow_width(&style_shadow, 10); lv_style_set_shadow_spread(&style_shadow, 5); lv_style_set_shadow_color(&style_shadow, lv_palette_main(LV_PALETTE_BLUE)); lv_obj_t * obj2; obj2 = lv_obj_create(lv_screen_active()); lv_obj_add_style(obj2, &style_shadow, 0); lv_obj_align(obj2, LV_ALIGN_CENTER, 60, 30);}#endif

Make an object draggable

#include "../../lv_examples.h"#if LV_BUILD_EXAMPLESstatic void drag_event_handler(lv_event_t * e){ lv_obj_t * obj = lv_event_get_target(e); lv_indev_t * indev = lv_indev_active(); if(indev == NULL) return; lv_point_t vect; lv_indev_get_vect(indev, &vect); int32_t x = lv_obj_get_x_aligned(obj) + vect.x; int32_t y = lv_obj_get_y_aligned(obj) + vect.y; lv_obj_set_pos(obj, x, y);}/** * Make an object draggable. */void lv_example_obj_2(void){ lv_obj_t * obj; obj = lv_obj_create(lv_screen_active()); lv_obj_set_size(obj, 150, 100); lv_obj_add_event_cb(obj, drag_event_handler, LV_EVENT_PRESSING, NULL); lv_obj_t * label = lv_label_create(obj); lv_label_set_text(label, "Drag me"); lv_obj_center(label);}#endif