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 , < key (DV_COMM
aka KC_W
) will
get shifted because Caps Word interprets that keycode as the letter 'W' by
default, the Spanish Ñ 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.
In your rules.mk
, add:
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 or tap dance or any means
you like.
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, 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:
COMMAND_ENABLE = no
Or configure Command to use another key combination like Left Ctrl + Right Ctrl
by defining IS_COMMAND()
in config.h:
// Activate Command with Left Ctrl + Right Ctrl.
#define IS_COMMAND() (get_mods() == MOD_MASK_CTRL)
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
#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.
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
#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 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. |
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
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.
}
}
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
void caps_word_set_user(bool active) {
if (active) {
// Do something when Caps Word activates.
} else {
// Do something when Caps Word deactivates.
}
}