diff options
author | Ryan <[email protected]> | 2024-06-02 12:42:24 +1000 |
---|---|---|
committer | GitHub <[email protected]> | 2024-06-02 12:42:24 +1000 |
commit | 78a0adfbb4d2c4e12f93f2a62ded0020d406243e (patch) | |
tree | e6e123b36569559233025add654580e090dc0154 /docs/features/caps_word.md | |
parent | fa6d23235bf429446250cd5212e209d5fbfdbac2 (diff) | |
download | qmk_firmware-78a0adfbb4d2c4e12f93f2a62ded0020d406243e.tar.gz qmk_firmware-78a0adfbb4d2c4e12f93f2a62ded0020d406243e.zip |
[docs] Organize driver & feature docs into subfolders (#23848)
Co-authored-by: Nick Brassel <[email protected]>
Diffstat (limited to 'docs/features/caps_word.md')
-rw-r--r-- | docs/features/caps_word.md | 189 |
1 files changed, 189 insertions, 0 deletions
diff --git a/docs/features/caps_word.md b/docs/features/caps_word.md new file mode 100644 index 0000000000..15361aab96 --- /dev/null +++ b/docs/features/caps_word.md @@ -0,0 +1,189 @@ +# 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: + +* While active, letters are capitalized and `-` becomes `_`. The `_` makes it easier + to type constant names (eg 'PROGRAM\_CONSTANTS'). + +* 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 `KC_A`--`KC_Z`, `KC_0`--`KC_9`, `KC_MINS`, `KC_UNDS`, + `KC_DELETE`, or `KC_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. As a consequence, Caps Word does not + follow the typical Caps Lock behaviour and may thus act in potentially + unexpected ways, especially when using an *OS* keyboard layout other than US + or UK. For example, Dvorak's <kbd>, <</kbd> key (`DV_COMM` aka `KC_W`) will + get shifted because Caps Word interprets that keycode as the letter 'W' by + default, the Spanish <kbd>Ñ</kbd> key (`ES_NTIL` aka `KC_SCLN`) will not get + capitalized because Caps Word interprets it as the semicolon ';' punctuation + character, and the US hyphen key (`KC_MINS`), while unaffected by Caps Lock, + is shifted by Caps Word. However, this is not really a problem because you can + [configure which keys should Caps Word + shift](#configure-which-keys-are-word-breaking). + + +## How do I enable Caps Word {#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 `QK_CAPS_WORD_TOGGLE` keycode (short + alias `CW_TOGG`) 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](combo) or [tap dance](tap_dance) or any means + you like. + +### Troubleshooting: Command {#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](command), 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 {#customizing-caps-word} + +### Invert on shift {#invert-on-shift} + +By default, Caps Word turns off when Shift keys are pressed, considering them as +word-breaking. Alternatively with the `CAPS_WORD_INVERT_ON_SHIFT` option, +pressing the Shift key continues Caps Word and inverts the shift state. This +is convenient for uncapitalizing one or a few letters within a word, for +example with Caps Word on, typing "D, B, Shift+A, Shift+A, S" produces "DBaaS", +or typing "P, D, F, Shift+S" produces "PDFs". + +Enable it by adding in config.h + +```c +#define CAPS_WORD_INVERT_ON_SHIFT +``` + +This option works with regular Shift keys `KC_LSFT` and `KC_RSFT`, mod-tap Shift +keys, and one-shot Shift keys. Note that while Caps Word is on, one-shot Shift +keys behave like regular Shift keys, and have effect only while they are held. + + +### Idle timeout {#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 {#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" {#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 {#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. + } +} +``` + |