mirror of
https://github.com/qmk/qmk_firmware.git
synced 2025-02-27 01:56:43 +00:00
16 lines
17 KiB
JavaScript
16 lines
17 KiB
JavaScript
import { _ as _export_sfc, c as createElementBlock, o as openBlock, a8 as createStaticVNode } from "./chunks/framework.DyMmIvSC.js";
|
||
const __pageData = JSON.parse('{"title":"Caps Word","description":"","frontmatter":{},"headers":[],"relativePath":"features/caps_word.md","filePath":"features/caps_word.md"}');
|
||
const _sfc_main = { name: "features/caps_word.md" };
|
||
const _hoisted_1 = /* @__PURE__ */ createStaticVNode('<h1 id="caps-word" tabindex="-1">Caps Word <a class="header-anchor" href="#caps-word" aria-label="Permalink to "Caps Word""></a></h1><p>It is often useful to type a single word in all capitals, for instance abbreviations like "QMK", or in code, identifiers like <code>KC_SPC</code>. "Caps Word" is a modern alternative to Caps Lock:</p><ul><li><p>While active, letters are capitalized and <code>-</code> becomes <code>_</code>. The <code>_</code> makes it easier to type constant names (eg 'PROGRAM_CONSTANTS').</p></li><li><p>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 <code>KC_A</code>--<code>KC_Z</code>, <code>KC_0</code>--<code>KC_9</code>, <code>KC_MINS</code>, <code>KC_UNDS</code>, <code>KC_DELETE</code>, or <code>KC_BACKSPACE</code> is pressed. Caps Word also disables itself if the keyboard is idle for 5 seconds. This is configurable, see below.</p></li><li><p>To avoid requiring a dedicated key for Caps Word, there is an option (<code>BOTH_SHIFTS_TURNS_ON_CAPS_WORD</code>) to activate Caps Word by simultaneously pressing both shift keys. See below for other options.</p></li><li><p>The implementation does not use the Caps Lock (<code>KC_CAPS</code>) 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 <em>OS</em> keyboard layout other than US or UK. For example, Dvorak's <kbd>, <</kbd> key (<code>DV_COMM</code> aka <code>KC_W</code>) will get shifted because Caps Word interprets that keycode as the letter 'W' by default, the Spanish <kbd>Ñ</kbd> key (<code>ES_NTIL</code> aka <code>KC_SCLN</code>) will not get capitalized because Caps Word interprets it as the semicolon ';' punctuation character, and the US hyphen key (<code>KC_MINS</code>), while unaffected by Caps Lock, is shifted by Caps Word. However, this is not really a problem because you can <a href="#configure-which-keys-are-word-breaking">configure which keys should Caps Word shift</a>.</p></li></ul><h2 id="how-do-i-enable-caps-word" tabindex="-1">How do I enable Caps Word <a class="header-anchor" href="#how-do-i-enable-caps-word" aria-label="Permalink to "How do I enable Caps Word {#how-do-i-enable-caps-word}""></a></h2><p>In your <code>rules.mk</code>, add:</p><div class="language-make vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">make</span><pre class="shiki shiki-themes github-light github-dark vp-code"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">CAPS_WORD_ENABLE = yes</span></span></code></pre></div><p>Next, use one the following methods to activate Caps Word:</p><ul><li><p><strong>Activate by pressing a key</strong>: Use the <code>QK_CAPS_WORD_TOGGLE</code> keycode (short alias <code>CW_TOGG</code>) in your keymap.</p></li><li><p><strong>Activate by pressing Left Shift + Right Shift</strong>: Add <code>#define BOTH_SHIFTS_TURNS_ON_CAPS_WORD</code> 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 <code>KC_LSFT</code> and <code>KC_RSFT</code> 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.</p></li><li><p><strong>Activate by double tapping Left Shift</strong>: Add <code>#define DOUBLE_TAP_SHIFT_TURNS_ON_CAPS_WORD</code> config.h. Then, double tapping Left Shift turns on Caps Word. This method works with <code>KC_LSFT</code> or one-shot Left Shift <code>OSM(MOD_LSFT)</code>. To count as a double tap, the maximum time in milliseconds between taps is <code>TAPPING_TERM</code>, or if using <code>TAPPING_TERM_PER_KEY</code>, the time returned by <code>get_tapping_term()</code> for the shift keycode being tapped.</p></li><li><p><strong>Custom activation</strong>: You can activate Caps Word from code by calling <code>caps_word_on()</code>. This may be used to activate Caps Word through <a href="./combo">a combo</a> or <a href="./tap_dance">tap dance</a> or any means you like.</p></li></ul><h3 id="troubleshooting-command" tabindex="-1">Troubleshooting: Command <a class="header-anchor" href="#troubleshooting-command" aria-label="Permalink to "Troubleshooting: Command {#troubleshooting-command}""></a></h3><p>When using <code>BOTH_SHIFTS_TURNS_ON_CAPS_WORD</code>, you might see a compile message <strong>"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."</strong></p><p>Many keyboards enable the <a href="./command">Command feature</a>, 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:</p><div class="language-make vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">make</span><pre class="shiki shiki-themes github-light github-dark vp-code"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">COMMAND_ENABLE = no</span></span></code></pre></div><p>Or configure Command to use another key combination like Left Ctrl + Right Ctrl by defining <code>IS_COMMAND()</code> in config.h:</p><div class="language-c vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">c</span><pre class="shiki shiki-themes github-light github-dark vp-code"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// Activate Command with Left Ctrl + Right Ctrl.</span></span>\n<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">#define</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> IS_COMMAND</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">() (</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">get_mods</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">() </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">==</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> MOD_MASK_CTRL)</span></span></code></pre></div><h2 id="customizing-caps-word" tabindex="-1">Customizing Caps Word <a class="header-anchor" href="#customizing-caps-word" aria-label="Permalink to "Customizing Caps Word {#customizing-caps-word}""></a></h2><h3 id="invert-on-shift" tabindex="-1">Invert on shift <a class="header-anchor" href="#invert-on-shift" aria-label="Permalink to "Invert on shift {#invert-on-shift}""></a></h3><p>By default, Caps Word turns off when Shift keys are pressed, considering them as word-breaking. Alternatively with the <code>CAPS_WORD_INVERT_ON_SHIFT</code> 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".</p><p>Enable it by adding in config.h</p><div class="language-c vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">c</span><pre class="shiki shiki-themes github-light github-dark vp-code"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">#define</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> CAPS_WORD_INVERT_ON_SHIFT</span></span></code></pre></div><p>This option works with regular Shift keys <code>KC_LSFT</code> and <code>KC_RSFT</code>, 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.</p><h3 id="idle-timeout" tabindex="-1">Idle timeout <a class="header-anchor" href="#idle-timeout" aria-label="Permalink to "Idle timeout {#idle-timeout}""></a></h3><p>Caps Word turns off automatically if no keys are pressed for <code>CAPS_WORD_IDLE_TIMEOUT</code> milliseconds. The default is 5000 (5 seconds). Configure the timeout duration in config.h, for instance</p><div class="language-c vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">c</span><pre class="shiki shiki-themes github-light github-dark vp-code"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">#define</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> CAPS_WORD_IDLE_TIMEOUT</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> 3000</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> // 3 seconds.</span></span></code></pre></div><p>Setting <code>CAPS_WORD_IDLE_TIMEOUT</code> to 0 configures Caps Word to never time out. Caps Word then remains active indefinitely until a word breaking key is pressed.</p><h3 id="functions" tabindex="-1">Functions <a class="header-anchor" href="#functions" aria-label="Permalink to "Functions {#functions}""></a></h3><p>Functions to manipulate Caps Word:</p><table><thead><tr><th>Function</th><th>Description</th></tr></thead><tbody><tr><td><code>caps_word_on()</code></td><td>Turns Caps Word on.</td></tr><tr><td><code>caps_word_off()</code></td><td>Turns Caps Word off.</td></tr><tr><td><code>caps_word_toggle()</code></td><td>Toggles Caps Word.</td></tr><tr><td><code>is_caps_word_on()</code></td><td>Returns true if Caps Word is currently on.</td></tr></tbody></table><h3 id="configure-which-keys-are-word-breaking" tabindex="-1">Configure which keys are "word breaking" <a class="header-anchor" href="#configure-which-keys-are-word-breaking" aria-label="Permalink to "Configure which keys are "word breaking" {#configure-which-keys-are-word-breaking}""></a></h3><p>You can define the <code>caps_word_press_user(uint16_t keycode)</code> callback to configure which keys should be shifted and which keys are considered "word breaking" and stop Caps Word.</p><p>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 <code>add_weak_mods(MOD_BIT(KC_LSFT))</code> to shift the key. Returning true continues the current "word," while returning false is "word breaking" and deactivates Caps Word. The default callback is</p><div class="language-c vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">c</span><pre class="shiki shiki-themes github-light github-dark vp-code"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">bool</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> caps_word_press_user</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">uint16_t</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;"> keycode</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) {</span></span>\n<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> switch</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> (keycode) {</span></span>\n<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> // Keycodes that continue Caps Word, with shift applied.</span></span>\n<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> case</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> KC_A ... KC_Z:</span></span>\n<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> case</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> KC_MINS:</span></span>\n<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> add_weak_mods</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">MOD_BIT</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(KC_LSFT));</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> // Apply shift to next key.</span></span>\n<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> return</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> true</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>\n<span class="line"></span>\n<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> // Keycodes that continue Caps Word, without shifting.</span></span>\n<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> case</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> KC_1 ... KC_0:</span></span>\n<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> case</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> KC_BSPC:</span></span>\n<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> case</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> KC_DEL:</span></span>\n<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> case</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> KC_UNDS:</span></span>\n<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> return</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> true</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>\n<span class="line"></span>\n<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>\n<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> return</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> false</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> // Deactivate Caps Word.</span></span>\n<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span>\n<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><h3 id="representing-caps-word-state" tabindex="-1">Representing Caps Word state <a class="header-anchor" href="#representing-caps-word-state" aria-label="Permalink to "Representing Caps Word state {#representing-caps-word-state}""></a></h3><p>Define <code>caps_word_set_user(bool active)</code> 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</p><div class="language-c vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">c</span><pre class="shiki shiki-themes github-light github-dark vp-code"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">void</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> caps_word_set_user</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">bool</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;"> active</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) {</span></span>\n<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> if</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> (active) {</span></span>\n<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> // Do something when Caps Word activates.</span></span>\n<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">else</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>\n<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> // Do something when Caps Word deactivates.</span></span>\n<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span>\n<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div>', 34);
|
||
const _hoisted_35 = [
|
||
_hoisted_1
|
||
];
|
||
function _sfc_render(_ctx, _cache, $props, $setup, $data, $options) {
|
||
return openBlock(), createElementBlock("div", null, _hoisted_35);
|
||
}
|
||
const caps_word = /* @__PURE__ */ _export_sfc(_sfc_main, [["render", _sfc_render]]);
|
||
export {
|
||
__pageData,
|
||
caps_word as default
|
||
};
|