Handling button click interactions.
Each Pebble window handles Pebble's buttons while it is displayed. Raw button down and button up events are transformed into click events that can be transferred to your app:
Single-click. Detects a single click, that is, a button down event followed by a button up event. It also offers hold-to-repeat functionality (repeated click).
Multi-click. Detects double-clicking, triple-clicking and other arbitrary click counts. It can fire its event handler on all of the matched clicks, or just the last.
Long-click. Detects long clicks, that is, press-and-hold.
Raw. Simply forwards the raw button events. It is provided as a way to use both the higher level "clicks" processing and the raw button events at the same time.
To receive click events when a window is displayed, you must register a ClickConfigProvider for this window with window_set_click_config_provider(). Your ClickConfigProvider will be called every time the window becomes visible with one context argument. By default this context is a pointer to the window but you can change this with window_set_click_config_provider_with_context().
In your ClickConfigProvider you call the window_single_click_subscribe(), window_single_repeating_click_subscribe(), window_multi_click_subscribe(), window_long_click_subscribe() and window_raw_click_subscribe() functions to register a handler for each event you wish to receive.
For convenience, click handlers are provided with a ClickRecognizerRef and a user-specified context.
The ClickRecognizerRef can be used in combination with click_number_of_clicks_counted(), click_recognizer_get_button_id() and click_recognizer_is_repeating() to get more information about the click. This is useful if you want different buttons or event types to share the same handler.
The user-specified context is the context of your ClickConfigProvider (see above). By default it points to the window. You can override it for all handlers with window_set_click_config_provider_with_context() or for a specific button with window_set_click_context().
Watchfaces cannot use the buttons to interact with the user. Instead, you can use the AccelerometerService.
By default, the Back button will always pop to the previous window on the Window Stack (and leave the app if the current window is the only window). You can override the default back button behavior with window_single_click_subscribe() and window_multi_click_subscribe() but you cannot set a repeating, long or raw click handler on the back button because a long press will always terminate the app and return to the main menu.
First associate a click config provider callback with your window:
void app_init(void) {
...
window_set_click_config_provider(&window, (ClickConfigProvider) config_provider);
...
}
void config_provider(Window *window) {
// single click / repeat-on-hold config:
window_single_click_subscribe(BUTTON_ID_DOWN, down_single_click_handler);
window_single_repeating_click_subscribe(BUTTON_ID_SELECT, 1000, select_single_click_handler);
// multi click config:
window_multi_click_subscribe(BUTTON_ID_SELECT, 2, 10, 0, true, select_multi_click_handler);
// long click config:
window_long_click_subscribe(BUTTON_ID_SELECT, 700, select_long_click_handler, select_long_click_release_handler);
}
void down_single_click_handler(ClickRecognizerRef recognizer, void *context) {
... called on single click ...
Window *window = (Window *)context;
}
void select_single_click_handler(ClickRecognizerRef recognizer, void *context) {
... called on single click, and every 1000ms of being held ...
Window *window = (Window *)context;
}
void select_multi_click_handler(ClickRecognizerRef recognizer, void *context) {
... called for multi-clicks ...
Window *window = (Window *)context;
const uint16_t count = click_number_of_clicks_counted(recognizer);
}
void select_long_click_handler(ClickRecognizerRef recognizer, void *context) {
... called on long click start ...
Window *window = (Window *)context;
}
void select_long_click_release_handler(ClickRecognizerRef recognizer, void *context) {
... called when long click is released ...
Window *window = (Window *)context;
}
Refer to the User Interface Layers chapter in the Pebble Developer Guides (chapter "Clicks") for a conceptual overview of clicks and relevant code examples.
Gets the click count. You can use this inside a click handler implementation to get the click count for multi_click and (repeated) click events.
The click recognizer for which to get the click count
The number of consecutive clicks, and for auto-repeating the number of repetitions.
Gets the button identifier. You can use this inside a click handler implementation to get the button id for the click event.
The click recognizer for which to get the button id that caused the click event
the ButtonId of the click recognizer
Is this a repeating click. You can use this inside a click handler implementation to find out whether this is a repeating click or not.
The click recognizer for which to find out whether this is a repeating click.
true if this is a repeating click.
Button ID values.
Back button.
Up button.
Select (middle) button.
Down button.
Total number of buttons.
Reference to opaque click recognizer When a ClickHandler callback is called, the recognizer that fired the handler is passed in.
Function signature of the callback that handles a recognized click pattern.
The click recognizer that detected a "click" pattern
Pointer to application specified data (see window_set_click_config_provider_with_context() and window_set_click_context()). This defaults to the window.
This callback is called every time the window becomes visible (and when you call window_set_click_config_provider() if the window is already visible).
Subscribe to click events using window_single_click_subscribe() window_single_repeating_click_subscribe() window_multi_click_subscribe() window_long_click_subscribe() window_raw_click_subscribe() These subscriptions will get used by the click recognizers of each of the 4 buttons.
Pointer to application specific data (see window_set_click_config_provider_with_context()).
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!