All Data Structures Functions Variables Typedefs Enumerations Enumerator Groups

Detailed Description

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 theBuilding User Interfaces chapter in Pebble Developer Guide (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);

Modules

 ActionBarLayer
 Vertical, bar-shaped control widget on the right edge of the window.
 
 BitmapLayer
 Layer that displays a bitmap image.
 
 InverterLayer
 Layer that inverts anything "below it".
 
 MenuLayer
 Layer that displays a standard list menu. Data is provided using callbacks.
 
 RotBitmapLayer
 Layer that displays a rotated bitmap image.
 
 ScrollLayer
 Layer that scrolls its contents, animated.
 
 SimpleMenuLayer
 Wrapper around MenuLayer, that uses static data to display a list menu.
 
 TextLayer
 Layer that displays and formats a text string.
 

Function Documentation

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
parentThe layer to which to add the child layer
childThe 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
    frameThe 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
    frameThe frame at which the layer should be initialized.
    data_sizeThe 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
layerThe 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
layerThe 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
layerThe 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
layerThe 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
layerThe 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
layerThe 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_insertThe layer to insert into the hierarchy
above_sibling_layerThe 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_insertThe layer to insert into the hierarchy
below_sibling_layerThe 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
    layerThe 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
parentThe 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
childThe layer to remove
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
layerThe layer for which to set the bounds
boundsThe 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
layerThe layer for which to set the clipping property
clipsSupply 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
layerThe layer for which to set the frame
frameThe 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
layerThe layer for which to set the visibility
hiddenSupply true to make the layer hidden, or false to make it non-hidden.
void layer_set_update_proc ( Layer *  layer,
LayerUpdateProc  update_proc 
)

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
layerPointer to the layer structure.
update_procPointer 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 Documentation

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
layerThe layer that needs to be rendered
ctxThe destination graphics context to draw into
See Also
Graphics
layer_set_update_proc()