mirror of
https://github.com/qmk/qmk_firmware.git
synced 2025-02-27 01:56:43 +00:00
16 lines
19 KiB
JavaScript
16 lines
19 KiB
JavaScript
import { _ as _export_sfc, c as createElementBlock, o as openBlock, a8 as createStaticVNode } from "./chunks/framework.B9AX-CPi.js";
|
||
const __pageData = JSON.parse('{"title":"List of Useful Core Functions To Make Your Keyboard Better","description":"","frontmatter":{},"headers":[],"relativePath":"ref_functions.md","filePath":"ref_functions.md","lastUpdated":null}');
|
||
const _sfc_main = { name: "ref_functions.md" };
|
||
const _hoisted_1 = /* @__PURE__ */ createStaticVNode('<h1 id="list-of-useful-core-functions-to-make-your-keyboard-better" tabindex="-1">List of Useful Core Functions To Make Your Keyboard Better <a class="header-anchor" href="#list-of-useful-core-functions-to-make-your-keyboard-better" aria-label="Permalink to "List of Useful Core Functions To Make Your Keyboard Better""></a></h1><p>There are a lot of hidden functions in QMK that are incredibly useful, or may add a bit of functionality that you've been wanting. Functions that are specific to certain features are not included here, as those will be on their respective feature page.</p><h2 id="olkb-tri-layers" tabindex="-1">(OLKB) Tri Layers <a class="header-anchor" href="#olkb-tri-layers" aria-label="Permalink to "(OLKB) Tri Layers {#olkb-tri-layers}""></a></h2><p>There are actually separate functions that you can use there, depending on what you're after.</p><h3 id="update-tri-layer-x-y-z" tabindex="-1"><code>update_tri_layer(x, y, z)</code> <a class="header-anchor" href="#update-tri-layer-x-y-z" aria-label="Permalink to "`update_tri_layer(x, y, z)`""></a></h3><p>The first is the <code>update_tri_layer(x, y, z)</code> function. This function check to see if layers <code>x</code> and <code>y</code> are both on. If they are both on, then it turns on layer <code>z</code>. Otherwise, if both <code>x</code> and <code>y</code> are not both on (either only one is, or neither is), then it turns off layer <code>z</code>.</p><p>This function is useful if you want to create specific keys that have this functionality, but other layer keycodes won't do this.</p><h4 id="example" tabindex="-1">Example <a class="header-anchor" href="#example" aria-label="Permalink to "Example""></a></h4><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;"> process_record_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 style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">keyrecord_t</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> *</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">record</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:#D73A49;--shiki-dark:#F97583;"> case</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> LOWER:</span></span>\n<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> if</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> (record</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">-></span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">event.pressed) {</span></span>\n<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> layer_on</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(_LOWER);</span></span>\n<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> update_tri_layer</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(_LOWER, _RAISE, _ADJUST);</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:#6F42C1;--shiki-dark:#B392F0;"> layer_off</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(_LOWER);</span></span>\n<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> update_tri_layer</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(_LOWER, _RAISE, _ADJUST);</span></span>\n<span class="line"><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>\n<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> case</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> RAISE:</span></span>\n<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> if</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> (record</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">-></span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">event.pressed) {</span></span>\n<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> layer_on</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(_RAISE);</span></span>\n<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> update_tri_layer</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(_LOWER, _RAISE, _ADJUST);</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:#6F42C1;--shiki-dark:#B392F0;"> layer_off</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(_RAISE);</span></span>\n<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> update_tri_layer</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(_LOWER, _RAISE, _ADJUST);</span></span>\n<span class="line"><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>\n<span class="line"><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;"> true</span><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="update-tri-layer-state-state-x-y-z" tabindex="-1"><code>update_tri_layer_state(state, x, y, z)</code> <a class="header-anchor" href="#update-tri-layer-state-state-x-y-z" aria-label="Permalink to "`update_tri_layer_state(state, x, y, z)`""></a></h3><p>The other function is <code>update_tri_layer_state(state, x, y, z)</code>. This function is meant to be called from the <a href="./custom_quantum_functions#layer-change-code"><code>layer_state_set_*</code> functions</a>. This means that any time that you use a keycode to change the layer, this will be checked. So you could use <code>LT(layer, kc)</code> to change the layer and it will trigger the same layer check.</p><p>There are a couple of caveats to this method:</p><ol><li>You cannot access the <code>z</code> layer without having <code>x</code> and <code>y</code> layers on, since if you try to activate just layer <code>z</code>, it will run this code and turn off layer <code>z</code> before you could use it.</li><li>Because layers are processed from the highest number <code>z</code> should be a higher layer than <code>x</code> and <code>y</code> or you may not be able to access it.</li></ol><h4 id="example-1" tabindex="-1">Example <a class="header-anchor" href="#example-1" aria-label="Permalink to "Example""></a></h4><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:#005CC5;--shiki-dark:#79B8FF;">layer_state_t</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> layer_state_set_user</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">layer_state_t</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;"> state</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:#6F42C1;--shiki-dark:#B392F0;"> update_tri_layer_state</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(state, _LOWER, _RAISE, _ADJUST);</span></span>\n<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><p>Alternatively, you don't have to immediately "return" the value. This is useful if you want to add multiple tri layers, or if you want to add additional effects.</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:#005CC5;--shiki-dark:#79B8FF;">layer_state_t</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> layer_state_set_user</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">layer_state_t</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;"> state</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) {</span></span>\n<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> state </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> update_tri_layer_state</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(state, _LOWER, _RAISE, _ADJUST);</span></span>\n<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> state </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> update_tri_layer_state</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(state, _RAISE, _SYMB, _SPECIAL);</span></span>\n<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> return</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> state;</span></span>\n<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><h2 id="setting-the-persistent-default-layer" tabindex="-1">Setting the Persistent Default Layer <a class="header-anchor" href="#setting-the-persistent-default-layer" aria-label="Permalink to "Setting the Persistent Default Layer""></a></h2><p>Do you want to set the default layer, so that it's retained even after you unplug the board? If so, this is the function for you.</p><p>To do this, you would use <code>set_single_persistent_default_layer(layer)</code>. If you have a name defined for your layer, you can use that instead (such as _QWERTY, _DVORAK or _COLEMAK).</p><p>This will set the default layer, update the persistent settings, and play a tune if you have <a href="./features/audio">Audio</a> enabled on your board, and the default layer sounds set.</p><p>To configure the default layer sounds, you would want to define this in your <code>config.h</code> file, like this:</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;"> DEFAULT_LAYER_SONGS</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { </span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">SONG</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(QWERTY_SOUND), </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">\\</span></span>\n<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> SONG</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(COLEMAK_SOUND), </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">\\</span></span>\n<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> SONG</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(DVORAK_SOUND) </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">\\</span></span>\n<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span></code></pre></div><p>If you do not require it to be retained after you unplug the board, use <code>set_single_default_layer(layer)</code> instead.</p><div class="tip custom-block"><p class="custom-block-title">TIP</p><p>There are a large number of predefined songs in <a href="https://github.com/qmk/qmk_firmware/blob/master/quantum/audio/song_list.h" target="_blank" rel="noreferrer">quantum/audio/song_list.h</a> that you can use.</p></div><h2 id="resetting-the-keyboard" tabindex="-1">Resetting the keyboard <a class="header-anchor" href="#resetting-the-keyboard" aria-label="Permalink to "Resetting the keyboard""></a></h2><p>There is the <code>QK_REBOOT</code> or <code>QK_RBT</code> quantum keycode that you can use. But if you want to reset the board as part of a macro, rather than hitting a key separately, you can do that.</p><p>And to do so, add <code>soft_reset_keyboard()</code> to your function or macro.</p><h2 id="reset-to-bootloader" tabindex="-1">Reset to bootloader <a class="header-anchor" href="#reset-to-bootloader" aria-label="Permalink to "Reset to bootloader""></a></h2><p>To reset to the bootloader use <code>QK_BOOTLOADER</code> or <code>QK_BOOT</code> keycode or <code>reset_keyboard()</code> function.</p><h2 id="wiping-the-eeprom-persistent-storage" tabindex="-1">Wiping the EEPROM (Persistent Storage) <a class="header-anchor" href="#wiping-the-eeprom-persistent-storage" aria-label="Permalink to "Wiping the EEPROM (Persistent Storage)""></a></h2><p>If you're having issues with Audio, RGB Underglow, backlighting or keys acting weird, then you can reset the EEPROM (persistent setting storage). To force an EEPROM reset, use the <a href="./quantum_keycodes"><code>EE_CLR</code> keycode</a> or <a href="./features/bootmagic">Bootmagic</a> functionality. If neither of those are an option, then you can use a custom macro to do so.</p><p>To wipe the EEPROM, run <code>eeconfig_init()</code> from your function or macro to reset most of the settings to default.</p><h2 id="tap-random-key" tabindex="-1">Tap random key <a class="header-anchor" href="#tap-random-key" aria-label="Permalink to "Tap random key""></a></h2><p>If you want to send a random character to the host computer, you can use the <code>tap_random_base64()</code> function. This <a href="https://en.wikipedia.org/wiki/Pseudorandom_number_generator" target="_blank" rel="noreferrer">pseudorandomly</a> selects a number between 0 and 63, and then sends a key press based on that selection. (0–25 is <code>A</code>–<code>Z</code>, 26–51 is <code>a</code>–<code>z</code>, 52–61 is <code>0</code>–<code>9</code>, 62 is <code>+</code> and 63 is <code>/</code>).</p><div class="tip custom-block"><p class="custom-block-title">TIP</p><p>Needless to say, but this is <em>not</em> a cryptographically secure method of generating random Base64 keys or passwords.</p></div><h2 id="software-timers" tabindex="-1">Software Timers <a class="header-anchor" href="#software-timers" aria-label="Permalink to "Software Timers""></a></h2><p>It's possible to start timers and read values for time-specific events. Here's an example:</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;">static</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> uint16_t</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> key_timer;</span></span>\n<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">key_timer </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> timer_read</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;">if</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> (</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">timer_elapsed</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(key_timer) </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"><</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> 100</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 if less than 100ms have passed</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 if 100ms or more have passed</span></span>\n<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div>', 39);
|
||
const _hoisted_40 = [
|
||
_hoisted_1
|
||
];
|
||
function _sfc_render(_ctx, _cache, $props, $setup, $data, $options) {
|
||
return openBlock(), createElementBlock("div", null, _hoisted_40);
|
||
}
|
||
const ref_functions = /* @__PURE__ */ _export_sfc(_sfc_main, [["render", _sfc_render]]);
|
||
export {
|
||
__pageData,
|
||
ref_functions as default
|
||
};
|