User interface layers for displaying graphic components.
Layers are objects that can be displayed on a Pebble watchapp window, enabling users to see visual objects, like text or images. Each layer stores the information about its state necessary to draw or redraw the object that it represents and uses graphics routines along with this state to draw itself when asked. Layers can be used to display various graphics.
Layers are the basic building blocks for your application UI. Layers can be nested inside each other. Every window has a root layer which is always the topmost layer. You provide a function that is called to draw the content of the layer when needed; or you can use standard layers that are provided by the system, such as text layer, image layer, menu layer, action bar layer, and so on.
The Pebble layer hierarchy is the list of things that need to be drawn to the screen. Multiple layers can be arranged into a hierarchy. This enables ordering (front to back), layout and hierarchy. Through relative positioning, visual objects that are grouped together by adding them into the same layer can be moved all at once. This means that the child layers will move accordingly. If a parent layer has clipping enabled, all the children will be clipped to the frame of the parent.
Pebble OS provides convenience layers with built-in logic for displaying different graphic components, like text and bitmap layers.
Refer to the User Interface Layers chapter in the Pebble Developer Guides (chapter "Layers") for a conceptual overview of Layers and relevant code examples.
The Modules listed here contain what can be thought of conceptually as subclasses of Layer. The listed types can be safely type-casted to Layer (or Layer * in case of a pointer). The layer_... functions can then be used with the data structures of these subclasses.
For example, the following is legal:
TextLayer *text_layer;
...
layer_set_hidden((Layer *)text_layer, true);
Vertical, bar-shaped control widget on the right edge of the window.
Layer that displays a bitmap image.
Layer that displays a standard list menu. Data is provided using callbacks.
Layer that displays a rotated bitmap image.
Layer that scrolls its contents, animated.
Wrapper around MenuLayer, that uses static data to display a list menu.
Layer that serves as a configurable status bar.
Layer that displays and formats a text string.
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)
The frame at which the layer should be initialized.
A pointer to the layer. NULL if the layer could not be created
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)
The frame at which the layer should be initialized.
The size (in bytes) of memory to allocate for callback data.
A pointer to the layer. NULL if the layer could not be created
Destroys a layer previously created by layer_create.
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.
The layer to mark dirty
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().
Pointer to the layer structure.
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.
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.
The layer for which to set the frame
The new frame
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.
The layer for which to get the frame
The frame of the layer
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.
The layer for which to set the bounds
The new bounds
Gets the bounds of the layer.
The layer for which to get the bounds
The bounds of the layer
Converts a point from the layer's local coordinate system to screen coordinates.
If the layer isn't part of the view hierarchy the result is undefined.
The view whose coordinate system will be used to convert the value to the screen.
A point specified in the local coordinate system (bounds) of the layer.
The point converted to the coordinate system of the screen.
Converts a rectangle from the layer's local coordinate system to screen coordinates.
If the layer isn't part of the view hierarchy the result is undefined.
The view whose coordinate system will be used to convert the value to the screen.
A rectangle specified in the local coordinate system (bounds) of the layer.
The rectangle converted to the coordinate system of the screen.
Gets the window that the layer is currently attached to.
The layer for which to get the window
The window that this layer is currently attached to, or NULL if it has not been added to a window's layer hierarchy.
Removes the layer from its current parent layer If removed successfully, the child's parent layer will be marked dirty automatically.
The layer to remove
Removes child layers from given layer If removed successfully, the child's parent layer will be marked dirty automatically.
The layer from which to remove all child layers
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.
The layer to which to add the child layer
The layer to add to the parent layer
Inserts the layer as a sibling behind another layer. If the layer to insert was already part of a layer hierarchy, it will be removed from its old parent first. 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.
The layer to insert into the hierarchy
The layer that will be used as the sibling layer above which the insertion will take place
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.
The layer to insert into the hierarchy
The layer that will be used as the sibling layer below which the insertion will take place
Sets the visibility of the layer. If the visibility has changed, layer_mark_dirty() will be called automatically on the parent layer.
The layer for which to set the visibility
Supply true to make the layer hidden, or false to make it non-hidden.
Gets the visibility of the layer.
The layer for which to get the visibility
True if the layer is hidden, false if it is not hidden.
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.
The layer for which to set the clipping property
Supply true to make the layer clip to its frame, or false to make it non-clipping.
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.
The layer for which to get the clipping property
True if clipping is enabled for the layer, false if clipping is not enabled for the layer.
Gets the data from a layer that has been created with an extra data region.
The layer to get the data region from.
A void pointer to the data region.
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.
The layer that needs to be rendered
The destination graphics context to draw into
Get the largest unobstructed bounds rectangle of a layer.
The layer for which to get the unobstructed bounds.
The unobstructed bounds of the layer.
Get the largest unobstructed bounds rectangle of a layer.
The layer for which to get the unobstructed bounds.
The unobstructed bounds of the layer.
Do you have questions about the Pebble SDK?
Do you need some help understanding something on this page?
You can either take advantage of our awesome developer community and check out the SDK Help forums, or you can send us a message through the website!