<spanclass="line"><spanstyle="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> NULL</span><spanstyle="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> // Null terminate the array of overrides!</span></span>
<spanclass="line"><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">};</span></span></code></pre></div><h2id="intermediate-difficulty-examples"tabindex="-1">Intermediate Difficulty Examples <aclass="header-anchor"href="#intermediate-difficulty-examples"aria-label="Permalink to "Intermediate Difficulty Examples {#intermediate-difficulty-examples}""></a></h2><h3id="media-controls-amp-screen-brightness"tabindex="-1">Media Controls & Screen Brightness <aclass="header-anchor"href="#media-controls-amp-screen-brightness"aria-label="Permalink to "Media Controls & Screen Brightness {#media-controls-amp-screen-brightness}""></a></h3><p>In this example a single key is configured to control media, volume and screen brightness by using key overrides.</p><ul><li>The key is set to send <code>play/pause</code> in the keymap.</li></ul><p>The following key overrides will be configured:</p><ul><li><code>Ctrl</code> + <code>play/pause</code> will send <code>next track</code>.</li><li><code>Ctrl</code> + <code>Shift</code> + <code>play/pause</code> will send <code>previous track</code>.</li><li><code>Alt</code> + <code>play/pause</code> will send <code>volume up</code>.</li><li><code>Alt</code> + <code>Shift</code> + <code>play/pause</code> will send <code>volume down</code>.</li><li><code>Ctrl</code> + <code>Alt</code> + <code>play/pause</code> will send <code>brightness up</code>.</li><li><code>Ctrl</code> + <code>Alt</code> + <code>Shift</code> + <code>play/pause</code> will send <code>brightness down</code>.</li></ul><divclass="language-c vp-adaptive-theme"><buttontitle="Copy Code"class="copy"></button><spanclass="lang">c</span><preclass="shiki shiki-themes github-light github-dark vp-code"><code><spanclass="line"><spanstyle="--shiki-light:#D73A49;--shiki-dark:#F97583;">const</span><spanstyle="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> key_override_t</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> next_track_override </span><spanstyle="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"></span></span>
<spanclass="line"><spanstyle="--shiki-light:#D73A49;--shiki-dark:#F97583;"> ~</span><spanstyle="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">0</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span><spanstyle="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> // Activate on all layers</span></span>
<spanclass="line"><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> MOD_MASK_SA,</span><spanstyle="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> // Do not activate when shift or alt are pressed</span></span>
<spanclass="line"><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> ko_option_no_reregister_trigger);</span><spanstyle="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> // Specifies that the play key is not registered again after lifting ctrl</span></span>
<spanclass="line"><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">};</span></span></code></pre></div><h3id="flexible-macos-friendly-grave-escape"tabindex="-1">Flexible macOS-friendly Grave Escape <aclass="header-anchor"href="#flexible-macos-friendly-grave-escape"aria-label="Permalink to "Flexible macOS-friendly Grave Escape {#flexible-macos-friendly-grave-escape}""></a></h3><p>The <ahref="./grave_esc">Grave Escape feature</a> is limited in its configurability and has <ahref="./grave_esc#caveats">bugs when used on macOS</a>. Key overrides can be used to achieve a similar functionality as Grave Escape, but with more customization and without bugs on macOS.</p><divclass="language-c vp-adaptive-theme"><buttontitle="Copy Code"class="copy"></button><spanclass="lang">c</span><preclass="shiki shiki-themes github-light github-dark vp-code"><code><spanclass="line"><spanstyle="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// Shift + esc = ~</span></span>
<spanclass="line"><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">};</span></span></code></pre></div><p>In addition to not encountering unexpected bugs on macOS, you can also change the behavior as you wish. Instead setting <code>GUI</code> + <code>ESC</code> = <code>`</code> you may change it to an arbitrary other modifier, for example <code>Ctrl</code> + <code>ESC</code> = <code>`</code>.</p><h2id="advanced-examples"tabindex="-1">Advanced Examples <aclass="header-anchor"href="#advanced-examples"aria-label="Permalink to "Advanced Examples {#advanced-examples}""></a></h2><h3id="modifiers-as-layer-keys"tabindex="-1">Modifiers as Layer Keys <aclass="header-anchor"href="#modifiers-as-layer-keys"aria-label="Permalink to "Modifiers as Layer Keys {#modifiers-as-layer-keys}""></a></h3><p>Do you really need a dedicated key to toggle your fn layer? With key overrides, perhaps not. This example shows how you can configure to use <code>rGUI</code> + <code>rAlt</code> (right GUI and right alt) to access a momentary layer like an fn layer. With this you completely eliminate the need to use a dedicated layer key. Of course the choice of modifier keys can be changed as needed, <code>rGUI</code> + <code>rAlt</code> is just an example here.</p><divclass="language-c vp-adaptive-theme"><buttontitle="Copy Code"class="copy"></button><spanclass="lang">c</span><preclass="shiki shiki-themes github-light github-dark vp-code"><code><spanclass="line"><spanstyle="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// This is called when the override activates and deactivates. Enable the fn layer on activation and disable on deactivation</span></span>
<spanclass="line"><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> .enabled </span><spanstyle="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><spanstyle="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> NULL</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">};</span></span></code></pre></div><h2id="keycodes"tabindex="-1">Keycodes <aclass="header-anchor"href="#keycodes"aria-label="Permalink to "Keycodes {#keycodes}""></a></h2><table><thead><tr><th>Keycode</th><th>Aliases</th><th>Description</th></tr></thead><tbody><tr><td><code>QK_KEY_OVERRIDE_TOGGLE</code></td><td><code>KO_TOGG</code></td><td>Toggle key overrides</td></tr><tr><td><code>QK_KEY_OVERRIDE_ON</code></td><td><code>KO_ON</code></td><td>Turn on key overrides</td></tr><tr><td><code>QK_KEY_OVERRIDE_OFF</code></td><td><code>KO_OFF</code></td><td>Turn off key overrides</td></tr></tbody></table><h2id="reference-for-key_override_t"tabindex="-1">Reference for <code>key_override_t</code><aclass="header-anchor"href="#reference-for-key_override_t"aria-label="Permalink to "Reference for `key_override_t` {#reference-for-key_override_t}""></a></h2><p>Advanced users may need more customization than what is offered by the simple <code>ko_make</code> initializers. For this, directly create a <code>key_override_t</code> value and set all members. Below is a reference for all members of <code>key_override_t</code>.</p><table><thead><tr><th>Member</th><th>Description</th></tr></thead><tbody><tr><td><code>uint16_t trigger</code></td><td>The non-modifier keycode that triggers the override. This keycode, and the necessary modifiers (<code>trigger_mods</code>) must be pressed to activate this override. Set this to the keycode of the key that should activate the override. Set to <code>KC_NO</code> to require only the necessary modifiers to be pressed and no non-modifier.</td></tr><tr><td><code>uint8_t trigger_mods</code></td><td>Which mods need to be down for activation. If both sides of a modifier are set (e.g. left ctrl and right ctrl) then only one is required to be pressed (e.g. left ctrl suffices). Use the <code>MOD_MASK_XXX</code> and <code>MOD_BIT()</code> macros for this.</td></tr><tr><td><code>layer_state_t layers</code></td><td>This is a BITMASK (!), defining which layers this override applies to. To use this override on layer i set the ith bit <code>(1 << i)</code>.</td></tr><tr><td><code>uint8_t negative_mod_mask</code></td><td>Which modifiers cannot be down. It must hold that <code>(active_modifiers & negative_mod_mask) == 0</code>, otherwise the key override will not be activated. An active override will be deactivated once this is no longer true.</td></tr><tr><td><code>uint8_t suppressed_mods</code></td><td>Modifiers to 'suppress' while the override is active. To suppress a modifier means that even though the modifier key is held down, the host OS sees the modifier as not pressed. Can be used to suppress the trigger modifiers, as a trivial example.</td></tr><tr><td><code>uint16_t replacement</code></td><td>The complex keycode to send as replacement when this override is triggered. This can be a simple keycode, a key-modifier combination (e.g. <code>C(KC_A)</code>), or <code>KC_NO</code> (to register no replacement keycode). Use in combination with suppressed_mods to get the correct modifiers to be sent.</td></tr><tr><td><code>ko_option_t options</code></td><td>Options controlling the behavior of the override, such as what actions are allowed to activate the override.</td></tr><tr><td><code>bool (*custom_action)(bool activated, void *context)</code></td><td>If not NULL, this function will be called right before the replacement key is registered, along with the provided context and a flag indicating whether the override was activated or deactivated. This function allows you to run some custom actions for specific key overrides. If you return <code>false</code>, the replacement key is not registered/unregistered as it would normally. Return
<spanclass="line"><spanstyle="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// Neutralize left alt, left GUI, right GUI and left Control+Shift</span></span>
<spanclass="line"><spanstyle="--shiki-light:#D73A49;--shiki-dark:#F97583;">#define</span><spanstyle="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> MODS_TO_NEUTRALIZE</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { </span><spanstyle="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">MOD_BIT</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(KC_LEFT_ALT), </span><spanstyle="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">MOD_BIT</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(KC_LEFT_GUI), </span><spanstyle="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">MOD_BIT</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(KC_RIGHT_GUI), </span><spanstyle="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">MOD_BIT</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(KC_LEFT_CTRL)</span><spanstyle="--shiki-light:#D73A49;--shiki-dark:#F97583;">|</span><spanstyle="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">MOD_BIT</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(KC_LEFT_SHIFT) }</span></span></code></pre></div><divclass="warning custom-block"><pclass="custom-block-title">WARNING</p><p>Do not use <code>MOD_xxx</code> constants like <code>MOD_LSFT</code> or <code>MOD_RALT</code>, since they're 5-bit packed bit-arrays while <code>MODS_TO_NEUTRALIZE</code> expects a list of 8-bit packed bit-arrays. Use <code>MOD_BIT(<kc>)</code> or <code>MOD_MASK_xxx</code> instead.</p></div></div></div></main><footerclass="VPDocFooter"data-v-39a288b8data-v-09de1c0f><!--[--><!--]--><!----><navclass="prev-next"data-v-09de1c0f><divclass="pager"data-v-09de1c0f><aclass="VPLink link pager-link prev"href="/features/key_lock"data-v-09de1c0f><!--[--><spanclass="desc"data-v-09de1c0f>Previous page</span><spanclass="title"data-v-09de1c0f>Key Lock</span><!--]--></a></div><divclass="pager"data-v-09de1c0f><aclass="VPLink link pager-link next"href="/feature_layers"data-v-09de1c0f><!--[--><spanclass="desc"data-v-09de1c0f>Next page</span><spanclass="title"data-v-09de1c0f>Layers</span><!--]--></a></div></nav></footer><!--[--><!--]--></div></div></div><!--[--><!--]--></div></div><!----><!--[--><!--]--></div></div>
