caps_word.md (7490B)
1 # Caps Word 2 3 It is often useful to type a single word in all capitals, for instance 4 abbreviations like "QMK", or in code, identifiers like `KC_SPC`. "Caps Word" is 5 a modern alternative to Caps Lock: 6 7 * While active, letters are capitalized and `-` becomes `_`. The `_` makes it easier 8 to type constant names (eg 'PROGRAM\_CONSTANTS'). 9 10 * Caps Word automatically disables 11 itself at the end of the word. That is, it stops by default once a space or 12 any key other than `KC_A`--`KC_Z`, `KC_0`--`KC_9`, `KC_MINS`, `KC_UNDS`, 13 `KC_DELETE`, or `KC_BACKSPACE` is pressed. Caps Word also disables itself if 14 the keyboard is idle for 5 seconds. This is configurable, see below. 15 16 * To avoid requiring a dedicated key for Caps Word, there is an option 17 (`BOTH_SHIFTS_TURNS_ON_CAPS_WORD`) to activate Caps Word by simultaneously 18 pressing both shift keys. See below for other options. 19 20 * The implementation does not use the Caps Lock (`KC_CAPS`) keycode. Caps Word 21 works even if you're remapping Caps Lock at the OS level to Ctrl or something 22 else, as Emacs and Vim users often do. As a consequence, Caps Word does not 23 follow the typical Caps Lock behaviour and may thus act in potentially 24 unexpected ways, especially when using an *OS* keyboard layout other than US 25 or UK. For example, Dvorak's <kbd>, <</kbd> key (`DV_COMM` aka `KC_W`) will 26 get shifted because Caps Word interprets that keycode as the letter 'W' by 27 default, the Spanish <kbd>Ñ</kbd> key (`ES_NTIL` aka `KC_SCLN`) will not get 28 capitalized because Caps Word interprets it as the semicolon ';' punctuation 29 character, and the US hyphen key (`KC_MINS`), while unaffected by Caps Lock, 30 is shifted by Caps Word. However, this is not really a problem because you can 31 [configure which keys should Caps Word 32 shift](#configure-which-keys-are-word-breaking). 33 34 35 ## How do I enable Caps Word {#how-do-i-enable-caps-word} 36 37 In your `rules.mk`, add: 38 39 ```make 40 CAPS_WORD_ENABLE = yes 41 ``` 42 43 Next, use one the following methods to activate Caps Word: 44 45 * **Activate by pressing a key**: Use the `QK_CAPS_WORD_TOGGLE` keycode (short 46 alias `CW_TOGG`) in your keymap. 47 48 * **Activate by pressing Left Shift + Right Shift**: Add `#define 49 BOTH_SHIFTS_TURNS_ON_CAPS_WORD` to config.h. You may also need to disable or 50 reconfigure Command, details below. Then, simultaneously pressing both left 51 and right shifts turns on Caps Word. This method works with the plain 52 `KC_LSFT` and `KC_RSFT` keycodes as well as one-shot shifts and Space Cadet 53 shifts. If your shift keys are mod-taps, hold both shift mod-tap keys until 54 the tapping term, then release them. 55 56 * **Activate by double tapping Left Shift**: Add `#define 57 DOUBLE_TAP_SHIFT_TURNS_ON_CAPS_WORD` config.h. Then, double tapping Left Shift 58 turns on Caps Word. This method works with `KC_LSFT` or one-shot Left Shift 59 `OSM(MOD_LSFT)`. To count as a double tap, the maximum time in milliseconds 60 between taps is `TAPPING_TERM`, or if using `TAPPING_TERM_PER_KEY`, the time 61 returned by `get_tapping_term()` for the shift keycode being tapped. 62 63 * **Custom activation**: You can activate Caps Word from code by calling 64 `caps_word_on()`. This may be used to activate Caps Word through [a 65 combo](combo) or [tap dance](tap_dance) or any means 66 you like. 67 68 ### Troubleshooting: Command {#troubleshooting-command} 69 70 When using `BOTH_SHIFTS_TURNS_ON_CAPS_WORD`, you might see a compile message 71 **"BOTH_SHIFTS_TURNS_ON_CAPS_WORD and Command should not be enabled at the same 72 time, since both use the Left Shift + Right Shift key combination."** 73 74 Many keyboards enable the [Command feature](command), which by 75 default is also activated using the Left Shift + Right Shift key combination. To 76 fix this conflict, please disable Command by adding in rules.mk: 77 78 ```make 79 COMMAND_ENABLE = no 80 ``` 81 82 Or configure Command to use another key combination like Left Ctrl + Right Ctrl 83 by defining `IS_COMMAND()` in config.h: 84 85 ```c 86 // Activate Command with Left Ctrl + Right Ctrl. 87 #define IS_COMMAND() (get_mods() == MOD_MASK_CTRL) 88 ``` 89 90 91 ## Customizing Caps Word {#customizing-caps-word} 92 93 ### Invert on shift {#invert-on-shift} 94 95 By default, Caps Word turns off when Shift keys are pressed, considering them as 96 word-breaking. Alternatively with the `CAPS_WORD_INVERT_ON_SHIFT` option, 97 pressing the Shift key continues Caps Word and inverts the shift state. This 98 is convenient for uncapitalizing one or a few letters within a word, for 99 example with Caps Word on, typing "D, B, Shift+A, Shift+A, S" produces "DBaaS", 100 or typing "P, D, F, Shift+S" produces "PDFs". 101 102 Enable it by adding in config.h 103 104 ```c 105 #define CAPS_WORD_INVERT_ON_SHIFT 106 ``` 107 108 This option works with regular Shift keys `KC_LSFT` and `KC_RSFT`, mod-tap Shift 109 keys, and one-shot Shift keys. Note that while Caps Word is on, one-shot Shift 110 keys behave like regular Shift keys, and have effect only while they are held. 111 112 113 ### Idle timeout {#idle-timeout} 114 115 Caps Word turns off automatically if no keys are pressed for 116 `CAPS_WORD_IDLE_TIMEOUT` milliseconds. The default is 5000 (5 seconds). 117 Configure the timeout duration in config.h, for instance 118 119 ```c 120 #define CAPS_WORD_IDLE_TIMEOUT 3000 // 3 seconds. 121 ``` 122 123 Setting `CAPS_WORD_IDLE_TIMEOUT` to 0 configures Caps Word to never time out. 124 Caps Word then remains active indefinitely until a word breaking key is pressed. 125 126 127 ### Functions {#functions} 128 129 Functions to manipulate Caps Word: 130 131 | Function | Description | 132 |-------------------------|------------------------------------------------| 133 | `caps_word_on()` | Turns Caps Word on. | 134 | `caps_word_off()` | Turns Caps Word off. | 135 | `caps_word_toggle()` | Toggles Caps Word. | 136 | `is_caps_word_on()` | Returns true if Caps Word is currently on. | 137 138 139 ### Configure which keys are "word breaking" {#configure-which-keys-are-word-breaking} 140 141 You can define the `caps_word_press_user(uint16_t keycode)` callback to 142 configure which keys should be shifted and which keys are considered "word 143 breaking" and stop Caps Word. 144 145 The callback is called on every key press while Caps Word is active. When the 146 key should be shifted (that is, a letter key), the callback should call 147 `add_weak_mods(MOD_BIT(KC_LSFT))` to shift the key. Returning true continues the 148 current "word," while returning false is "word breaking" and deactivates Caps 149 Word. The default callback is 150 151 ```c 152 bool caps_word_press_user(uint16_t keycode) { 153 switch (keycode) { 154 // Keycodes that continue Caps Word, with shift applied. 155 case KC_A ... KC_Z: 156 case KC_MINS: 157 add_weak_mods(MOD_BIT(KC_LSFT)); // Apply shift to next key. 158 return true; 159 160 // Keycodes that continue Caps Word, without shifting. 161 case KC_1 ... KC_0: 162 case KC_BSPC: 163 case KC_DEL: 164 case KC_UNDS: 165 return true; 166 167 default: 168 return false; // Deactivate Caps Word. 169 } 170 } 171 ``` 172 173 174 ### Representing Caps Word state {#representing-caps-word-state} 175 176 Define `caps_word_set_user(bool active)` to get callbacks when Caps Word turns 177 on or off. This is useful to represent the current Caps Word state, e.g. by 178 setting an LED or playing a sound. In your keymap, define 179 180 ```c 181 void caps_word_set_user(bool active) { 182 if (active) { 183 // Do something when Caps Word activates. 184 } else { 185 // Do something when Caps Word deactivates. 186 } 187 } 188 ``` 189