All Data Structures Functions Variables Typedefs Enumerations Enumerator Groups Pages

Detailed Description

Dealing with button input.

The Clicks framework is the preferred way to handle button interactions. It offers an API that is concerned with "clicks" instead of raw up & down button events. Each button has a ClickRecognizer, which is represented using the ClickRecognizerRef type, which are automatically created by the system. Each of these ClickRecognizers is a little state machine that processes the raw stream of up & down events for one of the buttons and based upon the raw, incoming events, it tries to distill and match the "click" events according the application-provided configuration.

There are a 4 types of "click" events:

The configuration of the click recognizers happens inside a callback function (of type ClickConfigProvider) that is associated with a Window using window_set_click_config_provider() or using window_set_click_config_provider_with_context().

Example

For example, here, we first associate a click config provider callback with our window:

void app_init(void) {
...
...
}

Then in the callback, we set our 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);
}

Then we implement the handlers for each configuration we have set up:

void down_single_click_handler(ClickRecognizerRef recognizer, void *context) {
... called on single click ...
Window *window = (Window *)context; // This context defaults to the window, but may be changed with \ref window_set_click_context.
}
void select_single_click_handler(ClickRecognizerRef recognizer, void *context) {
... called on single click, and every 1000ms of being held ...
Window *window = (Window *)context; // This context defaults to the window, but may be changed with \ref window_set_click_context.
}
void select_multi_click_handler(ClickRecognizerRef recognizer, void *context) {
... called for multi-clicks ...
Window *window = (Window *)context; // This context defaults to the window, but may be changed with \ref window_set_click_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; // This context defaults to the window, but may be changed with \ref window_set_click_context.
}
void select_long_click_release_handler(ClickRecognizerRef recognizer, void *context) {
... called when long click is released ...
Window *window = (Window *)context; // This context defaults to the window, but may be changed with \ref window_set_click_context.
}

See templates/template_buttons/src/template_buttons.c for a complete example.

Note
The Back button cannot be re-configured. It is hard-wired to pop to the previous window on the Window Stack.

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
recognizerThe 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
recognizerThe click recognizer for which to get the button id that caused the click event
Returns
the ButtonId of the click recognizer

Typedef Documentation

typedef void(* ClickConfigProvider)(void *context)

This callback gets called at times that a click recognizer has to be set up, for example when a new window comes into view. 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.

See Also
ButtonId for the mapping buttons to the array indices.
Parameters
contextPointer to application specific data, as configured using window_set_click_config_provider_with_context(), or defaults to the window if registered with window_set_click_config_provider().
typedef void(* ClickHandler)(ClickRecognizerRef recognizer, void *context)

Function signature of the callback that handles a recognized click pattern.

Parameters
recognizerThe click recognizer that detected a "click" pattern
contextPointer to application specified data as configured using window_set_click_config_provider_with_context() or as set manually in the ClickConfigProvider callback on the .context field of the ClickConfig.
See Also
ClickConfigProvider
typedef void* ClickRecognizerRef

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

See Also
ClickHandler

Enumeration Type Documentation

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.