1# Base object (lv_obj)
2
3## Overview
4
5The 'Base Object' implements the basic properties of widgets on a screen, such as:
6- coordinates
7- parent object
8- children
9- contains the styles
10- attributes like *Clickable*, *Scrollable*, etc.
11
12In object-oriented thinking, it is the base class from which all other objects in LVGL are inherited.
13
14The functions and functionalities of the Base object can be used with other widgets too. For example `lv_obj_set_width(slider, 100)`
15
16The Base object can be directly used as a simple widget: it's nothing more than a rectangle. In HTML terms, think of it as a `<div>`.
17
18### Coordinates
19
20Only a small subset of coordinate settings is described here. To see all the features of LVGL (padding, coordinates in styles, layouts, etc) visit the [Coordinates](/overview/coords) page.
21
22#### Size
23The 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)`.
24
25#### Position
26You can set the position relative to the parent with `lv_obj_set_x(obj, new_x)` and `lv_obj_set_y(obj, new_y)`, or both axes at the same time with `lv_obj_set_pos(obj, new_x, new_y)`.
27
28#### Alignment
29You can align the object on its parent with `lv_obj_set_align(obj, LV_ALIGN_...)`. After this every x and y setting will be relative to the set alignment mode.
30For example, this will shift the object by 10;20 px from the center of its parent:
31```c
32lv_obj_set_align(obj, LV_ALIGN_CENTER);
33lv_obj_set_pos(obj, 10, 20);
34
35//Or in one function
36lv_obj_align(obj, LV_ALIGN_CENTER, 10, 20);
37```
38
39To align one object to another use: `lv_obj_align_to(obj_to_align, obj_referece, LV_ALIGN_..., x, y)`
40
41For example, to align a text below an image: `lv_obj_align_to(text, image, LV_ALIGN_OUT_BOTTOM_MID, 0, 10)`.
42
43The following align types exist:
44![](/misc/align.png "Alignment types in LVGL")
45
46
47### Parents and children
48You 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)`.
49
50To get a specific child of a parent use `lv_obj_get_child(parent, idx)`. Some examples for `idx`:
51- `0` get the child created first
52- `1` get the child created second
53- `-1` get the child created last
54
55The children can be iterated lke this:
56```c
57uint32_t i;
58for(i = 0; i < lv_obj_get_child_cnt(parent); i++) {
59  lv_obj_t * child = lv_obj_get_child(parent, i);
60  /*Do something with child*/
61}
62```
63
64`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.
65
66You 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)`.
67
68You can change the index of an object in its parent using  `lv_obj_move_to_index(obj, index)`.
69
70You can swap the position of two objects with `lv_obj_swap(obj1, obj2)`.
71
72### Display and Screens
73
74At the highest level of the LVGL object hierarchy is the *display* which represents the driver for a display device (physical display or simulator). A display can have one or more screens associated with it. Each screen contains a hierarchy of objects for graphical widgets representing a layout that covers the entire display.
75
76When you have created a screen like `lv_obj_t * screen = lv_obj_create(NULL)`, you can make it active with `lv_scr_load(screen)`. The `lv_scr_act()` function gives you a pointer to the active screen.
77
78If you have multiple displays, it's important to know that the screen functions operate on the most recently created display or the one explicitly selected with `lv_disp_set_default`.
79
80To get an object's screen use the `lv_obj_get_screen(obj)` function.
81
82### Events
83
84To set an event callback for an object, use `lv_obj_add_event_cb(obj, event_cb, LV_EVENT_..., user_data)`,
85
86To manually send an event to an object, use `lv_event_send(obj, LV_EVENT_..., param)`
87
88Read the [Event overview](/overview/event) to learn more about events.
89
90
91### Styles
92Be sure to read the [Style overview](/overview/style). Here only the most essential functions are described.
93
94A new style can be added to an object with the `lv_obj_add_style(obj, &new_style, selector)` function.
95`selector` is an ORed combination of part and state(s). E.g. `LV_PART_SCROLLBAR | LV_STATE_PRESSED`.
96
97The base objects use `LV_PART_MAIN` style properties and `LV_PART_SCROLLBAR` with the typical background style properties.
98
99
100### Flags
101There are some attributes which can be enabled/disabled by `lv_obj_add/clear_flag(obj, LV_OBJ_FLAG_...)`:
102
103- `LV_OBJ_FLAG_HIDDEN`  Make the object hidden. (Like it wasn't there at all)
104- `LV_OBJ_FLAG_CLICKABLE`  Make the object clickable by input devices
105- `LV_OBJ_FLAG_CLICK_FOCUSABLE`  Add focused state to the object when clicked
106- `LV_OBJ_FLAG_CHECKABLE`  Toggle checked state when the object is clicked
107- `LV_OBJ_FLAG_SCROLLABLE`  Make the object scrollable
108- `LV_OBJ_FLAG_SCROLL_ELASTIC`  Allow scrolling inside but with slower speed
109- `LV_OBJ_FLAG_SCROLL_MOMENTUM`  Make the object scroll further when "thrown"
110- `LV_OBJ_FLAG_SCROLL_ONE` Allow scrolling only one snappable children
111- `LV_OBJ_FLAG_SCROLL_CHAIN_HOR`  Allow propagating the horizontal scroll to a parent
112- `LV_OBJ_FLAG_SCROLL_CHAIN_VER`  Allow propagating the vertical scroll to a parent
113- `LV_OBJ_FLAG_SCROLL_CHAIN`  Simple packaging for (`LV_OBJ_FLAG_SCROLL_CHAIN_HOR | LV_OBJ_FLAG_SCROLL_CHAIN_VER`)
114- `LV_OBJ_FLAG_SCROLL_ON_FOCUS`  Automatically scroll object to make it visible when focused
115- `LV_OBJ_FLAG_SCROLL_WITH_ARROW`  Allow scrolling the focused object with arrow keys
116- `LV_OBJ_FLAG_SNAPPABLE` If scroll snap is enabled on the parent it can snap to this object
117- `LV_OBJ_FLAG_PRESS_LOCK` Keep the object pressed even if the press slid from the object
118- `LV_OBJ_FLAG_EVENT_BUBBLE` Propagate the events to the parent too
119- `LV_OBJ_FLAG_GESTURE_BUBBLE` Propagate the gestures to the parent
120- `LV_OBJ_FLAG_ADV_HITTEST` Allow performing more accurate hit (click) test. E.g. accounting for rounded corners
121- `LV_OBJ_FLAG_IGNORE_LAYOUT` Make the object positionable by the layouts
122- `LV_OBJ_FLAG_FLOATING` Do not scroll the object when the parent scrolls and ignore layout
123- `LV_OBJ_FLAG_OVERFLOW_VISIBLE` Do not clip the children's content to the parent's boundary
124
125- `LV_OBJ_FLAG_LAYOUT_1`  Custom flag, free to use by layouts
126- `LV_OBJ_FLAG_LAYOUT_2`  Custom flag, free to use by layouts
127
128- `LV_OBJ_FLAG_WIDGET_1`  Custom flag, free to use by widget
129- `LV_OBJ_FLAG_WIDGET_2`  Custom flag, free to use by widget
130
131- `LV_OBJ_FLAG_USER_1`  Custom flag, free to use by user
132- `LV_OBJ_FLAG_USER_2`  Custom flag, free to use by user
133- `LV_OBJ_FLAG_USER_3`  Custom flag, free to use by user
134- `LV_OBJ_FLAG_USER_4`  Custom flag, free to use by user
135
136Some examples:
137```c
138/*Hide on object*/
139lv_obj_add_flag(obj, LV_OBJ_FLAG_HIDDEN);
140
141/*Make an object non-clickable*/
142lv_obj_clear_flag(obj, LV_OBJ_FLAG_CLICKABLE);
143```
144
145### Groups
146
147Read the [Input devices overview](/overview/indev) to learn more about *Groups*.
148
149Objects 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 object belongs to.
150
151`lv_obj_is_focused(obj)` returns if the object is currently focused on its group or not. If the object is not added to a group, `false` will be returned.
152
153
154### Extended click area
155By default, the objects can be clicked only within their bounding area. However, this can be extended with `lv_obj_set_ext_click_area(obj, size)`.
156
157## Events
158- `LV_EVENT_VALUE_CHANGED` when the `LV_OBJ_FLAG_CHECKABLE` flag is enabled and the object clicked (on transition to/from the checked state)
159- `LV_EVENT_DRAW_PART_BEGIN` and `LV_EVENT_DRAW_PART_END` is sent for the following types:
160    - `LV_OBJ_DRAW_PART_RECTANGLE` The main rectangle
161       - `part`: `LV_PART_MAIN`
162       - `rect_dsc`
163       - `draw_area`: the area of the rectangle
164    - `LV_OBJ_DRAW_PART_BORDER_POST`  The border if the `border_post` style property is `true`
165       - `part`: `LV_PART_MAIN`
166       - `rect_dsc`
167       - `draw_area`: the area of the rectangle
168    - `LV_OBJ_DRAW_PART_SCROLLBAR` the scrollbars
169       - `part`: `LV_PART_SCROLLBAR`
170       - `rect_dsc`
171       - `draw_area`: the area of the rectangle
172
173Learn more about [Events](/overview/event).
174
175## Keys
176If `LV_OBJ_FLAG_CHECKABLE` is enabled, `LV_KEY_RIGHT` and `LV_KEY_UP` make the object checked, and `LV_KEY_LEFT` and `LV_KEY_DOWN` make it unchecked.
177
178If `LV_OBJ_FLAG_SCROLLABLE` is enabled, but the object is not editable (as declared by the widget class), the arrow keys (`LV_KEY_UP`, `LV_KEY_DOWN`, `LV_KEY_LEFT`, `LV_KEY_RIGHT`) scroll the object. If the object can only scroll vertically, `LV_KEY_LEFT` and `LV_KEY_RIGHT` will scroll up/down instead, making it compatible with an encoder input device. See [Input devices overview](/overview/indev) for more on encoder behaviors and the edit mode.
179
180
181Learn more about [Keys](/overview/indev).
182
183## Example
184
185```eval_rst
186
187.. include:: ../../examples/widgets/obj/index.rst
188
189```
190
191## API
192
193```eval_rst
194
195.. doxygenfile:: lv_obj.h
196  :project: lvgl
197
198```
199