1.. _layers:
2
3======
4Layers
5======
6
7When the term "layer" is used in LVGL documentation, it may refer to one of several
8things:
9
101.  for Widgets, the :ref:`layers_creation` creates a natural layering of Widgets;
112.  in the context of pixel rendering (drawing), there are :ref:`draw_layers`;
123.  permanent :ref:`screen_layers` are part of each :ref:`display` object, and
13    are covered :ref:`here <screen_layers>`
14
15#1 and #2 are covered below.
16
17
18
19.. _layers_creation:
20
21Order of Creation
22*****************
23
24By default, LVGL draws new Widgets on top of old Widgets.
25
26For example, assume we add a button to a parent Widget named button1 and
27then another button named button2. Then button1 (along with its child
28Widget(s)) will be in the background and can be covered by button2 and
29its children.
30
31.. image:: /misc/layers.png
32
33.. code-block:: c
34
35   /* Create a screen */
36   lv_obj_t * scr = lv_obj_create(NULL);
37   lv_screen_load(scr);          /* Load the screen */
38
39   /* Create 2 buttons */
40   lv_obj_t * btn1 = lv_button_create(scr);     /* Create the first button on the screen */
41   lv_obj_set_pos(btn1, 60, 40);                      /* Set the position of the first button */
42
43   lv_obj_t * btn2 = lv_button_create(scr);     /* Create the second button on the screen */
44   lv_obj_set_pos(btn2, 180, 80);                     /* Set the position of the second button */
45
46   /* Add labels to the buttons */
47   lv_obj_t * label1 = lv_label_create(btn1);   /* Create a label on the first button */
48   lv_label_set_text(label1, "Button 1");             /* Set the text of the label */
49
50   lv_obj_t * label2 = lv_label_create(btn2);   /* Create a label on the second button */
51   lv_label_set_text(label2, "Button 2");             /* Set the text of the label */
52
53   /* Delete the second label */
54   lv_obj_delete(label2);
55
56.. _layers_order:
57
58Changing Order
59--------------
60
61There are four explicit ways to bring a Widget to the foreground:
62
63- Use :cpp:expr:`lv_obj_move_foreground(widget)` to bring a Widget to the foreground.
64  Similarly, use :cpp:expr:`lv_obj_move_background(widget)` to move it to the background.
65- Use :cpp:expr:`lv_obj_move_to_index(widget, idx)` to move a Widget to a given index in the order of children.
66
67  - ``0``: background
68  - ``child_num - 1``: foreground
69  - ``< 0``: count from the top, to move forward (up): :cpp:expr:`lv_obj_move_to_index(widget, lv_obj_get_index(widget) - 1)`
70
71- Use :cpp:expr:`lv_obj_swap(widget1, widget2)` to swap the relative layer position of two Widgets.
72- When :cpp:expr:`lv_obj_set_parent(widget, new_parent)` is used, ``widget`` will be on the foreground of ``new_parent``.
73
74
75.. _draw_layers:
76
77Draw Layers
78***********
79
80Some style properties cause LVGL to allocate a buffer and render a Widget and its
81children there first.  Later that layer will be merged to the screen or its parent
82layer after applying some transformations or other modifications.
83
84Simple Layer
85------------
86
87The following style properties trigger the creation of a "Simple Layer":
88
89- ``opa_layered``
90- ``bitmap_mask_src``
91- ``blend_mode``
92
93In this case the Widget will be sliced into ``LV_DRAW_SW_LAYER_SIMPLE_BUF_SIZE``
94sized chunks.
95
96If there is no memory for a new chunk, LVGL will try allocating the layer after
97another chunk is rendered and freed.
98
99Transformed Layer
100-----------------
101
102When the widget is transformed a larger part of the Widget needs to rendered to
103provide enough data for transformation.  LVGL tries to render as small area of the
104widget as possible, but due to the nature of transformations no slicing is possible
105in this case.
106
107The following style properties trigger the creation of a "Transform Layer":
108
109- ``transform_scale_x``
110- ``transform_scale_y``
111- ``transform_skew_x``
112- ``transform_skew_y``
113- ``transform_rotate``
114
115Clip corner
116-----------
117
118The ``clip_corner`` style property also causes LVGL to create a 2 layers with radius
119height for the top and bottom parts of the Widget.
120
121
122.. _layers_api:
123
124API
125***
126