acid-drop

- Hacking the planet from a LilyGo T-Deck using custom firmware
git clone git://git.acid.vegas/acid-drop.git
Log | Files | Refs | Archive | README | LICENSE

obj.md (9260B)

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