From 526abaef6a3a0cb08818f55a1d07b72f43903b12 Mon Sep 17 00:00:00 2001 From: Ally Parker Date: Tue, 29 Dec 2020 14:37:13 +0000 Subject: [PATCH] Add docs for subscribing to events --- docs/docs/development/events.md | 59 +++++++++++++++++++++++++++------ 1 file changed, 48 insertions(+), 11 deletions(-) diff --git a/docs/docs/development/events.md b/docs/docs/development/events.md index 392d93a6..eeeb523a 100644 --- a/docs/docs/development/events.md +++ b/docs/docs/development/events.md @@ -4,34 +4,71 @@ title: Events ## Overview ZMK uses events to decouple behaviours and to allow new functionality to be added to existing events. -## `activity_state_changed` +## Subscribing to events + +Subscribing to events uses a combination of the `ZMK_SUBSCRIPTION` and `ZMK_LISTENER` macros. + +`ZMK_SUBSCRIPTION` tells the event manager that the module wants to subscribe to a particular type of event. + +`ZMK_LISTENER` tells the event manager which method of the module to call when an event is raised on a subscription. When subscribing to multiple event types, you can check which event type was raised using the `is_` helper methods (See example below). + +:::note +The event manager expects the method to be called `_listener` by convention. +::: + +``` +int behavior_hold_tap_listener(const struct zmk_event_header *eh) { + if (is_position_state_changed(eh)) { + return position_state_changed_listener(eh); + } else if (is_keycode_state_changed(eh)) { + return keycode_state_changed_listener(eh); + } + return 0; +} + +ZMK_LISTENER(behavior_hold_tap, behavior_hold_tap_listener); +ZMK_SUBSCRIPTION(behavior_hold_tap, keycode_state_changed); +``` + +todo: Describe the return values from the listener methods. + +## Events + +### `activity_state_changed` + Fired by the activity monitor when the state changes. The monitor subscribes to `position_state_changed` and `sensor_event` events to keep track of activity. -* `ZMK_ACTIVITY_ACTIVE` -* `ZMK_ACTIVITY_IDLE` - When idle time is greater than `CONFIG_ZMK_IDLE_TIMEOUT ` -* `ZMK_ACTIVITY_SLEEP` - When `CONFIG_ZMK_SLEEP` is enabled and idle time is greater than `CONFIG_ZMK_IDLE_SLEEP_TIMEOUT` +- `ZMK_ACTIVITY_ACTIVE` +- `ZMK_ACTIVITY_IDLE` - When idle time is greater than `CONFIG_ZMK_IDLE_TIMEOUT ` +- `ZMK_ACTIVITY_SLEEP` - When `CONFIG_ZMK_SLEEP` is enabled and idle time is greater than `CONFIG_ZMK_IDLE_SLEEP_TIMEOUT` + +### `battery_state_changed` -## `battery_state_changed` todo -## `ble_active_profile_changed` +### `ble_active_profile_changed` + todo -## `keycode_state_changed` +### `keycode_state_changed` + todo -## `layer_state_changed` +### `layer_state_changed` + todo -## `modifiers_state_changed` +### `modifiers_state_changed` + todo -## `position_state_changed` +### `position_state_changed` + todo ## `sensor_event` todo -## `usb_conn_state_changed` +### `usb_conn_state_changed` todo