Hierarchical layout system.
Layers are “visual objects”. They are the objects that can be displayed on the screen, for example a box that contains text or a box that contains an image. Each layer stores the information about its state necessary to (re)draw the object it represents and uses graphics routines along with this state to draw itself when asked. Multiple layers can be arranged into a tree. This enables ordering (front to back), layout, hierarchy and relative positioning.
Please refer to Building User Interfaces chapter in Pebble Developer Guide
(chapter "Layers") for a conceptual overview of Layers and relevant code examples.
The Modules list contains "subclasses" of Layer. The listed types can be safely type-casted to Layer
(or Layer *
in case of a pointer). Therefore the layer_...
functions can be used with the datastructures of these "subclasses".
For example, the following is legal:
TextLayer *text_layer;
...
layer_set_hidden((Layer *)text_layer, true);
void layer_add_child |
( |
Layer * |
parent, |
|
|
Layer * |
child |
|
) |
| |
Adds the child layer to a given parent layer, making it appear in front of its parent and in front of any existing child layers of the parent. If the child layer was already part of a layer hierarchy, it will be removed from its old parent first. If added successfully, the parent (and children) will be marked dirty automatically.
- Parameters
-
parent | The layer to which to add the child layer |
child | The layer to add to the parent layer |
Layer* layer_create |
( |
GRect |
frame | ) |
|
Creates a layer on the heap and sets its frame and bounds. Default values:
bounds
: origin (0, 0) and a size equal to the frame that is passed in.
clips
: true
hidden
: false
update_proc
: NULL
(draws nothing) - Parameters
-
frame | The frame at which the layer should be initialized. |
- See Also
- layer_set_frame()
-
layer_set_bounds()
- Returns
- A pointer to the layer.
NULL
if the layer could not be created
Layer* layer_create_with_data |
( |
GRect |
frame, |
|
|
size_t |
data_size |
|
) |
| |
Creates a layer on the heap with extra space for callback data, and set its frame andbounds. Default values:
bounds
: origin (0, 0) and a size equal to the frame that is passed in.
clips
: true
hidden
: false
update_proc
: NULL
(draws nothing) - Parameters
-
frame | The frame at which the layer should be initialized. |
data_size | The size (in bytes) of memory to allocate for callback data. |
- See Also
- layer_create()
-
layer_set_frame()
-
layer_set_bounds()
- Returns
- A pointer to the layer.
NULL
if the layer could not be created
void layer_destroy |
( |
Layer * |
layer | ) |
|
Destroys a layer previously created by layer_create.
GRect layer_get_bounds |
( |
const Layer * |
layer | ) |
|
Gets the bounds of the layer.
- Parameters
-
layer | The layer for which to get the bounds |
- Returns
- The bounds of the layer
- See Also
- layer_set_bounds
bool layer_get_clips |
( |
const Layer * |
layer | ) |
|
Gets whether clipping is enabled for the layer. If enabled, whatever the layer and its children will draw using their .update_proc
callbacks, will be clipped by the this layer's frame.
- Parameters
-
layer | The layer for which to get the clipping property |
- Returns
- True if clipping is enabled for the layer, false if clipping is not enabled for the layer.
void* layer_get_data |
( |
const Layer * |
layer | ) |
|
Gets the data from a layer that has been created with an extra data region.
- Parameters
-
layer | The layer to get the data region from. |
- Returns
- A void pointer to the data region.
GRect layer_get_frame |
( |
const Layer * |
layer | ) |
|
Gets the frame of the layer, which is it's bounding box relative to the coordinate system of its parent layer. If the frame has changed, layer_mark_dirty() will be called automatically.
- Parameters
-
layer | The layer for which to get the frame |
- Returns
- The frame of the layer
- See Also
- layer_set_frame
bool layer_get_hidden |
( |
const Layer * |
layer | ) |
|
Gets the visibility of the layer.
- Parameters
-
layer | The layer for which to get the visibility |
- Returns
- True if the layer is hidden, false if it is not hidden.
struct Window* layer_get_window |
( |
const Layer * |
layer | ) |
|
Gets the window that the layer is currently attached to.
- Parameters
-
layer | The layer for which to get the window |
- Returns
- The window that this layer is currently attached to, or
NULL
if it has not been added to a window's layer hierarchy.
- See Also
- window_get_root_layer()
-
layer_add_child()
void layer_insert_above_sibling |
( |
Layer * |
layer_to_insert, |
|
|
Layer * |
above_sibling_layer |
|
) |
| |
Inserts the layer as a sibling in front of another layer. The above_layer has to be a child of a parent layer, otherwise this function will be a noop. If inserted successfully, the parent (and children) will be marked dirty automatically.
- Parameters
-
layer_to_insert | The layer to insert into the hierarchy |
above_sibling_layer | The layer that will be used as the sibling layer below which the insertion will take place |
void layer_insert_below_sibling |
( |
Layer * |
layer_to_insert, |
|
|
Layer * |
below_sibling_layer |
|
) |
| |
Inserts the layer as a sibling behind another layer. The below_layer has to be a child of a parent layer, otherwise this function will be a noop. If inserted successfully, the parent (and children) will be marked dirty automatically.
- Parameters
-
layer_to_insert | The layer to insert into the hierarchy |
below_sibling_layer | The layer that will be used as the sibling layer above which the insertion will take place |
void layer_mark_dirty |
( |
Layer * |
layer | ) |
|
Marks the complete layer as "dirty", awaiting to be asked by the system to redraw itself. Typically, this function is called whenever state has changed that affects what the layer is displaying.
- The layer's
.update_proc
will not be called before this function returns, but will be called asynchronously, shortly.
- Internally, a call to this function will schedule a re-render of the window that the layer belongs to. In effect, all layers in that window's layer hierarchy will be asked to redraw.
- If an earlier re-render request is still pending, this function is a no-op.
- Parameters
-
layer | The layer to mark dirty |
void layer_remove_child_layers |
( |
Layer * |
parent | ) |
|
Removes child layers from given layer If removed successfully, the child's parent layer will be marked dirty automatically.
- Parameters
-
parent | The layer from which to remove all child layers |
void layer_remove_from_parent |
( |
Layer * |
child | ) |
|
Removes the layer from its current parent layer If removed successfully, the child's parent layer will be marked dirty automatically.
- Parameters
-
void layer_set_bounds |
( |
Layer * |
layer, |
|
|
GRect |
bounds |
|
) |
| |
Sets the bounds of the layer, which is it's bounding box relative to its frame. If the bounds has changed, layer_mark_dirty() will be called automatically.
- Parameters
-
layer | The layer for which to set the bounds |
bounds | The new bounds |
- See Also
- layer_set_frame()
void layer_set_clips |
( |
Layer * |
layer, |
|
|
bool |
clips |
|
) |
| |
Sets whether clipping is enabled for the layer. If enabled, whatever the layer and its children will draw using their .update_proc
callbacks, will be clipped by the this layer's frame. If the clipping has changed, layer_mark_dirty() will be called automatically.
- Parameters
-
layer | The layer for which to set the clipping property |
clips | Supply true to make the layer clip to its frame, or false to make it non-clipping. |
void layer_set_frame |
( |
Layer * |
layer, |
|
|
GRect |
frame |
|
) |
| |
Sets the frame of the layer, which is it's bounding box relative to the coordinate system of its parent layer. The size of the layer's bounds will be extended automatically, so that the bounds cover the new frame.
- Parameters
-
layer | The layer for which to set the frame |
frame | The new frame |
- See Also
- layer_set_bounds()
void layer_set_hidden |
( |
Layer * |
layer, |
|
|
bool |
hidden |
|
) |
| |
Sets the visibility of the layer. If the visibility has changed, layer_mark_dirty() will be called automatically on the parent layer.
- Parameters
-
layer | The layer for which to set the visibility |
hidden | Supply true to make the layer hidden, or false to make it non-hidden. |
Sets the layer's render function. The system will call the update_proc
automatically when the layer needs to redraw itself, see also layer_mark_dirty().
- Parameters
-
layer | Pointer to the layer structure. |
update_proc | Pointer to the function that will be called when the layer needs to be rendered. Typically, one performs a series of drawing commands in the implementation of the update_proc , see Drawing Primitives, Drawing Paths and Drawing Text. |
typedef void(* LayerUpdateProc)(struct Layer *layer, GContext *ctx) |
Function signature for a Layer's render callback (the name of the type is derived from the words 'update procedure'). The system will call the .update_proc
callback whenever the Layer needs to be rendered.
- Parameters
-
layer | The layer that needs to be rendered |
ctx | The destination graphics context to draw into |
- See Also
- Graphics
-
layer_set_update_proc()