All Data Structures Functions Variables Typedefs Enumerations Enumerator Groups Pages

Detailed Description

The basic building block of the user interface.

Windows are the basic unit of app flow. The person wearing the watch interacts with a window, using what they see on screen and pressing the buttons of the watch. Thus a window is output, but takes input as well (see window_set_click_config_provider() and Clicks). When a window is visible, its root Layer (and all its child layers) will be drawn onto the screen automatically. The Window Stack is the global manager of what window is presented and makes sure that input events are forwarded to the top-most window.

Please refer to Building User Interfaces chapter in Pebble Developer Guide (chapter "Windows") for a conceptual overview of Window, the Window Stack and relevant code examples.

Modules

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

Function Documentation

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.
  • Full screen : no
  • click_config_provider : NULL
  • window_handlers : all NULL
  • status_bar_icon : NULL (none)
    Returns
    A pointer to the window. NULL if the window could not be created
void window_destroy ( Window *  window)

Destroys a Window previously created by window_create.

ClickConfigProvider window_get_click_config_provider ( const Window *  window)

Gets the current click configuration provider of the window.

Parameters
windowThe window for which to get the click config provider
bool window_get_fullscreen ( const Window *  window)

Gets whether the window is full-screen, consequently hiding the sytem status bar.

Parameters
windowThe window for which to get its full-screen property
Returns
True if the window is marked as fullscreen, false if it is not marked as fullscreen.
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
windowThe window for which to get the root layer
Returns
The window's root layer
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
windowThe window for which to get the user data
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
windowThe window to query its loaded status
See Also
WindowHandlers
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 within the ClickConfigProvider.
Parameters
button_idThe button events to subscribe to.
See Also
ButtonId.
Parameters
delay_msMilliseconds after which "handler" is fired. A value of 0 means to use the system default 500ms.
down_handlerThe ClickHandler to fire as soon as the button has been held for delay_ms. This may be NULL to have no down handler.
up_handlerThe ClickHandler to fire on the release of a long click. This may be NULL to have no up 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 
)

Subscribe to multi click events.

Note
Must be called from within the ClickConfigProvider.
Parameters
button_idThe button events to subscribe to.
See Also
ButtonId.
Parameters
minMinimum number of clicks before handler is fired. Defaults to 2.
maxMaximum number of clicks after which the click counter is reset. A value of 0 means use "min" also as "max".
timeoutThe 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_onlyDefaults to false. When true, only the for the last multi-click the handler is called.
handlerThe ClickHandler to fire on this event. Fired for multi-clicks, as "filtered" by the last_click_only, min, and max parameters.
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.
Parameters
button_idThe button events to subscribe to.
See Also
ButtonId.
Parameters
down_handlerThe ClickHandler to fire as soon as the button has been pressed. This may be NULL to have no down handler.
up_handlerThe ClickHandler to fire on the release of the button. This may be NULL to have no up handler.
contextIf this context is not NULL, it will override the general context.
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
windowThe window for which to set the background color
background_colorThe new background color
See Also
window_get_root_layer()
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
windowThe window for which to set the click config provider
click_config_providerThe callback that will be called to configure the click recognizers with the window
See Also
Clicks
ClickConfigProvider
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
windowThe window for which to set the click config provider
click_config_providerThe callback that will be called to configure the click recognizers with the window
contextPointer to application specific data that will be passed to the click configuration provider callback.
See Also
Clicks
window_set_click_config_provider
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.

Note
Must be called from within the ClickConfigProvider.
Parameters
button_idThe button to set the context for.
contextPointer to data that will be passed as context.
void window_set_fullscreen ( Window *  window,
bool  enabled 
)

Sets whether or not the window is fullscreen, consequently hiding the sytem status bar.

Note
This needs to be called before pushing a window to the window stack.
Parameters
windowThe window for which to set its full-screen property
enabledTrue to make the window full-screen or false to leave space for the system status bar.
See Also
window_get_fullscreen()
void window_set_status_bar_icon ( Window *  window,
const GBitmap icon 
)

Assigns an icon (max. 16x16 pixels) that can be displayed in the system status bar. When no icon is assigned, the icon of the previous window on the window stack is used.

Note
This needs to be called before pushing a window to the window stack.
Parameters
windowThe window for which to set the status bar icon
iconThe new status bar icon
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
windowThe window for which to set the user data
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
windowThe window for which to set the window handlers
handlersThe handlers for the specified window
See Also
WindowHandlers
void window_single_click_subscribe ( ButtonId  button_id,
ClickHandler  handler 
)

Subscribe to single click events. A single click is detected every time "repeat_interval_ms" has been reached.

Note
Must be called from within the ClickConfigProvider.
window_single_click_subscribe() and window_single_repeating_click_subscribe() conflict, and cannot both be used on the same button.
Parameters
button_idThe button events to subscribe to.
See Also
ButtonId.
Parameters
contextOptional pointer to application specific data that will be passed into the handler.
See Also
Clicks A value of 0ms means "no repeat timer". The minimum is 30ms, and values below will be disregarded.
Parameters
handlerThe ClickHandler to fire on this event.
Note
When there is a multi_click and/or long_click setup, there will be a delay pending before the single click 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
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 within the ClickConfigProvider.
window_single_click_subscribe() and window_single_repeating_click_subscribe() conflict, and cannot both be used on the same button.
Parameters
repeat_interval_msWhen holding down, how many milliseconds before the handler is fired again.
Note
If there is a long-click handler subscribed on this button, repeat_interval_ms will not be used.
See Also
window_single_click_subscribe

Data Structure Documentation

struct WindowHandlers

WindowHandlers These handlers are called by the Window Stack as windows get pushed on / popped:

  • load: called when the window is pushed to the screen when it's not loaded. This is a good moment to do the layout of the window.
  • appear: called when the window comes on the screen (again). E.g. when second-top-most window gets revealed (again) after popping the top-most window, but also when the window is pushed for the first time. This is a good moment to start timers related to the window, or reset the UI, etc.
  • disappear:called when the window leaves the screen, e.g. when another window is pushed, or this window is popped. Good moment to stop timers related to the window.
  • unload: called when the window is deinited, but could be used in the future to free resources bound to windows that are not on screen.

All these handlers use WindowHandler as their function signature.

See Also
window_set_window_handlers()
Window Stack

Typedef Documentation

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