diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/_summary.md | 1 | ||||
| -rw-r--r-- | docs/feature_caps_word.md | 156 | ||||
| -rw-r--r-- | docs/keycodes.md | 8 | 
3 files changed, 165 insertions, 0 deletions
| diff --git a/docs/_summary.md b/docs/_summary.md index 786685eba4..fed75196b4 100644 --- a/docs/_summary.md +++ b/docs/_summary.md @@ -75,6 +75,7 @@    * Software Features      * [Auto Shift](feature_auto_shift.md) +    * [Caps Word](feature_caps_word.md)      * [Combos](feature_combo.md)      * [Debounce API](feature_debounce_type.md)      * [Key Lock](feature_key_lock.md) diff --git a/docs/feature_caps_word.md b/docs/feature_caps_word.md new file mode 100644 index 0000000000..0b71119917 --- /dev/null +++ b/docs/feature_caps_word.md @@ -0,0 +1,156 @@ +# Caps Word + +It is often useful to type a single word in all capitals, for instance +abbreviations like "QMK", or in code, identifiers like `KC_SPC`. "Caps Word" is +a modern alternative to Caps Lock: + +* Letters are capitalized while active, and Caps Word automatically disables +  itself at the end of the word. That is, it stops by default once a space or +  any key other than `a`--`z`, `0`--`9`, `-`, `_`, delete, or backspace is +  pressed. Caps Word also disables itself if the keyboard is idle for 5 seconds. +  This is configurable, see below. + +* To avoid requiring a dedicated key for Caps Word, there is an option +  (`BOTH_SHIFTS_TURNS_ON_CAPS_WORD`) to activate Caps Word by simultaneously +  pressing both shift keys. See below for other options. + +* The implementation does not use the Caps Lock (`KC_CAPS`) keycode. Caps Word +  works even if you're remapping Caps Lock at the OS level to Ctrl or something +  else, as Emacs and Vim users often do. + + +## How do I enable Caps Word :id=how-do-i-enable-caps-word + +In your `rules.mk`, add: + +```make +CAPS_WORD_ENABLE = yes +``` + +Next, use one the following methods to activate Caps Word: + +* **Activate by pressing a key**: Use the `CAPS_WORD` keycode (short +  alias `CAPSWRD`) in your keymap. + +* **Activate by pressing Left Shift + Right Shift**: Add `#define +  BOTH_SHIFTS_TURNS_ON_CAPS_WORD` to config.h. You may also need to disable or +  reconfigure Command, details below. Then, simultaneously pressing both left +  and right shifts turns on Caps Word. This method works with the plain +  `KC_LSFT` and `KC_RSFT` keycodes as well as one-shot shifts and Space Cadet +  shifts. If your shift keys are mod-taps, hold both shift mod-tap keys until +  the tapping term, then release them. + +* **Activate by double tapping Left Shift**: Add `#define +  DOUBLE_TAP_SHIFT_TURNS_ON_CAPS_WORD` config.h. Then, double tapping Left Shift +  turns on Caps Word. This method works with `KC_LSFT` or one-shot Left Shift +  `OSM(MOD_LSFT)`. To count as a double tap, the maximum time in milliseconds +  between taps is `TAPPING_TERM`, or if using `TAPPING_TERM_PER_KEY`, the time +  returned by `get_tapping_term()` for the shift keycode being tapped. + +* **Custom activation**: You can activate Caps Word from code by calling +  `caps_word_on()`. This may be used to activate Caps Word through [a +  combo](feature_combo.md) or [tap dance](feature_tap_dance.md) or any means +  you like. + +### Troubleshooting: Command :id=troubleshooting-command + +When using `BOTH_SHIFTS_TURNS_ON_CAPS_WORD`, you might see a compile message +**"BOTH_SHIFTS_TURNS_ON_CAPS_WORD and Command should not be enabled at the same +time, since both use the Left Shift + Right Shift key combination."** + +Many keyboards enable the [Command feature](feature_command.md), which by +default is also activated using the Left Shift + Right Shift key combination. To +fix this conflict, please disable Command by adding in rules.mk:  + +```make +COMMAND_ENABLE = no +``` + +Or configure Command to use another key combination like Left Ctrl + Right Ctrl +by defining `IS_COMMAND()` in config.h: + +```c +// Activate Command with Left Ctrl + Right Ctrl. +#define IS_COMMAND() (get_mods() == MOD_MASK_CTRL) +``` + + +## Customizing Caps Word :id=customizing-caps-word + +### Idle timeout :id=idle-timeout + +Caps Word turns off automatically if no keys are pressed for +`CAPS_WORD_IDLE_TIMEOUT` milliseconds. The default is 5000 (5 seconds). +Configure the timeout duration in config.h, for instance  + +```c +#define CAPS_WORD_IDLE_TIMEOUT 3000  // 3 seconds. +``` + +Setting `CAPS_WORD_IDLE_TIMEOUT` to 0 configures Caps Word to never time out. +Caps Word then remains active indefinitely until a word breaking key is pressed. + + +### Functions :id=functions + +Functions to manipulate Caps Word: + +| Function                | Description                                    | +|-------------------------|------------------------------------------------| +| `caps_word_on()`        | Turns Caps Word on.                            | +| `caps_word_off()`       | Turns Caps Word off.                           | +| `caps_word_toggle()`    | Toggles Caps Word.                             | +| `is_caps_word_on()`     | Returns true if Caps Word is currently on.     | + + +### Configure which keys are "word breaking" :id=configure-which-keys-are-word-breaking + +You can define the `caps_word_press_user(uint16_t keycode)` callback to +configure which keys should be shifted and which keys are considered "word +breaking" and stop Caps Word. + +The callback is called on every key press while Caps Word is active. When the +key should be shifted (that is, a letter key), the callback should call +`add_weak_mods(MOD_BIT(KC_LSFT))` to shift the key. Returning true continues the +current "word," while returning false is "word breaking" and deactivates Caps +Word. The default callback is + +```c +bool caps_word_press_user(uint16_t keycode) { +    switch (keycode) { +        // Keycodes that continue Caps Word, with shift applied. +        case KC_A ... KC_Z: +        case KC_MINS: +            add_weak_mods(MOD_BIT(KC_LSFT));  // Apply shift to next key. +            return true; + +        // Keycodes that continue Caps Word, without shifting. +        case KC_1 ... KC_0: +        case KC_BSPC: +        case KC_DEL: +        case KC_UNDS: +            return true; + +        default: +            return false;  // Deactivate Caps Word. +    } +} +``` + + +### Representing Caps Word state :id=representing-caps-word-state + +Define `caps_word_set_user(bool active)` to get callbacks when Caps Word turns +on or off. This is useful to represent the current Caps Word state, e.g. by +setting an LED or playing a sound. In your keymap, define + +```c +void caps_word_set_user(bool active) { +    if (active) { +        // Do something when Caps Word activates. +    } else { +        // Do something when Caps Word deactivates. +    } +} +``` + diff --git a/docs/keycodes.md b/docs/keycodes.md index 10652bdb2f..bd5af32dd3 100644 --- a/docs/keycodes.md +++ b/docs/keycodes.md @@ -269,6 +269,14 @@ See also: [Bluetooth](feature_bluetooth.md)  |`OUT_USB` |USB only                                      |  |`OUT_BT`  |Bluetooth only                                | +## Caps Word :id=caps-word + +See also: [Caps Word](feature_caps_word.md) + +|Key        |Aliases  |Description                   | +|-----------|---------|------------------------------| +|`CAPS_WORD`|`CAPSWRD`|Toggles Caps Word             | +  ## Dynamic Macros :id=dynamic-macros  See also: [Dynamic Macros](feature_dynamic_macros.md) | 
