mirror of
https://github.com/lvgl/lvgl.git
synced 2024-11-27 11:43:43 +08:00
291 lines
10 KiB
ReStructuredText
291 lines
10 KiB
ReStructuredText
.. _lv_obj:
|
|
|
|
====================
|
|
Base object (lv_obj)
|
|
====================
|
|
|
|
Overview
|
|
********
|
|
|
|
The 'Base Object' implements the basic properties of widgets on a
|
|
screen, such as:
|
|
|
|
- coordinates
|
|
- parent object
|
|
- children
|
|
- contains the styles
|
|
- attributes like *Clickable*, *Scrollable*, etc.
|
|
|
|
In object-oriented thinking, it is the base class from which all other
|
|
objects in LVGL are inherited.
|
|
|
|
The functions and functionalities of the Base object can be used with
|
|
other widgets too. For example :cpp:expr:`lv_obj_set_width(slider, 100)`
|
|
|
|
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>``.
|
|
|
|
.. _lv_obj_coordinates:
|
|
|
|
Coordinates
|
|
-----------
|
|
|
|
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 :ref:`Coordinates <coord>` page.
|
|
|
|
.. _lv_obj_size:
|
|
|
|
Size
|
|
^^^^
|
|
|
|
The object size can be modified on individual axes with
|
|
:cpp:expr:`lv_obj_set_width(obj, new_width)` and
|
|
:cpp:expr:`lv_obj_set_height(obj, new_height)`, or both axes can be modified at
|
|
the same time with :cpp:expr:`lv_obj_set_size(obj, new_width, new_height)`.
|
|
|
|
.. _lv_obj_position:
|
|
|
|
Position
|
|
^^^^^^^^
|
|
|
|
You can set the position relative to the parent with
|
|
:cpp:expr:`lv_obj_set_x(obj, new_x)` and :cpp:expr:`lv_obj_set_y(obj, new_y)`, or both
|
|
axes at the same time with :cpp:expr:`lv_obj_set_pos(obj, new_x, new_y)`.
|
|
|
|
.. _lv_obj_alignment:
|
|
|
|
Alignment
|
|
^^^^^^^^^
|
|
|
|
You can align the object on its parent with
|
|
:cpp:expr:`lv_obj_set_align(obj, LV_ALIGN_...)`. After this every x and y
|
|
setting will be relative to the set alignment mode. For example, this
|
|
will shift the object by 10;20 px from the center of its parent:
|
|
|
|
.. code:: c
|
|
|
|
lv_obj_set_align(obj, LV_ALIGN_CENTER);
|
|
lv_obj_set_pos(obj, 10, 20);
|
|
|
|
//Or in one function
|
|
lv_obj_align(obj, LV_ALIGN_CENTER, 10, 20);
|
|
|
|
To align one object to another use:
|
|
:cpp:expr:`lv_obj_align_to(obj_to_align, obj_reference, LV_ALIGN_..., x, y)`
|
|
|
|
For example, to align a text below an image:
|
|
:cpp:expr:`lv_obj_align_to(text, image, LV_ALIGN_OUT_BOTTOM_MID, 0, 10)`.
|
|
|
|
The following align types exist: |image1|
|
|
|
|
.. _lv_obj_parents_and_children:
|
|
|
|
Parents and children
|
|
--------------------
|
|
|
|
You can set a new parent for an object with
|
|
:cpp:expr:`lv_obj_set_parent(obj, new_parent)`. To get the current parent, use
|
|
:cpp:expr:`lv_obj_get_parent(obj)`.
|
|
|
|
To get a specific child of a parent use :cpp:expr:`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:
|
|
|
|
.. code:: c
|
|
|
|
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*/
|
|
}
|
|
|
|
:cpp:expr:`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 background
|
|
with :cpp:expr:`lv_obj_move_foreground(obj)` and
|
|
:cpp:expr:`lv_obj_move_background(obj)`.
|
|
|
|
You can change the index of an object in its parent using
|
|
:cpp:expr:`lv_obj_move_to_index(obj, index)`.
|
|
|
|
You can swap the position of two objects with
|
|
:cpp:expr:`lv_obj_swap(obj1, obj2)`.
|
|
|
|
.. _lv_obj_display_and_screens:
|
|
|
|
Display and Screens
|
|
-------------------
|
|
|
|
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.
|
|
|
|
When you have created a screen like
|
|
``lv_obj_t * screen = lv_obj_create(NULL)``, you can make it active with
|
|
:cpp:expr:`lv_screen_load(screen)`. The :cpp:func:`lv_screen_active` function gives you a
|
|
pointer to the active screen.
|
|
|
|
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 :cpp:func:`lv_display_set_default`.
|
|
|
|
To get an object's screen use the :cpp:expr:`lv_obj_get_screen(obj)` function.
|
|
|
|
.. _lv_obj_overview_events:
|
|
|
|
Events
|
|
------
|
|
|
|
To set an event callback for an object, use
|
|
:cpp:expr:`lv_obj_add_event_cb(obj, event_cb, LV_EVENT_..., user_data)`,
|
|
|
|
To manually send an event to an object, use
|
|
:cpp:expr:`lv_event_send(obj, LV_EVENT_..., param)`
|
|
|
|
Read the :ref:`Event overview <events>` to learn more about
|
|
events.
|
|
|
|
.. _lv_obj_styles:
|
|
|
|
Styles
|
|
------
|
|
|
|
Be sure to read the :ref:`Style overview <styles>`. Here only the
|
|
most essential functions are described.
|
|
|
|
A new style can be added to an object with the
|
|
:cpp:expr:`lv_obj_add_style(obj, &new_style, selector)` function. ``selector``
|
|
is an ORed combination of part and state(s). E.g.
|
|
:cpp:expr:`LV_PART_SCROLLBAR | LV_STATE_PRESSED`.
|
|
|
|
The base objects use :cpp:enumerator:`LV_PART_MAIN` style properties and
|
|
:cpp:enumerator:`LV_PART_SCROLLBAR` with the typical background style properties.
|
|
|
|
.. _lv_obj_flags:
|
|
|
|
Flags
|
|
-----
|
|
|
|
There are some attributes which can be enabled/disabled by
|
|
``lv_obj_add/remove_flag(obj, LV_OBJ_FLAG_...)`` and ``lv_obj_set_flag(obj, LV_OBJ_FLAG_..., true/false)``
|
|
|
|
- :cpp:enumerator:`LV_OBJ_FLAG_HIDDEN` Make the object hidden. (Like it wasn't there at all)
|
|
- :cpp:enumerator:`LV_OBJ_FLAG_CLICKABLE` Make the object clickable by input devices
|
|
- :cpp:enumerator:`LV_OBJ_FLAG_CLICK_FOCUSABLE` Add focused state to the object when clicked
|
|
- :cpp:enumerator:`LV_OBJ_FLAG_CHECKABLE` Toggle checked state when the object is clicked
|
|
- :cpp:enumerator:`LV_OBJ_FLAG_SCROLLABLE` Make the object scrollable
|
|
- :cpp:enumerator:`LV_OBJ_FLAG_SCROLL_ELASTIC` Allow scrolling inside but with slower speed
|
|
- :cpp:enumerator:`LV_OBJ_FLAG_SCROLL_MOMENTUM` Make the object scroll further when "thrown"
|
|
- :cpp:enumerator:`LV_OBJ_FLAG_SCROLL_ONE` Allow scrolling only one snappable children
|
|
- :cpp:enumerator:`LV_OBJ_FLAG_SCROLL_CHAIN_HOR` Allow propagating the horizontal scroll to a parent
|
|
- :cpp:enumerator:`LV_OBJ_FLAG_SCROLL_CHAIN_VER` Allow propagating the vertical scroll to a parent
|
|
- :cpp:enumerator:`LV_OBJ_FLAG_SCROLL_CHAIN` Simple packaging for (:cpp:expr:`LV_OBJ_FLAG_SCROLL_CHAIN_HOR | LV_OBJ_FLAG_SCROLL_CHAIN_VER`)
|
|
- :cpp:enumerator:`LV_OBJ_FLAG_SCROLL_ON_FOCUS` Automatically scroll object to make it visible when focused
|
|
- :cpp:enumerator:`LV_OBJ_FLAG_SCROLL_WITH_ARROW` Allow scrolling the focused object with arrow keys
|
|
- :cpp:enumerator:`LV_OBJ_FLAG_SNAPPABLE` If scroll snap is enabled on the parent it can snap to this object
|
|
- :cpp:enumerator:`LV_OBJ_FLAG_PRESS_LOCK` Keep the object pressed even if the press slid from the object
|
|
- :cpp:enumerator:`LV_OBJ_FLAG_EVENT_BUBBLE` Propagate the events to the parent too
|
|
- :cpp:enumerator:`LV_OBJ_FLAG_GESTURE_BUBBLE` Propagate the gestures to the parent
|
|
- :cpp:enumerator:`LV_OBJ_FLAG_ADV_HITTEST` Allow performing more accurate hit (click) test. E.g. accounting for rounded corners
|
|
- :cpp:enumerator:`LV_OBJ_FLAG_IGNORE_LAYOUT` Make the object positionable by the layouts
|
|
- :cpp:enumerator:`LV_OBJ_FLAG_FLOATING` Do not scroll the object when the parent scrolls and ignore layout
|
|
- :cpp:enumerator:`LV_OBJ_FLAG_SEND_DRAW_TASK_EVENTS` Enable sending ``LV_EVENT_DRAW_TASK_ADDED`` events
|
|
- :cpp:enumerator:`LV_OBJ_FLAG_OVERFLOW_VISIBLE` Do not clip the children's content to the parent's boundary
|
|
- :cpp:enumerator:`LV_OBJ_FLAG_FLEX_IN_NEW_TRACK` Start a new flex track on this item
|
|
- :cpp:enumerator:`LV_OBJ_FLAG_LAYOUT_1` Custom flag, free to use by layouts
|
|
- :cpp:enumerator:`LV_OBJ_FLAG_LAYOUT_2` Custom flag, free to use by layouts
|
|
- :cpp:enumerator:`LV_OBJ_FLAG_WIDGET_1` Custom flag, free to use by widget
|
|
- :cpp:enumerator:`LV_OBJ_FLAG_WIDGET_2` Custom flag, free to use by widget
|
|
- :cpp:enumerator:`LV_OBJ_FLAG_USER_1` Custom flag, free to use by user
|
|
- :cpp:enumerator:`LV_OBJ_FLAG_USER_2` Custom flag, free to use by user
|
|
- :cpp:enumerator:`LV_OBJ_FLAG_USER_3` Custom flag, free to use by user
|
|
- :cpp:enumerator:`LV_OBJ_FLAG_USER_4` Custom flag, free to use by user
|
|
|
|
Some examples:
|
|
|
|
.. code:: c
|
|
|
|
/*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);
|
|
|
|
.. _lv_obj_groups:
|
|
|
|
Groups
|
|
------
|
|
|
|
Read the :ref:`Input devices overview <indev>` to learn more
|
|
about *Groups*.
|
|
|
|
Objects are added to a *group* with :cpp:expr:`lv_group_add_obj(group, obj)`,
|
|
and you can use :cpp:expr:`lv_obj_get_group(obj)` to see which group an object
|
|
belongs to.
|
|
|
|
:cpp:expr:`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.
|
|
|
|
.. _lv_obj_extended_click_area:
|
|
|
|
Extended click area
|
|
-------------------
|
|
|
|
By default, the objects can be clicked only within their bounding area.
|
|
However, this can be extended with
|
|
:cpp:expr:`lv_obj_set_ext_click_area(obj, size)`.
|
|
|
|
.. _events-1:
|
|
|
|
.. _lv_obj_events:
|
|
|
|
Events
|
|
******
|
|
|
|
- :cpp:enumerator:`LV_EVENT_VALUE_CHANGED` when the :cpp:enumerator:`LV_OBJ_FLAG_CHECKABLE` flag is
|
|
enabled and the object clicked (on transition to/from the checked state)
|
|
|
|
Learn more about :ref:`events`.
|
|
|
|
.. _lv_obj_keys:
|
|
|
|
Keys
|
|
****
|
|
|
|
If :cpp:enumerator:`LV_OBJ_FLAG_CHECKABLE` is enabled, :cpp:enumerator:`LV_KEY_RIGHT` and
|
|
:cpp:enumerator:`LV_KEY_UP` make the object checked, and :cpp:enumerator:`LV_KEY_LEFT` and
|
|
:cpp:enumerator:`LV_KEY_DOWN` make it unchecked.
|
|
|
|
If :cpp:enumerator:`LV_OBJ_FLAG_SCROLLABLE` is enabled, but the object is not editable
|
|
(as declared by the widget class), the arrow keys (:cpp:enumerator:`LV_KEY_UP`,
|
|
:cpp:enumerator:`LV_KEY_DOWN`, :cpp:enumerator:`LV_KEY_LEFT`, :cpp:enumerator:`LV_KEY_RIGHT`) scroll the object.
|
|
If the object can only scroll vertically, :cpp:enumerator:`LV_KEY_LEFT` and
|
|
:cpp:enumerator:`LV_KEY_RIGHT` will scroll up/down instead, making it compatible with
|
|
an encoder input device. See :ref:`Input devices overview <indev>` for
|
|
more on encoder behaviors and the edit mode.
|
|
|
|
Learn more about :ref:`indev_keys`.
|
|
|
|
.. |image1| image:: /misc/align.png
|
|
|
|
.. _lv_obj_example:
|
|
|
|
Example
|
|
*******
|
|
|
|
.. include:: ../examples/widgets/obj/index.rst
|
|
|
|
.. _lv_obj_api:
|
|
|
|
API
|
|
***
|