pebble
  • Tutorials
  • Get the SDK
  • Guides
  • Documentation
  • Examples
  • Community
  • Blog
  • More
Privacy
Cookies
Publish

Pebble C API

  • Pebble C API
  • Pebble JavaScript API
  • PebbleKit JS
  • PebbleKit iOS
  • PebbleKit Android
  • Foundation
    • App
    • App Communication
    • App Glance
    • AppMessage
    • AppSync
    • AppWorker
    • DataLogging
    • DataStructures
      • UUID
    • Dictation
    • Dictionary
    • Event Service
      • AccelerometerService
      • AppFocusService
      • BatteryStateService
      • CompassService
      • ConnectionService
      • HealthService
      • TickTimerService
    • Exit Reason
    • Internationalization
    • Launch Reason
    • Logging
    • Math
    • Memory Management
    • Platform
    • Resources
      • File Formats
    • Storage
    • Timer
    • Wakeup
    • Wall Time
    • WatchInfo
    • Rocky
  • Graphics
    • Draw Commands
    • Drawing Paths
    • Drawing Primitives
    • Drawing Text
    • Fonts
    • Graphics Context
    • Graphics Types
      • Color Definitions
  • User Interface
    • Animation
      • PropertyAnimation
    • Clicks
    • Layers
      • ActionBarLayer
      • BitmapLayer
      • MenuLayer
      • RotBitmapLayer
      • ScrollLayer
      • SimpleMenuLayer
      • StatusBarLayer
      • TextLayer
    • Light
    • Preferences
    • UnobstructedArea
    • Vibes
    • Window
      • ActionMenu
      • NumberWindow
    • Window Stack
  • Standard C
    • Format
    • Locale
    • Math
    • Memory
    • String
    • Time

Window

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 User Interface Layers chapter in the Pebble Developer Guides (chapter "Window") for a conceptual overview of Window, the Window Stack and relevant code examples.

Modules

ActionMenu

 

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.

  • click_config_provider : NULL

  • window_handlers : all NULL

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.

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

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

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

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

Parameters

window

The window to query its loaded status

Returns

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

See Also

WindowHandlers
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.

Parameters

window

The window for which to set the user data

data

A pointer to user data.

See Also

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

Parameters

window

The window for which to get the user data

See Also

window_set_user_data
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
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
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.

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.

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.

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.

Data Structure Documentation

struct 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.

Data Fields

WindowHandler 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.

WindowHandler 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.

WindowHandler 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.

WindowHandler 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.

See Also

window_set_window_handlers()

Typedef Documentation

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

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

See Also

WindowHandlers

Need some help?

Modules

  • ActionMenu
  • NumberWindow

Functions

  • window_create
  • window_destroy
  • window_set_click_config_provider
  • window_set_click_config_provider_with_context
  • window_get_click_config_provider
  • window_get_click_config_context
  • window_set_window_handlers
  • window_get_root_layer
  • window_set_background_color
  • window_is_loaded
  • window_set_user_data
  • window_get_user_data
  • window_single_click_subscribe
  • window_single_repeating_click_subscribe
  • window_multi_click_subscribe
  • window_long_click_subscribe
  • window_raw_click_subscribe
  • window_set_click_context

Data Structures

  • WindowHandlers

Typedefs

  • Window
  • WindowHandler

Getting Help

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!