User interface layers for displaying graphic components. More...

Collaboration diagram for Layers:

Modules
	TextLayer
	Layer that displays and formats a text string.

	ScrollLayer
	Layer that scrolls its contents, animated.

	MenuLayer
	Layer that displays a standard list menu. Data is provided using callbacks.

	SimpleMenuLayer
	Wrapper around MenuLayer, that uses static data to display a list menu.

	ActionBarLayer
	Vertical, bar-shaped control widget on the right edge of the window.

	StatusBarLayer
	Layer that serves as a configurable status bar.

	BitmapLayer
	Layer that displays a bitmap image.

	RotBitmapLayer
	Layer that displays a rotated bitmap image.

Classes
class	Pebble::Layer

class	Pebble::SimpleLayer
	Layer that is automatically managed. More...

class	Pebble::CustomLayer
	Layer that is automatically managed and contains an OnUpdate callback for drawing. More...

Typedefs
typedef struct Layer	Layer

typedef void(*	LayerUpdateProc) (struct Layer layer, GContext ctx)

Functions
Layer *	layer_create (GRect frame)

Layer *	layer_create_with_data (GRect frame, size_t data_size)

void	layer_destroy (Layer *layer)
	Destroys a layer previously created by layer_create.

void	layer_mark_dirty (Layer *layer)

void	layer_set_update_proc (Layer *layer, LayerUpdateProc update_proc)

void	layer_set_frame (Layer *layer, GRect frame)

GRect	layer_get_frame (const Layer *layer)

void	layer_set_bounds (Layer *layer, GRect bounds)

GRect	layer_get_bounds (const Layer *layer)

GRect	layer_get_unobstructed_bounds (const Layer *layer)

GPoint	layer_convert_point_to_screen (const Layer *layer, GPoint point)

GRect	layer_convert_rect_to_screen (const Layer *layer, GRect rect)

struct Window *	layer_get_window (const Layer *layer)

void	layer_remove_from_parent (Layer *child)

void	layer_remove_child_layers (Layer *parent)

void	layer_add_child (Layer parent, Layer child)

void	layer_insert_below_sibling (Layer layer_to_insert, Layer below_sibling_layer)

void	layer_insert_above_sibling (Layer layer_to_insert, Layer above_sibling_layer)

void	layer_set_hidden (Layer *layer, bool hidden)

bool	layer_get_hidden (const Layer *layer)

void	layer_set_clips (Layer *layer, bool clips)

bool	layer_get_clips (const Layer *layer)

void *	layer_get_data (const Layer *layer)

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 the (chapter "Layers") for a conceptual overview of Layers and relevant code examples.

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 (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);

Typedef Documentation

◆ LayerUpdateProc

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()

Function Documentation

◆ layer_add_child()

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_convert_point_to_screen()

GPoint layer_convert_point_to_screen	(	const Layer *	layer,
		GPoint	point
	)

Converts a point from the layer's local coordinate system to screen coordinates.

Note: If the layer isn't part of the view hierarchy the result is undefined.

Parameters

layer	The view whose coordinate system will be used to convert the value to the screen.
point	A point specified in the local coordinate system (bounds) of the layer.

Returns: The point converted to the coordinate system of the screen.

◆ layer_convert_rect_to_screen()

GRect layer_convert_rect_to_screen	(	const Layer *	layer,
		GRect	rect
	)

Converts a rectangle from the layer's local coordinate system to screen coordinates.

Note: If the layer isn't part of the view hierarchy the result is undefined.

Parameters

layer	The view whose coordinate system will be used to convert the value to the screen.
rect	A rectangle specified in the local coordinate system (bounds) of the layer.

Returns: The rectangle converted to the coordinate system of the screen.

◆ layer_create()

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_create_with_data()

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

◆ layer_get_bounds()

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

◆ layer_get_clips()

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.

◆ layer_get_data()

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.

◆ layer_get_frame()

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

◆ layer_get_hidden()

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.

◆ layer_get_unobstructed_bounds()

GRect layer_get_unobstructed_bounds ( const Layer * layer )

Get the largest unobstructed bounds rectangle of a layer.

Parameters

layer The layer for which to get the unobstructed bounds.

Returns: The unobstructed bounds of the layer.

See also: UnobstructedArea

◆ layer_get_window()

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()

◆ layer_insert_above_sibling()

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

◆ layer_insert_below_sibling()

void layer_insert_below_sibling	(	Layer *	layer_to_insert,
		Layer *	below_sibling_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.

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

◆ layer_mark_dirty()

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

◆ layer_remove_child_layers()

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

◆ layer_remove_from_parent()

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

child The layer to remove

◆ layer_set_bounds()

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()

◆ layer_set_clips()

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.

◆ layer_set_frame()

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()

◆ layer_set_hidden()

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.

◆ layer_set_update_proc()

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

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.

frame	The frame at which the layer should be initialized.
data_size	The size (in bytes) of memory to allocate for callback data.

Modules

Classes

Typedefs

Functions

Detailed Description

Typedef Documentation

◆ LayerUpdateProc

Function Documentation

◆ layer_add_child()

◆ layer_convert_point_to_screen()

◆ layer_convert_rect_to_screen()

◆ layer_create()

◆ layer_create_with_data()

◆ layer_get_bounds()

◆ layer_get_clips()

◆ layer_get_data()

◆ layer_get_frame()

◆ layer_get_hidden()

◆ layer_get_unobstructed_bounds()

◆ layer_get_window()

◆ layer_insert_above_sibling()

◆ layer_insert_below_sibling()

◆ layer_mark_dirty()

◆ layer_remove_child_layers()

◆ layer_remove_from_parent()

◆ layer_set_bounds()

◆ layer_set_clips()

◆ layer_set_frame()

◆ layer_set_hidden()

◆ layer_set_update_proc()