Clicks // Pebble Developers

gearss 2016-05-03

展开全文

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

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:

void app_init(void) {
  ...
  window_set_click_config_provider(&window, (ClickConfigProvider) config_provider);
  ...
}

Then in the callback, you set your desired configuration for each button:

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);
}

Now you implement the handlers for each click you've subscribed to and set up:

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

Function Documentation

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.

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

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.

Enum Documentation

enum ButtonId

Button ID values.

click_recognizer_get_button_id()

Enumerators

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.

Typedef Documentation

typedef void * ClickRecognizerRef

Reference to opaque click recognizer When a ClickHandler callback is called, the recognizer that fired the handler is passed in.

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.