From 156c3311529493c92c4ba66af3bff135fea7efff Mon Sep 17 00:00:00 2001 From: Peter Johanson Date: Thu, 26 Sep 2024 01:09:03 -0600 Subject: [PATCH] feat: Add basic metadata info to new behavior guide. --- docs/docs/development/new-behavior.mdx | 93 ++++++++++++++++++++++++++ 1 file changed, 93 insertions(+) diff --git a/docs/docs/development/new-behavior.mdx b/docs/docs/development/new-behavior.mdx index 3d50b821ca8f..b027e5d30295 100644 --- a/docs/docs/development/new-behavior.mdx +++ b/docs/docs/development/new-behavior.mdx @@ -293,6 +293,8 @@ Comes in the form `static const struct behavior_driver_api _drive - `.binding_pressed`: Used for behaviors that invoke an action on its keybind press. Set `.binding_pressed` equal to the function typically named [`on__binding_pressed`](#dependencies). - `.binding_released`: Same as above, except for activating on keybind release events. Set `.binding_released` equal to the function typically named [`on__binding_released`](#dependencies). +- `.parameter_metadata`: Defined in ``. Pointer to metadata describing the parameters to use with the behavior so the behavior may be used with [ZMK Studio](../features/studio.md) +- `.get_parameter_metadata`: Defined in ``. Callback function that can dynamically provide/populate the metadata describing the parameters to use with the behavior so the behavior may be used with [ZMK Studio](../features/studio.md) - `.locality`: Defined in ``. Describes how the behavior affects parts of a _split_ keyboard. - `BEHAVIOR_LOCALITY_CENTRAL`: Behavior only affects the central half, which is the case for most keymap-related behavior. - `BEHAVIOR_LOCALITY_EVENT_SOURCE`: Behavior affects only the central _or_ peripheral half depending on which side invoked the behavior binding, such as [reset behaviors](../keymaps/behaviors/reset.md). @@ -301,6 +303,97 @@ Comes in the form `static const struct behavior_driver_api _drive For unibody keyboards, all locality values perform the same as `BEHAVIOR_LOCALITY_GLOBAL`. ::: +##### Behavior Metadata + +allows flexibility to specify different kinds of well known parameter types, such as a HID usage, different second parameters passed on the selected first parameter, etc. +Behavior metadata documents the possible combinations of parameters that can be used with the behavior when added to your keymap. The metadata structure + +You can see a few examples of how the metadata is implemented in practice for: + +- [key press](https://github.com/zmkfirmware/zmk/blob/main/app/src/behaviors/behavior_key_press.c#L21), +- [RGB underglow](https://github.com/zmkfirmware/zmk/blob/main/app/src/behaviors/behavior_rgb_underglow.c#L23), +- and more complex scenarios like [hold-tap](https://github.com/zmkfirmware/zmk/blob/main/app/src/behaviors/behavior_hold_tap.c#L680) which is dynamic based on what behaviors are set up in the hold-tap bindings + +Behavior metadata consists of one or more metadata sets, where each metadata set has a set of values for the parameter(s) used with the behavior. + +For example, a common approach for behaviors is to have a set of possible first parameters that identify the "command" to invoke for the behavior, and the second parameter is a detail/sub-parameter to the action. You can see this with the `&bt` behavior. +In that scenario, all `&bt` "commands" that take a BT profile as a secound parameter are grouped into one set, and all commands that take no arguments are grouped into another. + +This allows the ZMK Studio UI to properly show a input for a profile only when the appropriate first "command" selection is made in the UI. Here is a snippet of that setup from the [behavior_bt.c](https://github.com/zmkfirmware/zmk/blob/main/app/src/behaviors/behavior_bt.c#L25) code: + +``` + +# Set up the values for commands that take no additional parameter. +static const struct behavior_parameter_value_metadata no_arg_values[] = { + { + .display_name = "Next Profile", + .type = BEHAVIOR_PARAMETER_VALUE_TYPE_VALUE, + .value = BT_NXT_CMD, + }, + { + .display_name = "Previous Profile", + .type = BEHAVIOR_PARAMETER_VALUE_TYPE_VALUE, + .value = BT_PRV_CMD, + }, + { + .display_name = "Clear All Profiles", + .type = BEHAVIOR_PARAMETER_VALUE_TYPE_VALUE, + .value = BT_CLR_ALL_CMD, + }, + { + .display_name = "Clear Selected Profile", + .type = BEHAVIOR_PARAMETER_VALUE_TYPE_VALUE, + .value = BT_CLR_CMD, + }, +}; + +# Set up the "no arg" metadata set. +static const struct behavior_parameter_metadata_set no_args_set = { + .param1_values = no_arg_values, + .param1_values_len = ARRAY_SIZE(no_arg_values), +}; + +# Set up the possible param1 values for commands that take a profile index for param2 +static const struct behavior_parameter_value_metadata prof_index_param1_values[] = { + { + .display_name = "Select Profile", + .type = BEHAVIOR_PARAMETER_VALUE_TYPE_VALUE, + .value = BT_SEL_CMD, + }, + { + .display_name = "Disconnect Profile", + .type = BEHAVIOR_PARAMETER_VALUE_TYPE_VALUE, + .value = BT_DISC_CMD, + }, +}; + +# Set up the param2 value metadata for the valid range of possible profiles to pick from. +static const struct behavior_parameter_value_metadata prof_index_param2_values[] = { + { + .display_name = "Profile", + .type = BEHAVIOR_PARAMETER_VALUE_TYPE_RANGE, + .range = {.min = 0, .max = ZMK_BLE_PROFILE_COUNT}, + }, +}; + +# Set up the metadata set for the commands that take a profile for the second parameter. +static const struct behavior_parameter_metadata_set profile_index_metadata_set = { + .param1_values = prof_index_param1_values, + .param1_values_len = ARRAY_SIZE(prof_index_param1_values), + .param2_values = prof_index_param2_values, + .param2_values_len = ARRAY_SIZE(prof_index_param2_values), +}; + +# Finally, expose all the sets in the top level aggregate structure. +static const struct behavior_parameter_metadata_set metadata_sets[] = {no_args_set, + profile_index_metadata_set}; + +static const struct behavior_parameter_metadata metadata = { + .sets_len = ARRAY_SIZE(metadata_sets), + .sets = metadata_sets, +}; +``` + ##### Data pointers (optional) The data `struct` stores additional data required for **each new instance** of the behavior. Regardless of the instance number, `n`, `behavior__data_##n` is typically initialized as an empty `struct`. The data respective to each instance of the behavior can be accessed in functions like [`on__binding_pressed(struct zmk_behavior_binding *binding, struct zmk_behavior_binding_event event)`](#dependencies) by extracting the behavior device from the keybind like so: