Handling button click interactions. More...
Classes | |
| class | Pebble::ClickRecognizer |
| class | Pebble::ClickConfig |
Typedefs | |
| typedef void * | ClickRecognizerRef |
| typedef void(* | ClickHandler) (ClickRecognizerRef recognizer, void *context) |
| typedef void(* | ClickConfigProvider) (void *context) |
Enumerations | |
| enum | ButtonId { BUTTON_ID_BACK = 0, BUTTON_ID_UP, BUTTON_ID_SELECT, BUTTON_ID_DOWN, NUM_BUTTONS } |
Functions | |
| uint8_t | click_number_of_clicks_counted (ClickRecognizerRef recognizer) |
| ButtonId | click_recognizer_get_button_id (ClickRecognizerRef recognizer) |
| bool | click_recognizer_is_repeating (ClickRecognizerRef recognizer) |
Detailed Description
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 AppWindow::SetClickConfigProvider(). Your ClickConfigProvider will be called every time the window becomes visible with one context argument.
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().
User interaction in watchfaces
Watchfaces cannot use the buttons to interact with the user. Instead, you can use the AccelerometerService.
About the Back button
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.
See also
Refer to the (chapter "Clicks") for a conceptual overview of clicks and relevant code examples.
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().
User interaction in watchfaces
Watchfaces cannot use the buttons to interact with the user. Instead, you can use the AccelerometerService.
About the Back button
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.
Usage example
First associate a click config provider callback with your window:
Then in the callback, you set your desired configuration for each button:
Now you implement the handlers for each click you've subscribed to and set up:
See also
Refer to the (chapter "Clicks") for a conceptual overview of clicks and relevant code examples.
Typedef Documentation
◆ ClickConfigProvider
| typedef void(* ClickConfigProvider) (void *context) |
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.
- Parameters
-
context Pointer to application specific data (see window_set_click_config_provider_with_context()).
◆ ClickHandler
| typedef void(* ClickHandler) (ClickRecognizerRef recognizer, void *context) |
Function signature of the callback that handles a recognized click pattern
- Parameters
-
recognizer The click recognizer that detected a "click" pattern context Pointer to application specified data (see window_set_click_config_provider_with_context() and window_set_click_context()). This defaults to the window.
- See also
- ClickConfigProvider
◆ ClickRecognizerRef
| typedef void* ClickRecognizerRef |
Reference to opaque click recognizer When a ClickHandler callback is called, the recognizer that fired the handler is passed in.
Enumeration Type Documentation
◆ ButtonId
| enum ButtonId |
Button ID values
- See also
- click_recognizer_get_button_id()
| Enumerator | |
|---|---|
| BUTTON_ID_BACK | Back button. |
| BUTTON_ID_UP | Up button. |
| BUTTON_ID_SELECT | Select (middle) button. |
| BUTTON_ID_DOWN | Down button. |
| NUM_BUTTONS | Total number of buttons. |
Function Documentation
◆ click_number_of_clicks_counted()
| uint8_t click_number_of_clicks_counted | ( | ClickRecognizerRef | recognizer | ) |
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.
- Parameters
-
recognizer The click recognizer for which to get the click count
- Returns
- The number of consecutive clicks, and for auto-repeating the number of repetitions.
◆ click_recognizer_get_button_id()
| ButtonId click_recognizer_get_button_id | ( | ClickRecognizerRef | recognizer | ) |
Gets the button identifier. You can use this inside a click handler implementation to get the button id for the click event.
- Parameters
-
recognizer The click recognizer for which to get the button id that caused the click event
- Returns
- the ButtonId of the click recognizer
◆ click_recognizer_is_repeating()
| bool click_recognizer_is_repeating | ( | ClickRecognizerRef | 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.
- Parameters
-
recognizer The click recognizer for which to find out whether this is a repeating click.
- Returns
- true if this is a repeating click.
