The basic building block of the user interface. More...

Collaboration diagram for Window:

Modules
	NumberWindow
	A ready-made Window prompting the user to pick a number.

	ActionMenu

Classes
class	Pebble::Window
	Wraps and existing Pebble window but does not take ownership of it. More...

class	Pebble::AppWindow
	Base class for application windows. More...

class	Pebble::NumberWindow

struct	WindowHandlers

Typedefs
typedef struct Window	Window

typedef void(*	WindowHandler) (struct Window *window)

typedef struct WindowHandlers	WindowHandlers

Functions
Window *	window_create (void)

void	window_destroy (Window *window)
	Destroys a Window previously created by window_create.

void	window_set_click_config_provider (Window *window, ClickConfigProvider click_config_provider)

void	window_set_click_config_provider_with_context (Window window, ClickConfigProvider click_config_provider, void context)

ClickConfigProvider	window_get_click_config_provider (const Window *window)

void *	window_get_click_config_context (Window *window)

void	window_set_window_handlers (Window *window, WindowHandlers handlers)

struct Layer *	window_get_root_layer (const Window *window)

void	window_set_background_color (Window *window, GColor background_color)

bool	window_is_loaded (Window *window)

void	window_set_user_data (Window window, void data)

void *	window_get_user_data (const Window *window)

void	window_single_click_subscribe (ButtonId button_id, ClickHandler handler)

void	window_single_repeating_click_subscribe (ButtonId button_id, uint16_t repeat_interval_ms, ClickHandler handler)

void	window_multi_click_subscribe (ButtonId button_id, uint8_t min_clicks, uint8_t max_clicks, uint16_t timeout, bool last_click_only, ClickHandler handler)

void	window_long_click_subscribe (ButtonId button_id, uint16_t delay_ms, ClickHandler down_handler, ClickHandler up_handler)

void	window_raw_click_subscribe (ButtonId button_id, ClickHandler down_handler, ClickHandler up_handler, void *context)

void	window_set_click_context (ButtonId button_id, void *context)

Detailed Description

The basic building block of the user interface.

Windows are the top-level elements in the UI hierarchy and the basic building blocks for a Pebble UI. A single window is always displayed at a time on Pebble, with the exception of when animating from one window to the other, which, in that case, is managed by the window stack. You can stack windows on top of each other, but only the topmost window will be visible.

Users wearing a Pebble typically interact with the content and media displayed in a window, clicking and pressing buttons on the watch, depending on what they see and wish to respond to in a window.

Windows serve to display a hierarchy of layers on the screen and handle user input. When a window is visible, its root Layer (and all its child layers) are drawn onto the screen automatically.

You need a window, which always fills the entire screen, to display images, text, and graphics in your Pebble app. A layer by itself doesn’t display on Pebble; it must be in the current window’s layer hierarchy to be visible.

The Window Stack serves as the global manager of what window is presented and makes sure that input events are forwarded to the topmost window.

Refer to the (chapter "Window") for a conceptual overview of Window, the Window Stack and relevant code examples.

Typedef Documentation

◆ WindowHandler

typedef void(* WindowHandler) (struct Window *window)

Function signature for a handler that deals with transition events of a window.

See also: WindowHandlers; window_set_window_handlers()

◆ WindowHandlers

typedef struct WindowHandlers WindowHandlers

WindowHandlers These handlers are called by the Window Stack as windows get pushed on / popped. All these handlers use WindowHandler as their function signature.

See also: window_set_window_handlers(); Window Stack

Function Documentation

◆ window_create()

Window* window_create ( void )

Creates a new Window on the heap and initalizes it with the default values.

Background color : GColorWhite
Root layer's update_proc : function that fills the window's background using background_color.
click_config_provider : NULL
window_handlers : all NULL
Returns
A pointer to the window. NULL if the window could not be created

◆ window_get_click_config_context()

void* window_get_click_config_context ( Window * window )

Gets the current click configuration provider context of the window.

Parameters

window The window for which to get the click config provider context

◆ window_get_click_config_provider()

ClickConfigProvider window_get_click_config_provider ( const Window * window )

Gets the current click configuration provider of the window.

Parameters

window The window for which to get the click config provider

◆ window_get_root_layer()

struct Layer* window_get_root_layer ( const Window * window )

Gets the root Layer of the window. The root layer is the layer at the bottom of the layer hierarchy for this window. It is the window's "canvas" if you will. By default, the root layer only draws a solid fill with the window's background color.

Parameters

window The window for which to get the root layer

Returns: The window's root layer

◆ window_get_user_data()

void* window_get_user_data ( const Window * window )

Gets the pointer to developer-supplied data that was previously set using window_set_user_data().

See also: window_set_user_data

Parameters

window The window for which to get the user data

◆ window_is_loaded()

bool window_is_loaded ( Window * window )

Gets whether the window has been loaded. If a window is loaded, its .load handler has been called (and the .unload handler has not been called since).

Returns: true if the window is currently loaded or false if not.

Parameters

window The window to query its loaded status

See also: WindowHandlers

◆ window_long_click_subscribe()

void window_long_click_subscribe	(	ButtonId	button_id,
		uint16_t	delay_ms,
		ClickHandler	down_handler,
		ClickHandler	up_handler
	)

Subscribe to long click events.

Note: Must be called from the ClickConfigProvider.; The back button cannot be overridden with a long click.

Parameters

button_id	The button events to subscribe to.
delay_ms	Milliseconds after which "handler" is fired. A value of 0 means to use the system default 500ms.
down_handler	The ClickHandler to fire as soon as the button has been held for `delay_ms`. This may be NULL to have no down handler.
up_handler	The ClickHandler to fire on the release of a long click. This may be NULL to have no up handler.

◆ window_multi_click_subscribe()

void window_multi_click_subscribe	(	ButtonId	button_id,
		uint8_t	min_clicks,
		uint8_t	max_clicks,
		uint16_t	timeout,
		bool	last_click_only,
		ClickHandler	handler
	)

Subscribe to multi click events.

Note: Must be called from the ClickConfigProvider.

Parameters

button_id	The button events to subscribe to.
min_clicks	Minimum number of clicks before handler is fired. Defaults to 2.
max_clicks	Maximum number of clicks after which the click counter is reset. A value of 0 means use "min" also as "max".
timeout	The delay after which a sequence of clicks is considered finished, and the click counter is reset. A value of 0 means to use the system default 300ms.
last_click_only	Defaults to false. When true, only the handler for the last multi-click is called.
handler	The ClickHandler to fire on this event. Fired for multi-clicks, as "filtered" by the `last_click_only`, `min`, and `max` parameters.

◆ window_raw_click_subscribe()

void window_raw_click_subscribe	(	ButtonId	button_id,
		ClickHandler	down_handler,
		ClickHandler	up_handler,
		void *	context
	)

Subscribe to raw click events.

Note: Must be called from within the ClickConfigProvider.; The back button cannot be overridden with a raw click.

Parameters

button_id	The button events to subscribe to.
down_handler	The ClickHandler to fire as soon as the button has been pressed. This may be NULL to have no down handler.
up_handler	The ClickHandler to fire on the release of the button. This may be NULL to have no up handler.
context	If this context is not NULL, it will override the general context.

◆ window_set_background_color()

void window_set_background_color	(	Window *	window,
		GColor	background_color
	)

Sets the background color of the window, which is drawn automatically by the root layer of the window.

Parameters

window	The window for which to set the background color
background_color	The new background color

See also: window_get_root_layer()

◆ window_set_click_config_provider()

void window_set_click_config_provider	(	Window *	window,
		ClickConfigProvider	click_config_provider
	)

Sets the click configuration provider callback function on the window. This will automatically setup the input handlers of the window as well to use the click recognizer subsystem.

Parameters

window	The window for which to set the click config provider
click_config_provider	The callback that will be called to configure the click recognizers with the window

See also: Clicks; ClickConfigProvider

◆ window_set_click_config_provider_with_context()

void window_set_click_config_provider_with_context	(	Window *	window,
		ClickConfigProvider	click_config_provider,
		void *	context
	)

Same as window_set_click_config_provider(), but will assign a custom context pointer (instead of the window pointer) that will be passed into the ClickHandler click event handlers.

Parameters

window	The window for which to set the click config provider
click_config_provider	The callback that will be called to configure the click recognizers with the window
context	Pointer to application specific data that will be passed to the click configuration provider callback (defaults to the window).

See also: Clicks; window_set_click_config_provider

◆ window_set_click_context()

void window_set_click_context	(	ButtonId	button_id,
		void *	context
	)

Set the context that will be passed to handlers for the given button's events. By default the context passed to handlers is equal to the ClickConfigProvider context (defaults to the window).

Note: Must be called from within the ClickConfigProvider.

Parameters

button_id	The button to set the context for.
context	Set the context that will be passed to handlers for the given button's events.

◆ window_set_user_data()

void window_set_user_data	(	Window *	window,
		void *	data
	)

Sets a pointer to developer-supplied data that the window uses, to provide a means to access the data at later times in one of the window event handlers.

See also: window_get_user_data

Parameters

window	The window for which to set the user data
data	A pointer to user data.

◆ window_set_window_handlers()

void window_set_window_handlers	(	Window *	window,
		WindowHandlers	handlers
	)

Sets the window handlers of the window. These handlers get called e.g. when the user enters or leaves the window.

Parameters

window	The window for which to set the window handlers
handlers	The handlers for the specified window

See also: WindowHandlers

◆ window_single_click_subscribe()

void window_single_click_subscribe	(	ButtonId	button_id,
		ClickHandler	handler
	)

Subscribe to single click events.

Note: Must be called from the ClickConfigProvider.; window_single_click_subscribe() and window_single_repeating_click_subscribe() conflict, and cannot both be used on the same button.; When there is a multi_click and/or long_click setup, there will be a delay before the single click

Parameters

button_id	The button events to subscribe to.
handler	The ClickHandler to fire on this event. handler will get fired. On the other hand, when there is no multi_click nor long_click setup, the single click handler will fire directly on button down.

See also: ButtonId; Clicks; window_single_repeating_click_subscribe

◆ window_single_repeating_click_subscribe()

void window_single_repeating_click_subscribe	(	ButtonId	button_id,
		uint16_t	repeat_interval_ms,
		ClickHandler	handler
	)

Subscribe to single click event, with a repeat interval. A single click is detected every time "repeat_interval_ms" has been reached.

Note: Must be called from the ClickConfigProvider.; window_single_click_subscribe() and window_single_repeating_click_subscribe() conflict, and cannot both be used on the same button.; The back button cannot be overridden with a repeating click.

Parameters

button_id	The button events to subscribe to.
repeat_interval_ms	When holding down, how many milliseconds before the handler is fired again. A value of 0ms means "no repeat timer". The minimum is 30ms, and values below will be disregarded. If there is a long-click handler subscribed on this button, `repeat_interval_ms` will not be used.
handler	The ClickHandler to fire on this event.

See also: window_single_click_subscribe

Modules

Classes

Typedefs

Functions

Detailed Description

Typedef Documentation

◆ WindowHandler

◆ WindowHandlers

Function Documentation

◆ window_create()

◆ window_get_click_config_context()

◆ window_get_click_config_provider()

◆ window_get_root_layer()

◆ window_get_user_data()

◆ window_is_loaded()

◆ window_long_click_subscribe()

◆ window_multi_click_subscribe()

◆ window_raw_click_subscribe()

◆ window_set_background_color()

◆ window_set_click_config_provider()

◆ window_set_click_config_provider_with_context()

◆ window_set_click_context()

◆ window_set_user_data()

◆ window_set_window_handlers()

◆ window_single_click_subscribe()

◆ window_single_repeating_click_subscribe()