From 617923cd5641303c0cda360c5def9adcbae33260 Mon Sep 17 00:00:00 2001 From: skullY Date: Tue, 13 Jun 2017 14:18:01 -0700 Subject: Rough draft for a document on understanding QMK --- docs/understanding_qmk.md | 190 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 190 insertions(+) create mode 100644 docs/understanding_qmk.md diff --git a/docs/understanding_qmk.md b/docs/understanding_qmk.md new file mode 100644 index 0000000000..1b240fc87c --- /dev/null +++ b/docs/understanding_qmk.md @@ -0,0 +1,190 @@ +# Understanding QMK's Code + +This document attempts to explain how the QMK firmware works from a very high level. It assumes you understand basic programming concepts but does not (except where needed to demonstrate) assume familiarity with C. It assumes that you have a basic understanding of the following documents: + +* [QMK Overview](qmk_overview.md) +* [How Keyboards Work](basic_how_keyboards_work.md) +* [FAQ](faq.md) + +## Startup + +You can think of QMK as no different from any other computer program. It is started, performs its tasks, and then ends. The entry point for the program is the `main()` function, just like it is on any other C program. However, for a newcomer to QMK it can be confusing because the `main()` function appears in multiple places, and it can be hard to tell which one to look at. + +The reason for this is the different platforms that QMK supports. The most common platform is `lufa`, which runs on AVR processors such at the atmega32u4. We also support `chibios`, `pjrc`, `vusb`, and `bluefruit`, and may support more in the future. + +Let's focus on AVR processors for the moment, which use the `lufa` platform. You can find the `main()` function in [tmk_core/protocol/lufa/lufa.c](https://github.com/qmk/qmk_firmware/blob/master/tmk_core/protocol/lufa/lufa.c#L1129). If you browse through that function you'll find that it initializes any hardware that has been configured (including USB to the host) and then it starts the core part of the program with a [`while(1)`](https://github.com/qmk/qmk_firmware/blob/master/tmk_core/protocol/lufa/lufa.c#L1182). This is [The Main Loop](#the_main_loop). + +## The Main Loop + +This section of code is called "The Main Loop" because it's responsible for looping over the same set of instructions forever. This is where QMK dispatches out to the functions responsible for making the keyboard do everything it is supposed to. At first glance it can look like a lot of functionality but most of the time the code will be disabled by `#define`'s. + +### USB Suspend + +``` + #if !defined(NO_USB_STARTUP_CHECK) + while (USB_DeviceState == DEVICE_STATE_Suspended) { + print("[s]"); + suspend_power_down(); + if (USB_Device_RemoteWakeupEnabled && suspend_wakeup_condition()) { + USB_Device_SendRemoteWakeup(); + } + } + #endif +``` + +This section of code handles the USB suspend state. This state is entered when the computer the keyboard is plugged into is suspended. In this state we don't do anything but wait for the computer we're plugged into to wake up. + +### `keyboard_task()` + +``` + keyboard_task(); +``` + +This is where all the keyboard specific functionality is dispatched. The source code for `keyboard_task()` can be found in [tmk_core/common/keyboard.c](https://github.com/qmk/qmk_firmware/blob/master/tmk_core/common/keyboard.c#L154), and it is responsible for detecting changes in the matrix and turning LED's on and off. + +Within `keyboard_task()` you'll find code to handle: + +* Matrix Scanning +* Mouse Handling +* Serial Link(s) +* Visualizer +* Keyboard state LED's (Caps Lock, Num Lock, Scroll Lock) + +#### Matrix Scanning + +Matrix scanning is the core function of a keyboard firmware. It is the process of detecting which keys are currently pressed, and your keyboard runs this function many times a second. It's no exaggeration to say that 99% of your firmware's CPU time is spent on matrix scanning. + +While there are different strategies for doing the actual matrix detection, they are out of scope for this document. It is sufficient to treat matrix scanning as a black box, you ask for the matrix's current state and get back a datastructure that looks like this: + + +``` + { + {0,0,0,0}, + {0,0,0,0}, + {0,0,0,0}, + {0,0,0,0}, + {0,0,0,0} + } +``` + +That datastructure is a direct representation of the matrix for a 4 row by 5 column numpad. When a key is pressed that key's position within the matrix will be returned as `1` instead of `0`. + +Matrix Scanning runs many times per second. The exact rate varies but typically it runs at least 10 times per second to avoid perceptable lag. + +##### Matrix to Physical Layout Map + +Once we know the state of every switch on our keyboard we have to map that to a keycode. In QMK this is done by making use of C macros to allow us to separate the definition of the physical layout from the definition of keycodes. + +At the keyboard level we define a C macro (typically named `KEYMAP()`) which maps our keyboard's matrix to physical keys. Sometimes the matrix does not have a switch in every location, and we can use this macro to pre-populate those with KC_NO, making the keymap definition easier to work with. Here's an example `KEYMAP()` macro for a numpad: + +```c +#define KEYMAP( \ + k00, k01, k02, k03, \ + k10, k11, k12, k13, \ + k20, k21, k22, \ + k30, k31, k32, k33, \ + k40, k42 \ +) { \ + { k00, k01, k02, k03, }, \ + { k10, k11, k12, k13, }, \ + { k20, k21, k22, KC_NO, }, \ + { k30, k31, k32, k33, }, \ + { k40, KC_NO, k42, KC_NO } \ +} +``` + +Notice how the second block of our `KEYMAP()` macro matches the Matrix Scanning array above? This macro is what will map the matrix scanning array to keycodes. However, if you look at a 17 key numpad you'll notice that it has 3 places where the matrix could have a switch but doesn't, due to larger keys. We have populated those spaces with `KC_NO` so that our keymap definition doesn't have to. + +You can also use this macro to handle unusual matrix layouts, for example the [Clueboard rev 2](https://github.com/qmk/qmk_firmware/blob/master/keyboards/clueboard/rev2/rev2.h). Explaining that is outside the scope of this document. + +##### Keycode Assignment + +At the keymap level we make use of our `KEYMAP()` macro above to map keycodes to physical locations to matrix locations. It looks like this: + +``` +const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = { +[0] = KEYMAP( + KC_NLCK, KC_PSLS, KC_PAST, KC_PMNS, \ + KC_P7, KC_P8, KC_P9, KC_PPLS, \ + KC_P4, KC_P5, KC_P6, \ + KC_P1, KC_P2, KC_P3, KC_PENT, \ + KC_P0, KC_PDOT) +} +``` + +Notice how all of these arguments match up with the first half of the `KEYMAP()` macro from the last section? This is basically where we take a keycode and map it to our Matrix Scan from earlier. + +##### State Change Detection + +The matrix scanning described above tells us the state of the matrix at a given moment, but your computer only wants to know about changes, it doesn't care about the current state. QMK stores the results from the last matrix scan and compares the results from this matrix to determine when a key has been pressed or released. + +Let's look at an example. We'll hop into the middle of a keyboard scanning look to find that our previous scan looks like this: + +``` + { + {0,0,0,0}, + {0,0,0,0}, + {0,0,0,0}, + {0,0,0,0}, + {0,0,0,0} + } +``` + +And when our current scan completes it will look like this: + +``` + { + {1,0,0,0}, + {0,0,0,0}, + {0,0,0,0}, + {0,0,0,0}, + {0,0,0,0} + } +``` + +Comparing against our keymap we can see that the pressed key is KC_NLCK. From here we dispatch to the `process_record` set of functions. + +(FIXME: Feels like this section could be fleshed out more.) + +(FIXME: Magic happens between here and process_record) + +##### Process Record + +The `process_record()` function itself is deceptively simple, but hidden within is a gateway to overriding functionality at various levels of QMK. The chain of events looks something like this: + +* `void process_record(keyrecord_t *record)` + * `bool process_record_quantum(keyrecord_t *record)` + * Map this record to a keycode + * `bool process_record_kb(uint16_t keycode, keyrecord_t *record)` + * `bool process_record_user(uint16_t keycode, keyrecord_t *record)` + * `bool process_midi(uint16_t keycode, keyrecord_t *record)` + * `bool process_audio(uint16_t keycode, keyrecord_t *record)` + * `bool process_music(uint16_t keycode, keyrecord_t *record)` + * `bool process_tap_dance(uint16_t keycode, keyrecord_t *record)` + * `bool process_leader(uint16_t keycode, keyrecord_t *record)` + * `bool process_chording(uint16_t keycode, keyrecord_t *record)` + * `bool process_combo(uint16_t keycode, keyrecord_t *record)` + * `bool process_unicode(uint16_t keycode, keyrecord_t *record)` + * `bool process_ucis(uint16_t keycode, keyrecord_t *record)` + * `bool process_printer(uint16_t keycode, keyrecord_t *record)` + * `bool process_unicode_map(uint16_t keycode, keyrecord_t *record)` + * Identify and process quantum specific keycodes + * Identify and process standard keycodes + +At any step during this chain of events a function (such as `process_record_kb()`) can `return false` and processing of that keypress will end immediately. + +#### Mouse Handling + +FIXME: This needs to be written + +#### Serial Link(s) + +FIXME: This needs to be written + +#### Visualizer + +FIXME: This needs to be written + +#### Keyboard state LED's (Caps Lock, Num Lock, Scroll Lock) + +FIXME: This needs to be written -- cgit v1.2.3 From 40d82906cb2556ead29e2288788c7a26caf1f026 Mon Sep 17 00:00:00 2001 From: Jack Humbert Date: Wed, 28 Jun 2017 20:23:25 -0400 Subject: adds config options md --- docs/_summary.md | 1 + docs/config_options.md | 133 +++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 134 insertions(+) create mode 100644 docs/config_options.md diff --git a/docs/_summary.md b/docs/_summary.md index c5e29cb520..b08d86520e 100644 --- a/docs/_summary.md +++ b/docs/_summary.md @@ -18,6 +18,7 @@ * [Mouse keys](mouse_keys.md) * [FAQ: Creating a Keymap](faq_keymap.md) * [FAQ: Compiling QMK](faq_build.md) +* [The Config File](config_options.md) ### For hardware makers and modders * [Adding a keyboard to QMK](adding_a_keyboard_to_qmk.md) diff --git a/docs/config_options.md b/docs/config_options.md new file mode 100644 index 0000000000..13c8bdbbe8 --- /dev/null +++ b/docs/config_options.md @@ -0,0 +1,133 @@ +# The `config.h` file + +This is a c header file that is one of the first things included, and will persist over the whole project (if included). Lots of variables can be set here and accessed elsewhere (namely keymaps). This file can exist at a couple different levels: + +## Keyboard + +```c +#ifndef CONFIG_H +#define CONFIG_H + +#include "config_common.h" + +// config options + +#ifdef SUBPROJECT_ + #include "/config.h" +#endif + +#endif +``` + +This file contains config options that should apply to the whole keyboard, and won't change in subprojects, or most keymaps. The suproject block here only applies to keyboards with subprojects. + +## Subproject + +```c +#ifndef _CONFIG_H +#define _CONFIG_H + +#include "../config.h" + +// config options + +#endif +``` + +For keyboards that have subprojects, this file contains config options that should apply to only that subproject, and won't change in most keymaps. + +## Keymap + +```c +#ifndef CONFIG_USER_H +#define CONFIG_USER_H + +#include "../../config.h" + +// config options + +#endif +``` + +This file contains all of the options for that particular keymap. If you wish to override a previous declaration, you can use `#undef ` to undefine it, where you can then redefine it without an error. + +# Config Options + +```c +#define VENDOR_ID 0x1234 // defines your VID, and for most DIY projects, can be whatever you want +#define PRODUCT_ID 0x5678 // defines your PID, and for most DIY projects, can be whatever you want +#define DEVICE_VER 0 // defines the device version (often used for revisions) + +#define MANUFACTURER Me // generally who/whatever brand produced the board +#define PRODUCT Board // the name of the keyboard +#define DESCRIPTION a keyboard // a short description of what the keyboard is + +#define MATRIX_ROWS 5 // the number of rows in your keyboard's matrix +#define MATRIX_COLS 15 // the number of columns in your keyboard's matrix + +#define MATRIX_ROW_PINS { D0, D5, B5, B6 } // pins of the rows, from top to bottom +#define MATRIX_COL_PINS { F1, F0, B0, C7, F4, F5, F6, F7, D4, D6, B4, D7 } // pins of the columns, from left to right +#define UNUSED_PINS { D1, D2, D3, B1, B2, B3 } // pins unused by the keyboard for reference +#define MATRIX_HAS_GHOST // define is matrix has ghost (unlikely) +#define DIODE_DIRECTION COL2ROW // COL2ROW or ROW2COL - how your matrix is configured +// COL2ROW means the black mark on your diode is facing to the rows, and between the switch and the rows + +#define AUDIO_VOICES // turns on the alternate audio voices (to cycle through) +#define C6_AUDIO // enables audio on pin C6 +#define B5_AUDIO // enables audio on pin B5 (duophony is enable if both are enabled) + +#define BACKLIGHT_PIN B7 // pin of the backlight - B5, B6, B7 use PWM, others use softPWM +#define BACKLIGHT_LEVELS 3 // number of levels your backlight will have (not including off) + +#define DEBOUNCING_DELAY 5 // the delay when reading the value of the pin (5 is default) + +#define LOCKING_SUPPORT_ENABLE // mechanical locking support. Use KC_LCAP, KC_LNUM or KC_LSCR instead in keymap +#define LOCKING_RESYNC_ENABLE // tries to keep switch state consistent with keyboard LED state + +#define IS_COMMAND() ( \ // key combination that allows the use of magic commands (useful for debugging) + keyboard_report->mods == (MOD_BIT(KC_LSHIFT) | MOD_BIT(KC_RSHIFT)) \ +) + +// the following options can save on file size at the expense of that feature +#define NO_DEBUG // disable debuging (saves on file size) +#define NO_PRINT // disable printing (saves of file size) +#define NO_ACTION_LAYER // no layers +#define NO_ACTION_TAPPING // no tapping for layers/mods +#define NO_ACTION_ONESHOT // no oneshot for layers/mods +#define NO_ACTION_MACRO // no macros +#define NO_ACTION_FUNCTION // no functions + +#define FORCE_NKRO // NKRO by default requires to be turned on, this forces it to be on always + +#define PREVENT_STUCK_MODIFIERS // when switching layers, this will release all mods + +#define TAPPING_TERM 200 // how long before a tap becomes a hold +#define TAPPING_TOGGLE 2 // how many taps before triggering the toggle + +#define PERMISSIVE_HOLD // makes tap and hold keys work better for fast typers who don't want tapping term set above 500 + +#define LEADER_TIMEOUT 300 // how long before the leader key times out + +#define ONESHOT_TIMEOUT 300 // how long before oneshot times out +#define ONESHOT_TAP_TOGGLE 2 // how many taps before oneshot toggle is triggered + +#define IGNORE_MOD_TAP_INTERRUPT // makes it possible to do rolling combos (zx) with keys that convert to other keys on hold + +// ws2812 options +#define RGB_DI_PIN D7 // pin the DI on the ws2812 is hooked-up to +#define RGBLIGHT_ANIMATIONS // run RGB animations +#define RGBLED_NUM 15 // number of LEDs +#define RGBLIGHT_HUE_STEP 12 // units to step when in/decreasing hue +#define RGBLIGHT_SAT_STEP 25 // units to step when in/decresing saturation +#define RGBLIGHT_VAL_STEP 12 // units to step when in/decreasing value (brightness) + +#define RGBW_BB_TWI // bit-bangs twi to EZ RGBW LEDs (only required for Ergodox EZ) + +// mousekey options (self-describing) +#define MOUSEKEY_INTERVAL 20 +#define MOUSEKEY_DELAY 0 +#define MOUSEKEY_TIME_TO_MAX 60 +#define MOUSEKEY_MAX_SPEED 7 +#define MOUSEKEY_WHEEL_DELAY 0 + +``` \ No newline at end of file -- cgit v1.2.3 From d5244c6cf4939301b18ecf07650df6a6f9800e07 Mon Sep 17 00:00:00 2001 From: Jack Humbert Date: Thu, 29 Jun 2017 00:15:07 -0400 Subject: restructure keycode docs --- docs/_summary.md | 2 + docs/basic_keycodes.md | 186 ++++++++++++++++++++++++++++++++ docs/keycodes.md | 219 +------------------------------------ docs/quantum_keycodes.md | 274 +++++++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 466 insertions(+), 215 deletions(-) create mode 100644 docs/basic_keycodes.md create mode 100644 docs/quantum_keycodes.md diff --git a/docs/_summary.md b/docs/_summary.md index b08d86520e..268ab9954a 100644 --- a/docs/_summary.md +++ b/docs/_summary.md @@ -9,6 +9,8 @@ * [Keymap overview](keymap.md) * [Custom Quantum Functions](custom_quantum_functions.md) * [Keycodes](keycodes.md) + * [Basic Keycodes](basic_keycodes.md) + * [Quantum Keycodes](quantum_keycodes.md) * [Layer switching](key_functions.md) * [Leader Key](leader_key.md) * [Macros](macros.md) diff --git a/docs/basic_keycodes.md b/docs/basic_keycodes.md new file mode 100644 index 0000000000..2be3ada155 --- /dev/null +++ b/docs/basic_keycodes.md @@ -0,0 +1,186 @@ +# Basic keycodes + +## Letters and Numbers + +|KC_1|KC_2|KC_3|KC_4|KC_5|KC_6|KC_7|KC_8| +|----|----|----|----|----|----|----|----| +|KC_9|KC_0|KC_F1|KC_F2|KC_F3|KC_F4|KC_F5|KC_F6| +|KC_F7|KC_F8|KC_F9|KC_F10|KC_F11|KC_F12|KC_F13|KC_F14| +|KC_F15|KC_F16|KC_F17|KC_F18|KC_F19|KC_F20|KC_F21|KC_F22| +|KC_F23|KC_F24|KC_A|KC_B|KC_C|KC_D|KC_E|KC_F| +|KC_G|KC_H|KC_I|KC_J|KC_K|KC_L|KC_M|KC_N| +|KC_O|KC_P|KC_Q|KC_R|KC_S|KC_T|KC_U|KC_V| +|KC_W|KC_X|KC_Y|KC_Z||||| + +## Punctuation + +|Long Name|Short Name|Description| +|---------|----------|-----------| +|KC_ENTER|KC_ENT|`Return (ENTER)`| +|KC_ESCAPE|KC_ESC|`ESCAPE`| +|KC_BSPACE|KC_BSPC|`DELETE (Backspace)`| +|KC_TAB||`Tab`| +|KC_SPACE|KC_SPC|Spacebar| +|KC_MINUS|KC_MINS|`-` and `_`| +|KC_EQUAL|KC_EQL|`=` and `+`| +|KC_LBRACKET|KC_LBRC|`[` and `{`| +|KC_RBRACKET|KC_RBRC|`]` and `}`| +|KC_BSLASH|KC_BSLS|`\` and | | +|KC_NONUS_HASH|KC_NUHS|Non-US `#` and `~`| +|KC_NONUS_BSLASH|KC_NUBS|Non-US `\` and | | +|KC_INT1|KC_RO|JIS `\` and | | +|KC_INT2|KC_KANA|International216| +|KC_INT3|KC_JYEN|Yen Symbol (`¥`)| +|KC_SCOLON|KC_SCLN|`;` and `:`| +|KC_QUOTE|KC_QUOT|`‘` and `“`| +|KC_GRAVE|KC_GRV|Grave Accent and Tilde| +|KC_COMMA|KC_COMM|`,` and `<`| +|KC_DOT||`.` and `>`| +|KC_SLASH|KC_SLSH|`/` and `?`| +|KC_CAPSLOCK|KC_CAPS|Caps Lock| + +## Modifiers + +|Long Name|Short Name|Description| +|---------|----------|-----------| +|KC_LCTRL|KC_LCTL|LeftControl| +|KC_LSHIFT|KC_LSFT|LeftShift| +|KC_LALT||LeftAlt| +|KC_LGUI||Left GUI(Windows/Apple/Meta key)| +|KC_RCTRL|KC_RCTL|RightControl| +|KC_RSHIFT|KC_RSFT|RightShift| +|KC_RALT||RightAlt| +|KC_RGUI||Right GUI(Windows/Apple/Meta key)| +|KC_LOCKING_CAPS||Locking Caps Lock| +|KC_LOCKING_NUM||Locking Num Lock| +|KC_LOCKING_SCROLL||Locking Scroll Lock| +|KC_INT4|KC_HENK|JIS Henken| +|KC_INT5|KC_MHEN|JIS Muhenken| + +## Commands + +|Long Name|Short Name|Description| +|---------|----------|-----------| +|KC_PSCREEN|KC_PSCR|PrintScreen| +|KC_SCROLLLOCK|KC_SLCK|Scroll Lock| +|KC_PAUSE|KC_PAUS|Pause| +|KC_INSERT|KC_INS|Insert| +|KC_HOME||Home| +|KC_PGUP||PageUp| +|KC_DELETE|KC_DEL|Delete Forward| +|KC_END||End| +|KC_PGDOWN|KC_PGDN|PageDown| +|KC_RIGHT|KC_RGHT|RightArrow| +|KC_LEFT||LeftArrow| +|KC_DOWN||DownArrow| +|KC_UP||UpArrow| +|KC_APPLICATION|KC_APP|Application| +|KC_POWER||Power| +|KC_EXECUTE||Execute| +|KC_HELP||Help| +|KC_MENU||Menu| +|KC_SELECT||Select| +|KC_AGAIN||Again| +|KC_UNDO||Undo| +|KC_CUT||Cut| +|KC_COPY||Copy| +|KC_PASTE||Paste| +|KC_FIND||Find| +|KC_ALT_ERASE||Alternate Erase| +|KC_SYSREQ||SysReq/Attention| +|KC_CANCEL||Cancel| +|KC_CLEAR||Clear| +|KC_PRIOR||Prior| +|KC_RETURN||Return| +|KC_SEPARATOR||Separator| +|KC_OUT||Out| +|KC_OPER||Oper| +|KC_CLEAR_AGAIN||Clear/Again| +|KC_CRSEL||CrSel/Props| +|KC_EXSEL||ExSel| +|KC_SYSTEM_POWER|KC_PWR|System Power Down| +|KC_SYSTEM_SLEEP|KC_SLEP|System Sleep| +|KC_SYSTEM_WAKE|KC_WAKE|System Wake| +|KC_MAIL|KC_MAIL|| +|KC_CALCULATOR|KC_CALC|| +|KC_MY_COMPUTER|KC_MYCM|| +|KC_WWW_SEARCH|KC_WSCH|| +|KC_WWW_HOME|KC_WHOM|| +|KC_WWW_BACK|KC_WBAK|| +|KC_WWW_FORWARD|KC_WFWD|| +|KC_WWW_STOP|KC_WSTP|| +|KC_WWW_REFRESH|KC_WREF|| +|KC_WWW_FAVORITES|KC_WFAV|| + +## Media Keys + +Windows and Mac use different key codes for next track and previous track. Make sure you choose the keycode that corresponds to your OS. + +|Long Name|Short Name|Description| +|---------|----------|-----------| +|KC_STOP||Stop| +|KC__MUTE||Mute| +|KC__VOLUP||Volume Up| +|KC__VOLDOWN||Volume Down| +|KC_AUDIO_MUTE|KC_MUTE|| +|KC_AUDIO_VOL_UP|KC_VOLU|| +|KC_AUDIO_VOL_DOWN|KC_VOLD|| +|KC_MEDIA_NEXT_TRACK|KC_MNXT|Next Track (Windows)| +|KC_MEDIA_PREV_TRACK|KC_MPRV|Previous Track (Windows)| +|KC_MEDIA_FAST_FORWARD|KC_MFFD|Next Track (macOS)| +|KC_MEDIA_REWIND|KC_MRWD|Previous Track (macOS)| +|KC_MEDIA_STOP|KC_MSTP|| +|KC_MEDIA_PLAY_PAUSE|KC_MPLY|| +|KC_MEDIA_SELECT|KC_MSEL|| + +## Numpad + +|Long Name|Short Name|Description| +|---------|----------|-----------| +|KC_NUMLOCK|KC_NLCK|Keypad Num Lock and Clear| +|KC_KP_SLASH|KC_PSLS|Keypad /| +|KC_KP_ASTERISK|KC_PAST|Keypad *| +|KC_KP_MINUS|KC_PMNS|Keypad -| +|KC_KP_PLUS|KC_PPLS|Keypad +| +|KC_KP_ENTER|KC_PENT|Keypad ENTER| +|KC_KP_1|KC_P1|Keypad 1 and End| +|KC_KP_2|KC_P2|Keypad 2 and Down Arrow| +|KC_KP_3|KC_P3|Keypad 3 and PageDn| +|KC_KP_4|KC_P4|Keypad 4 and Left Arrow| +|KC_KP_5|KC_P5|Keypad 5| +|KC_KP_6|KC_P6|Keypad 6 and Right Arrow| +|KC_KP_7|KC_P7|Keypad 7 and Home| +|KC_KP_8|KC_P8|Keypad 8 and Up Arrow| +|KC_KP_9|KC_P9|Keypad 9 and PageUp| +|KC_KP_0|KC_P0|Keypad 0 and Insert| +|KC_KP_DOT|KC_PDOT|Keypad . and Delete| +|KC_KP_EQUAL|KC_PEQL|Keypad =| +|KC_KP_COMMA|KC_PCMM|Keypad Comma| +|KC_KP_EQUAL_AS400||Keypad Equal Sign| + +## Special Keys + +|Long Name|Short Name|Description| +|---------|----------|-----------| +|KC_NO||Ignore this key. (NOOP) | + +## Mousekey + +|Long Name|Short Name|Description| +|---------|----------|-----------| +|KC_MS_UP|KC_MS_U|Mouse Cursor Up| +|KC_MS_DOWN|KC_MS_D|Mouse Cursor Down| +|KC_MS_LEFT|KC_MS_L|Mouse Cursor Left| +|KC_MS_RIGHT|KC_MS_R|Mouse Cursor Right| +|KC_MS_BTN1|KC_BTN1|Mouse Button 1| +|KC_MS_BTN2|KC_BTN2|Mouse Button 2| +|KC_MS_BTN3|KC_BTN3|Mouse Button 3| +|KC_MS_BTN4|KC_BTN4|Mouse Button 4| +|KC_MS_BTN5|KC_BTN5|Mouse Button 5| +|KC_MS_WH_UP|KC_WH_U|Mouse Wheel Up| +|KC_MS_WH_DOWN|KC_WH_D|Mouse Wheel Down| +|KC_MS_WH_LEFT|KC_WH_L|Mouse Wheel Left| +|KC_MS_WH_RIGHT|KC_WH_R|Mouse Wheel Right| +|KC_MS_ACCEL0|KC_ACL0|Mouse Acceleration 0| +|KC_MS_ACCEL1|KC_ACL1|Mouse Acceleration 1| +|KC_MS_ACCEL2|KC_ACL2|Mouse Acceleration 2| \ No newline at end of file diff --git a/docs/keycodes.md b/docs/keycodes.md index 5cf5c019d0..7c5cae8b31 100644 --- a/docs/keycodes.md +++ b/docs/keycodes.md @@ -4,225 +4,14 @@ When defining a [keymap](keymap.md) each key needs a valid key definition. This page documents the symbols that correspond to keycodes that are available to you in QMK. -To customize your board, they can be used by themselves or as **action codes** in combination with one of the [many C macros](https://github.com/qmk/qmk_firmware/wiki#c-macros-for-action-code). +## Basic keycodes (`0x00` - `0xFF`) -The source of truth for these codes is [tmk_core/common/keycode.h](https://github.com/qmk/qmk_firmware/blob/master/tmk_core/common/keycode.h) file in the qmk source code. - -# The Keycodes - -Keycodes in QMK are based on [HID Usage Keyboard/Keypad Page(0x07)](http://www.usb.org/developers/hidpage/Hut1_12v2.pdf) with following exceptions: +[Basic keycodes](basic_keycodes.md) in QMK are based on [HID Usage Keyboard/Keypad Page(0x07)](http://www.usb.org/developers/hidpage/Hut1_12v2.pdf) with following exceptions: * `KC_NO` = 0 for no action * `KC_TRNS` = 1 for layer transparency * internal special keycodes in the `0xA5-DF` range (tmk heritage). -## Letters and Numbers - -|KC_1|KC_2|KC_3|KC_4|KC_5|KC_6|KC_7|KC_8| -|----|----|----|----|----|----|----|----| -|KC_9|KC_0|KC_F1|KC_F2|KC_F3|KC_F4|KC_F5|KC_F6| -|KC_F7|KC_F8|KC_F9|KC_F10|KC_F11|KC_F12|KC_F13|KC_F14| -|KC_F15|KC_F16|KC_F17|KC_F18|KC_F19|KC_F20|KC_F21|KC_F22| -|KC_F23|KC_F24|KC_A|KC_B|KC_C|KC_D|KC_E|KC_F| -|KC_G|KC_H|KC_I|KC_J|KC_K|KC_L|KC_M|KC_N| -|KC_O|KC_P|KC_Q|KC_R|KC_S|KC_T|KC_U|KC_V| -|KC_W|KC_X|KC_Y|KC_Z||||| - -## Punctuation - -|Long Name|Short Name|Description| -|---------|----------|-----------| -|KC_ENTER|KC_ENT|`Return (ENTER)`| -|KC_ESCAPE|KC_ESC|`ESCAPE`| -|KC_BSPACE|KC_BSPC|`DELETE (Backspace)`| -|KC_TAB||`Tab`| -|KC_SPACE|KC_SPC|Spacebar| -|KC_MINUS|KC_MINS|`-` and `_`| -|KC_EQUAL|KC_EQL|`=` and `+`| -|KC_LBRACKET|KC_LBRC|`[` and `{`| -|KC_RBRACKET|KC_RBRC|`]` and `}`| -|KC_BSLASH|KC_BSLS|`\` and | | -|KC_NONUS_HASH|KC_NUHS|Non-US `#` and `~`| -|KC_NONUS_BSLASH|KC_NUBS|Non-US `\` and | | -|KC_INT1|KC_RO|JIS `\` and | | -|KC_INT2|KC_KANA|International216| -|KC_INT3|KC_JYEN|Yen Symbol (`¥`)| -|KC_SCOLON|KC_SCLN|`;` and `:`| -|KC_QUOTE|KC_QUOT|`‘` and `“`| -|KC_GRAVE|KC_GRV|Grave Accent and Tilde| -|KC_COMMA|KC_COMM|`,` and `<`| -|KC_DOT||`.` and `>`| -|KC_SLASH|KC_SLSH|`/` and `?`| -|KC_CAPSLOCK|KC_CAPS|Caps Lock| - -## Modifiers - -|Long Name|Short Name|Description| -|---------|----------|-----------| -|KC_LCTRL|KC_LCTL|LeftControl| -|KC_LSHIFT|KC_LSFT|LeftShift| -|KC_LALT||LeftAlt| -|KC_LGUI||Left GUI(Windows/Apple/Meta key)| -|KC_RCTRL|KC_RCTL|RightControl| -|KC_RSHIFT|KC_RSFT|RightShift| -|KC_RALT||RightAlt| -|KC_RGUI||Right GUI(Windows/Apple/Meta key)| -|KC_LOCKING_CAPS||Locking Caps Lock| -|KC_LOCKING_NUM||Locking Num Lock| -|KC_LOCKING_SCROLL||Locking Scroll Lock| -|KC_INT4|KC_HENK|JIS Henken| -|KC_INT5|KC_MHEN|JIS Muhenken| - -## Commands - -|Long Name|Short Name|Description| -|---------|----------|-----------| -|KC_PSCREEN|KC_PSCR|PrintScreen| -|KC_SCROLLLOCK|KC_SLCK|Scroll Lock| -|KC_PAUSE|KC_PAUS|Pause| -|KC_INSERT|KC_INS|Insert| -|KC_HOME||Home| -|KC_PGUP||PageUp| -|KC_DELETE|KC_DEL|Delete Forward| -|KC_END||End| -|KC_PGDOWN|KC_PGDN|PageDown| -|KC_RIGHT|KC_RGHT|RightArrow| -|KC_LEFT||LeftArrow| -|KC_DOWN||DownArrow| -|KC_UP||UpArrow| -|KC_APPLICATION|KC_APP|Application| -|KC_POWER||Power| -|KC_EXECUTE||Execute| -|KC_HELP||Help| -|KC_MENU||Menu| -|KC_SELECT||Select| -|KC_AGAIN||Again| -|KC_UNDO||Undo| -|KC_CUT||Cut| -|KC_COPY||Copy| -|KC_PASTE||Paste| -|KC_FIND||Find| -|KC_ALT_ERASE||Alternate Erase| -|KC_SYSREQ||SysReq/Attention| -|KC_CANCEL||Cancel| -|KC_CLEAR||Clear| -|KC_PRIOR||Prior| -|KC_RETURN||Return| -|KC_SEPARATOR||Separator| -|KC_OUT||Out| -|KC_OPER||Oper| -|KC_CLEAR_AGAIN||Clear/Again| -|KC_CRSEL||CrSel/Props| -|KC_EXSEL||ExSel| -|KC_SYSTEM_POWER|KC_PWR|System Power Down| -|KC_SYSTEM_SLEEP|KC_SLEP|System Sleep| -|KC_SYSTEM_WAKE|KC_WAKE|System Wake| -|KC_MAIL|KC_MAIL|| -|KC_CALCULATOR|KC_CALC|| -|KC_MY_COMPUTER|KC_MYCM|| -|KC_WWW_SEARCH|KC_WSCH|| -|KC_WWW_HOME|KC_WHOM|| -|KC_WWW_BACK|KC_WBAK|| -|KC_WWW_FORWARD|KC_WFWD|| -|KC_WWW_STOP|KC_WSTP|| -|KC_WWW_REFRESH|KC_WREF|| -|KC_WWW_FAVORITES|KC_WFAV|| - -## Media Keys - -Windows and Mac use different key codes for next track and previous track. Make sure you choose the keycode that corresponds to your OS. - -|Long Name|Short Name|Description| -|---------|----------|-----------| -|KC_STOP||Stop| -|KC__MUTE||Mute| -|KC__VOLUP||Volume Up| -|KC__VOLDOWN||Volume Down| -|KC_AUDIO_MUTE|KC_MUTE|| -|KC_AUDIO_VOL_UP|KC_VOLU|| -|KC_AUDIO_VOL_DOWN|KC_VOLD|| -|KC_MEDIA_NEXT_TRACK|KC_MNXT|Next Track (Windows)| -|KC_MEDIA_PREV_TRACK|KC_MPRV|Previous Track (Windows)| -|KC_MEDIA_FAST_FORWARD|KC_MFFD|Next Track (macOS)| -|KC_MEDIA_REWIND|KC_MRWD|Previous Track (macOS)| -|KC_MEDIA_STOP|KC_MSTP|| -|KC_MEDIA_PLAY_PAUSE|KC_MPLY|| -|KC_MEDIA_SELECT|KC_MSEL|| - -## Numpad - -|Long Name|Short Name|Description| -|---------|----------|-----------| -|KC_NUMLOCK|KC_NLCK|Keypad Num Lock and Clear| -|KC_KP_SLASH|KC_PSLS|Keypad /| -|KC_KP_ASTERISK|KC_PAST|Keypad *| -|KC_KP_MINUS|KC_PMNS|Keypad -| -|KC_KP_PLUS|KC_PPLS|Keypad +| -|KC_KP_ENTER|KC_PENT|Keypad ENTER| -|KC_KP_1|KC_P1|Keypad 1 and End| -|KC_KP_2|KC_P2|Keypad 2 and Down Arrow| -|KC_KP_3|KC_P3|Keypad 3 and PageDn| -|KC_KP_4|KC_P4|Keypad 4 and Left Arrow| -|KC_KP_5|KC_P5|Keypad 5| -|KC_KP_6|KC_P6|Keypad 6 and Right Arrow| -|KC_KP_7|KC_P7|Keypad 7 and Home| -|KC_KP_8|KC_P8|Keypad 8 and Up Arrow| -|KC_KP_9|KC_P9|Keypad 9 and PageUp| -|KC_KP_0|KC_P0|Keypad 0 and Insert| -|KC_KP_DOT|KC_PDOT|Keypad . and Delete| -|KC_KP_EQUAL|KC_PEQL|Keypad =| -|KC_KP_COMMA|KC_PCMM|Keypad Comma| -|KC_KP_EQUAL_AS400||Keypad Equal Sign| - -## Special Keys - -|Long Name|Short Name|Description| -|---------|----------|-----------| -|KC_NO||Ignore this key. (NOOP) | - -## Mousekey - -|Long Name|Short Name|Description| -|---------|----------|-----------| -|KC_MS_UP|KC_MS_U|Mouse Cursor Up| -|KC_MS_DOWN|KC_MS_D|Mouse Cursor Down| -|KC_MS_LEFT|KC_MS_L|Mouse Cursor Left| -|KC_MS_RIGHT|KC_MS_R|Mouse Cursor Right| -|KC_MS_BTN1|KC_BTN1|Mouse Button 1| -|KC_MS_BTN2|KC_BTN2|Mouse Button 2| -|KC_MS_BTN3|KC_BTN3|Mouse Button 3| -|KC_MS_BTN4|KC_BTN4|Mouse Button 4| -|KC_MS_BTN5|KC_BTN5|Mouse Button 5| -|KC_MS_WH_UP|KC_WH_U|Mouse Wheel Up| -|KC_MS_WH_DOWN|KC_WH_D|Mouse Wheel Down| -|KC_MS_WH_LEFT|KC_WH_L|Mouse Wheel Left| -|KC_MS_WH_RIGHT|KC_WH_R|Mouse Wheel Right| -|KC_MS_ACCEL0|KC_ACL0|Mouse Acceleration 0| -|KC_MS_ACCEL1|KC_ACL1|Mouse Acceleration 1| -|KC_MS_ACCEL2|KC_ACL2|Mouse Acceleration 2| - -## Magic Keys - -The following keys can be used to turn on and off various "Magic" features. These include Boot Magic (holding certain keys down while plugging the keyboard in) and the Magic Key. +## Quantum keycodes (`0x0100` - `0xFFFF`) -|Long Name|Short Name|Description| -|---------|----------|-----------| -|MAGIC_SWAP_CONTROL_CAPSLOCK||Swap Capslock and Control| -|MAGIC_CAPSLOCK_TO_CONTROL||Change Capslock to Control| -|MAGIC_SWAP_ALT_GUI||Swap ALT and GUI| -|MAGIC_SWAP_LALT_LGUI||Swap LALT and LGUI| -|MAGIC_SWAP_RALT_RGUI||Swap RALT and RGUI| -|MAGIC_NO_GUI||Disable off the GUI key| -|MAGIC_SWAP_GRAVE_ESC||Swap the GRAVE (~ `) and Esc keys| -|MAGIC_SWAP_BACKSLASH_BACKSPACE||Swap Backslash and Backspace| -|MAGIC_UNSWAP_CONTROL_CAPSLOCK||Disable the Control/Caps Swap| -|MAGIC_UNCAPSLOCK_TO_CONTROL||Turn Capslock back into Capslock| -|MAGIC_UNSWAP_ALT_GUI||Turn the ALT/GUI swap off| -|MAGIC_UNSWAP_LALT_LGUI||Turn the LALT/LGUI swap off| -|MAGIC_UNSWAP_RALT_RGUI||Turn the RALT/RGUI swap off| -|MAGIC_UNNO_GUI||Enable the GUI key| -|MAGIC_UNSWAP_GRAVE_ESC||Turn the GRAVE/ESC swap off| -|MAGIC_UNSWAP_BACKSLASH_BACKSPACE||Turn the Backslash/Backspace swap off| -|MAGIC_HOST_NKRO||Turn NKRO on| -|MAGIC_UNHOST_NKRO||Turn NKRO off| -|MAGIC_TOGGLE_NKRO||Toggle NKRO on or off| +[Quantum keycodes](quantum_keycodes.md) allow for easier customisation of your keymap than the basic ones provide, without having to define custom actions. diff --git a/docs/quantum_keycodes.md b/docs/quantum_keycodes.md new file mode 100644 index 0000000000..81eb647017 --- /dev/null +++ b/docs/quantum_keycodes.md @@ -0,0 +1,274 @@ +# Quantum Keycodes + +Something important to realise with keycodes is that they are all numbers between `0x0` and `0xFFFF` - even though they may look like functions, words, or phrases, they are all shortcuts to some number. This allows us to define all of what they do in different places, and store keymaps in a relatively small place (arrays). If you try to "call" a keycode by placing it somewhere besides a keymap, it may compile, but it won't do anything useful. + +All keycodes on this page have a value above `0xFF` (values less are considered the [basic keycodes](basic_keycodes.md)) and won't work with any of the mod/layer-tap keys listed at the bottom. + +* `SAFE_RANGE` is always the last keycode in the quantum list, and where custom lists can begin +* `RESET` puts the keyboard into DFU mode for flashing +* `DEBUG` toggles debug mode +* Shortcuts for bootmagic options (work when bootmagic is off) + * `MAGIC_SWAP_CONTROL_CAPSLOCK` + * `MAGIC_CAPSLOCK_TO_CONTROL` + * `MAGIC_SWAP_LALT_LGUI` + * `MAGIC_SWAP_RALT_RGUI` + * `MAGIC_NO_GUI` + * `MAGIC_SWAP_GRAVE_ESC` + * `MAGIC_SWAP_BACKSLASH_BACKSPACE` + * `MAGIC_HOST_NKRO` + * `MAGIC_SWAP_ALT_GUI`/`AG_SWAP` + * `MAGIC_UNSWAP_CONTROL_CAPSLOCK` + * `MAGIC_UNCAPSLOCK_TO_CONTROL` + * `MAGIC_UNSWAP_LALT_LGUI` + * `MAGIC_UNSWAP_RALT_RGUI` + * `MAGIC_UNNO_GUI` + * `MAGIC_UNSWAP_GRAVE_ESC` + * `MAGIC_UNSWAP_BACKSLASH_BACKSPACE` + * `MAGIC_UNHOST_NKRO` + * `MAGIC_UNSWAP_ALT_GUI`/`AG_NORM` + * `MAGIC_TOGGLE_NKRO` +* `KC_GESC`/`GRAVE_ESC` acts as escape when pressed normally but when pressed with a mod will send a `~` +* `KC_LSPO` left shift when held, open paranthesis when tapped +* `KC_RSPC` right shift when held, close paranthesis when tapped +* `KC_LEAD` the leader key + +* `FUNC(n)`/`F(n)` to call `fn_action` n +* `M(n)` to call macro n +* `MACROTAP(n)` to macro-tap n idk FIXME + +## Audio + +```c +#ifdef AUDIO_ENABLE + AU_ON, + AU_OFF, + AU_TOG, + + #ifdef FAUXCLICKY_ENABLE + FC_ON, + FC_OFF, + FC_TOG, + #endif + + // Music mode on/off/toggle + MU_ON, + MU_OFF, + MU_TOG, + + // Music voice iterate + MUV_IN, + MUV_DE, +#endif +``` + +## Midi + +#if !MIDI_ENABLE_STRICT || (defined(MIDI_ENABLE) && defined(MIDI_BASIC)) + MI_ON, // send midi notes when music mode is enabled + MI_OFF, // don't send midi notes when music mode is enabled +#endif + +MIDI_TONE_MIN, +MIDI_TONE_MAX + +MI_C = MIDI_TONE_MIN, +MI_Cs, +MI_Db = MI_Cs, +MI_D, +MI_Ds, +MI_Eb = MI_Ds, +MI_E, +MI_F, +MI_Fs, +MI_Gb = MI_Fs, +MI_G, +MI_Gs, +MI_Ab = MI_Gs, +MI_A, +MI_As, +MI_Bb = MI_As, +MI_B, + +MIDI_TONE_KEYCODE_OCTAVES > 1 + +where x = 1-5: +MI_C_x, +MI_Cs_x, +MI_Db_x = MI_Cs_x, +MI_D_x, +MI_Ds_x, +MI_Eb_x = MI_Ds_x, +MI_E_x, +MI_F_x, +MI_Fs_x, +MI_Gb_x = MI_Fs_x, +MI_G_x, +MI_Gs_x, +MI_Ab_x = MI_Gs_x, +MI_A_x, +MI_As_x, +MI_Bb_x = MI_As_x, +MI_B_x, + +MI_OCT_Nx 1-2 +MI_OCT_x 0-7 +MIDI_OCTAVE_MIN = MI_OCT_N2, +MIDI_OCTAVE_MAX = MI_OCT_7, +MI_OCTD, // octave down +MI_OCTU, // octave up + +MI_TRNS_Nx 1-6 +MI_TRNS_x 0-6 +MIDI_TRANSPOSE_MIN = MI_TRNS_N6, +MIDI_TRANSPOSE_MAX = MI_TRNS_6, +MI_TRNSD, // transpose down +MI_TRNSU, // transpose up + +MI_VEL_x 1-10 +MIDI_VELOCITY_MIN = MI_VEL_1, +MIDI_VELOCITY_MAX = MI_VEL_10, +MI_VELD, // velocity down +MI_VELU, // velocity up + +MI_CHx 1-16 +MIDI_CHANNEL_MIN = MI_CH1 +MIDI_CHANNEL_MAX = MI_CH16, +MI_CHD, // previous channel +MI_CHU, // next channel + +MI_ALLOFF, // all notes off + +MI_SUS, // sustain +MI_PORT, // portamento +MI_SOST, // sostenuto +MI_SOFT, // soft pedal +MI_LEG, // legato + +MI_MOD, // modulation +MI_MODSD, // decrease modulation speed +MI_MODSU, // increase modulation speed +#endif // MIDI_ADVANCED + +## Backlight + +* `BL_x` where x = 0-15 +* `BL_ON = BL_9` +* `BL_OFF = BL_0` +* `BL_DEC` +* `BL_INC` +* `BL_TOGG` +* `BL_STEP` + +## RGB WS2818 LEDs + +* `RGB_TOG` toggle on/off +* `RGB_MOD` cycle between modes +* `RGB_HUI` hue increase +* `RGB_HUD` hue decrease +* `RGB_SAI` saturation increase +* `RGB_SAD` saturation decrease +* `RGB_VAI` value increase +* `RGB_VAD` value decrease + +## Thermal Printer (experimental) + +* `PRINT_ON` +* `PRINT_OFF` + +## Keyboard output selection + +* `OUT_AUTO` auto mode +* `OUT_USB` usb only +* `OUT_BT` bluetooth (when `BLUETOOTH_ENABLE`) + +## Modifiers + +* `KC_HYPR` LCTL + LSFT + LALT + LGUI - `MOD_HYPR` is the bit version +* `KC_MEH` LCTL + LSFT + LALT - `MOD_MEH` is the bit version + +### Modifiers with keys + +* `LCTL(kc)` LCTL + kc +* `LSFT(kc)`/`S(kc)` LSFT + kc +* `LALT(kc)` LALT + kc +* `LGUI(kc)` LGUI + kc +* `RCTL(kc)` RCTL + kc +* `RSFT(kc)` RSFT + kc +* `RALT(kc)` RALT + kc +* `RGUI(kc)` RGUI + kc + +* `HYPR(kc)` LCTL + LSFT + LALT + LGUI + kc +* `MEH(kc)` LCTL + LSFT + LALT + kc +* `LCAG(kc)` LCTL + LALT + LGUI + kc +* `ALTG(kc)` RCTL + RALT + kc +* `SCMD(kc)`/`SWIN(kc)` LGUI + LSFT + kc +* `LCA(kc)` LCTL + LALT + kc + +* `OSM(mod)` use mod for one keypress - use mod bits with this + +> Mod bits are the 4-letter part of the keycode prefixed with `MOD_`, e.g. `MOD_LCTL` + +### Mod-tap keys + +These keycodes will press the mod(s) when held, and the key when tapped. They only work with [basic keycodes](basic_keycodes.md). + +* `CTL_T(kc)`/`LCTL_T(kc)` LCTL when held, kc when tapped +* `RCTL_T(kc)` RCTL when held, kc when tapped + +* `SFT_T(kc)`/`LSFT_T(kc)` LSFT when held, kc when tapped +* `RSFT_T(kc)` RSFT when held, kc when tapped + +* `ALT_T(kc)`/`LALT_T(kc)` LALT when held, kc when tapped +* `RALT_T(kc)`/`ALGR_T(kc)` RALT when held, kc when tapped + +* `GUI_T(kc)`/`LGUI_T(kc)` LGUI when held, kc when tapped +* `RGUI_T(kc)` RGUI when held, kc when tapped + +* `C_S_T(kc)` LCTL + LSFT when held, kc when tapped +* `MEH_T(kc)` LCTL + LSFT + LALT when held, kc when tapped +* `LCAG_T(kc)` LCTL + LALT + LGUI when held, kc when tapped +* `RCAG_T(kc)` RCTL + RALT + RGUI when held, kc when tapped +* `ALL_T(kc)` LCTL + LSFT + LALT + LGUI when held, kc tapped [more info](http://brettterpstra.com/2012/12/08/a-useful-caps-lock-key/) +* `SCMD_T(kc)`/`SWIN_T(kc)` LGUI + LSFT when held, kc when tapped +* `LCA_T(kc)` LCTL + LALT when held, kc when tapped + +## Shifted symbols + +It's important to remember that all of the keycodes also send a left shift - this may cause unintended actions if unaccounted for. The 4-letter code is preferred in most situations. + +* `KC_TILD`/`KC_TILDE` tilde `~` +* `KC_EXLM`/`KC_EXCLAIM` exclamation mark `!` +* `KC_AT` at sign `@` +* `KC_HASH` hash sign `#` +* `KC_DLR`/`KC_DOLLAR` dollar sign `$` +* `KC_PERC`/`KC_PERCENT` percent sign `%` +* `KC_CIRC`/`KC_CIRCUMFLEX` circumflex `^` +* `KC_AMPR`/`KC_AMPERSAND` ampersand `&` +* `KC_ASTR`/`KC_ASTERISK` asterisk `*` +* `KC_LPRN`/`KC_LEFT_PAREN` left parenthesis `(` +* `KC_RPRN`/`KC_RIGHT_PAREN` right parenthesis `)` +* `KC_UNDS`/`KC_UNDERSCORE` underscore `_` +* `KC_PLUS` plus sign `+` +* `KC_LCBR`/`KC_LEFT_CURLY_BRACE` left curly brace `{` +* `KC_RCBR`/`KC_RIGHT_CURLY_BRACE` right curly brace `}` +* `KC_LT`/`KC_LABK`/`KC_LEFT_ANGLE_BRACKET` left angle bracket `<` +* `KC_GT`/`KC_RABK`/`KC_RIGHT_ANGLE_BRACKET` right angle bracket `>` +* `KC_COLN`/`KC_COLON` colon `:` +* `KC_PIPE` pipe `|` +* `KC_QUES`/`KC_QUESTION` question mark `?` +* `KC_DQT`/`KC_DOUBLE_QUOTE`/`KC_DQUO` double quote `"` + +## Layer adjustments + +* `LT(layer, kc)` turn on layer (0-15) when held, kc ([basic keycodes](basic_keycodes.md)) when tapped +* `TO(layer)` turn on layer when depressed +* `MO(layer)` momentarily turn on layer when depressed (requires `KC_TRNS` on destination layer) +* `DF(layer)` sets the base (default) layer +* `TG(layer)` toggle layer on/off +* `OSL(layer)` switch to layer for one keycode +* `TT(layer)` tap toggle? idk FIXME + +## Unicode + +* `UNICODE(n)`/`UC(n)` if `UNICODE_ENABLE`, this will send characters up to `0x7FFF` +* `X(n)` if `UNICODEMAP_ENABLE`, also sends unicode via a different method \ No newline at end of file -- cgit v1.2.3 From 910d32c07e5d130bbe59abe11be5459b2381f011 Mon Sep 17 00:00:00 2001 From: skullY Date: Wed, 28 Jun 2017 23:52:08 -0700 Subject: Flesh out the quantum_keycodes documentation --- docs/quantum_keycodes.md | 357 ++++++++++++++++++++++++++++------------------- 1 file changed, 216 insertions(+), 141 deletions(-) diff --git a/docs/quantum_keycodes.md b/docs/quantum_keycodes.md index 81eb647017..e9edad03ed 100644 --- a/docs/quantum_keycodes.md +++ b/docs/quantum_keycodes.md @@ -1,42 +1,50 @@ # Quantum Keycodes -Something important to realise with keycodes is that they are all numbers between `0x0` and `0xFFFF` - even though they may look like functions, words, or phrases, they are all shortcuts to some number. This allows us to define all of what they do in different places, and store keymaps in a relatively small place (arrays). If you try to "call" a keycode by placing it somewhere besides a keymap, it may compile, but it won't do anything useful. - -All keycodes on this page have a value above `0xFF` (values less are considered the [basic keycodes](basic_keycodes.md)) and won't work with any of the mod/layer-tap keys listed at the bottom. - -* `SAFE_RANGE` is always the last keycode in the quantum list, and where custom lists can begin -* `RESET` puts the keyboard into DFU mode for flashing -* `DEBUG` toggles debug mode -* Shortcuts for bootmagic options (work when bootmagic is off) - * `MAGIC_SWAP_CONTROL_CAPSLOCK` - * `MAGIC_CAPSLOCK_TO_CONTROL` - * `MAGIC_SWAP_LALT_LGUI` - * `MAGIC_SWAP_RALT_RGUI` - * `MAGIC_NO_GUI` - * `MAGIC_SWAP_GRAVE_ESC` - * `MAGIC_SWAP_BACKSLASH_BACKSPACE` - * `MAGIC_HOST_NKRO` - * `MAGIC_SWAP_ALT_GUI`/`AG_SWAP` - * `MAGIC_UNSWAP_CONTROL_CAPSLOCK` - * `MAGIC_UNCAPSLOCK_TO_CONTROL` - * `MAGIC_UNSWAP_LALT_LGUI` - * `MAGIC_UNSWAP_RALT_RGUI` - * `MAGIC_UNNO_GUI` - * `MAGIC_UNSWAP_GRAVE_ESC` - * `MAGIC_UNSWAP_BACKSLASH_BACKSPACE` - * `MAGIC_UNHOST_NKRO` - * `MAGIC_UNSWAP_ALT_GUI`/`AG_NORM` - * `MAGIC_TOGGLE_NKRO` -* `KC_GESC`/`GRAVE_ESC` acts as escape when pressed normally but when pressed with a mod will send a `~` -* `KC_LSPO` left shift when held, open paranthesis when tapped -* `KC_RSPC` right shift when held, close paranthesis when tapped -* `KC_LEAD` the leader key - -* `FUNC(n)`/`F(n)` to call `fn_action` n -* `M(n)` to call macro n -* `MACROTAP(n)` to macro-tap n idk FIXME - -## Audio +All keycodes within quantum are numbers between `0x0000` and `0xFFFF`. Within your `keymap.c` it may look like you have functions and other special cases, but ultimately the C preprocessor will translate those into a single 4 byte integer. QMK has reserved `0x0000` through `0x00FF` for standard keycodes. These are keycodes such as `KC_A`, `KC_1`, and `KC_LCTL`, which are basic keys defined in the USB HID specification. + +On this page we have documented keycodes between `0x00FF` and `0xFFFF` which are used to implement advanced quantum features. If you define your own custom keycodes they will be put into this range as well. Keycodes above `0x00FF` may not be used with any of the mod/layer-tap keys listed + +# Quantum keycodes + +|Name|Description| +|----|-----------| +|`RESET`|Put the keyboard into DFU mode for flashing| +|`DEBUG`|Toggles debug mode| +|`KC_GESC`/`GRAVE_ESC`|Acts as escape when pressed normally but when pressed with Shift or GUI will send a `~`| +|`KC_LSPO`|Left shift when held, open paranthesis when tapped| +|`KC_RSPC`|Right shift when held, close paranthesis when tapped| +|`KC_LEAD`|The [leader key](leader_key.md)| +|`FUNC(n)`/`F(n)`|Call `fn_action(n)`| +|`M(n)`|to call macro n| +|`MACROTAP(n)`|to macro-tap n idk FIXME| + +# Bootmagic Keycodes + +Shortcuts for bootmagic options (these work even when bootmagic is off.) + +|Name|Description| +|----|-----------| +|`MAGIC_SWAP_CONTROL_CAPSLOCK`|Swap Capslock and Left Control| +|`MAGIC_CAPSLOCK_TO_CONTROL`|Treat Capslock like a Control Key| +|`MAGIC_SWAP_LALT_LGUI`|Swap the left Alt and GUI keys| +|`MAGIC_SWAP_RALT_RGUI`|Swap the right Alt and GUI keys| +|`MAGIC_NO_GUI`|Disable the GUI key| +|`MAGIC_SWAP_GRAVE_ESC`|Swap the Grave and Esc key.| +|`MAGIC_SWAP_BACKSLASH_BACKSPACE`|Swap backslack and backspace| +|`MAGIC_HOST_NKRO`|Force NKRO on| +|`MAGIC_SWAP_ALT_GUI`/`AG_SWAP`|Swap Alt and Gui on both sides| +|`MAGIC_UNSWAP_CONTROL_CAPSLOCK`|Disable the Control/Capslock swap| +|`MAGIC_UNCAPSLOCK_TO_CONTROL`|Disable treating Capslock like Control | +|`MAGIC_UNSWAP_LALT_LGUI`|Disable Left Alt and GUI switching| +|`MAGIC_UNSWAP_RALT_RGUI`|Disable Right Alt and GUI switching| +|`MAGIC_UNNO_GUI`|Enable the GUI key | +|`MAGIC_UNSWAP_GRAVE_ESC`|Disable the Grave/Esc swap | +|`MAGIC_UNSWAP_BACKSLASH_BACKSPACE`|Disable the backslash/backspace swap| +|`MAGIC_UNHOST_NKRO`|Force NKRO off| +|`MAGIC_UNSWAP_ALT_GUI`/`AG_NORM`|Disable the Alt/GUI switching| +|`MAGIC_TOGGLE_NKRO`|Turn NKRO on or off| + +# Audio ```c #ifdef AUDIO_ENABLE @@ -126,7 +134,7 @@ MI_TRNSU, // transpose up MI_VEL_x 1-10 MIDI_VELOCITY_MIN = MI_VEL_1, -MIDI_VELOCITY_MAX = MI_VEL_10, +MIDI_VELOCITY_MAX = MI_VEL_9, MI_VELD, // velocity down MI_VELU, // velocity up @@ -149,126 +157,193 @@ MI_MODSD, // decrease modulation speed MI_MODSU, // increase modulation speed #endif // MIDI_ADVANCED -## Backlight +# Backlight -* `BL_x` where x = 0-15 -* `BL_ON = BL_9` -* `BL_OFF = BL_0` -* `BL_DEC` -* `BL_INC` -* `BL_TOGG` -* `BL_STEP` +These keycodes control the backlight. Most keyboards use this for single color in-switch lighting. -## RGB WS2818 LEDs +|Name|Description| +|----|-----------| +|`BL_x`|Set a specific backlight level between 0-9| +|`BL_ON`|An alias for `BL_9`| +|`BL_OFF`|An alias for `BL_0`| +|`BL_DEC`|Turn the backlight level down by 1| +|`BL_INC`|Turn the backlight level up by 1| +|`BL_TOGG`|Toggle the backlight on or off| +|`BL_STEP`|Step through backlight levels, wrapping around to 0 when you reach the top.| -* `RGB_TOG` toggle on/off -* `RGB_MOD` cycle between modes -* `RGB_HUI` hue increase -* `RGB_HUD` hue decrease -* `RGB_SAI` saturation increase -* `RGB_SAD` saturation decrease -* `RGB_VAI` value increase -* `RGB_VAD` value decrease +# RGBLIGHT WS2818 LEDs + +This controls the `RGBLIGHT` functionality. Most keyboards use WS2812 (and compatible) LEDs for underlight or case lighting. + +|Name|Description| +|----|-----------| +|`RGB_TOG`|toggle on/off| +|`RGB_MOD`|cycle through modes| +|`RGB_HUI`|hue increase| +|`RGB_HUD`|hue decrease| +|`RGB_SAI`|saturation increase| +|`RGB_SAD`|saturation decrease| +|`RGB_VAI`|value increase| +|`RGB_VAD`|value decrease| ## Thermal Printer (experimental) -* `PRINT_ON` -* `PRINT_OFF` +|Name|Description| +|----|-----------| +|`PRINT_ON`|Start printing everything the user types| +|`PRINT_OFF`|Stop printing everything the user types| ## Keyboard output selection -* `OUT_AUTO` auto mode -* `OUT_USB` usb only -* `OUT_BT` bluetooth (when `BLUETOOTH_ENABLE`) +This is used when multiple keyboard outputs can be selected. Currently this only allows for switching between USB and Bluetooth on keyboards that support both. + +|Name|Description| +|----|-----------| +|`OUT_AUTO`|auto mode| +|`OUT_USB`|usb only| +|`OUT_BT`|bluetooth (when `BLUETOOTH_ENABLE`)| + +# Modifiers -## Modifiers +These are special keycodes that simulate pressing several modifiers at once. -* `KC_HYPR` LCTL + LSFT + LALT + LGUI - `MOD_HYPR` is the bit version -* `KC_MEH` LCTL + LSFT + LALT - `MOD_MEH` is the bit version +|Name|Description| +|----|-----------| +|`KC_HYPR`|Hold down LCTL + LSFT + LALT + LGUI| +|`KC_MEH`|Hold down LCTL + LSFT + LALT| -### Modifiers with keys +/* FIXME: Should we have these in QMK too? + * |`KC_LCAG`|`LCTL` + `LALT` + `LGUI`| + * |`KC_ALTG`|`RCTL` + `RALT`| + * |`KC_SCMD`/`KC_SWIN`|`LGUI` + `LSFT`| + * |`KC_LCA`|`LCTL` + `LALT`| + */ -* `LCTL(kc)` LCTL + kc -* `LSFT(kc)`/`S(kc)` LSFT + kc -* `LALT(kc)` LALT + kc -* `LGUI(kc)` LGUI + kc -* `RCTL(kc)` RCTL + kc -* `RSFT(kc)` RSFT + kc -* `RALT(kc)` RALT + kc -* `RGUI(kc)` RGUI + kc +## Modifiers with keys -* `HYPR(kc)` LCTL + LSFT + LALT + LGUI + kc -* `MEH(kc)` LCTL + LSFT + LALT + kc -* `LCAG(kc)` LCTL + LALT + LGUI + kc -* `ALTG(kc)` RCTL + RALT + kc -* `SCMD(kc)`/`SWIN(kc)` LGUI + LSFT + kc -* `LCA(kc)` LCTL + LALT + kc +|Name|Description| +|----|-----------| +|`LCTL(kc)`|`LCTL` + `kc`| +|`LSFT(kc)`/`S(kc)`|`LSFT` + `kc`| +|`LALT(kc)`|`LALT` + `kc`| +|`LGUI(kc)`|`LGUI` + `kc`| +|`RCTL(kc)`|`RCTL` + `kc`| +|`RSFT(kc)`|`RSFT` + `kc`| +|`RALT(kc)`|`RALT` + `kc`| +|`RGUI(kc)`|`RGUI` + `kc`| +|`HYPR(kc)`|`LCTL` + `LSFT` + `LALT` + `LGUI` + `kc`| +|`MEH(kc)`|`LCTL` + `LSFT` + `LALT` + `kc`| +|`LCAG(kc)`|`LCTL` + `LALT` + `LGUI` + `kc`| +|`ALTG(kc)`|`RCTL` + `RALT` + `kc`| +|`SCMD(kc)`/`SWIN(kc)`|`LGUI` + `LSFT` + `kc`| +|`LCA(kc)`|`LCTL` + `LALT` + `kc`| -* `OSM(mod)` use mod for one keypress - use mod bits with this +## One Shot Keys -> Mod bits are the 4-letter part of the keycode prefixed with `MOD_`, e.g. `MOD_LCTL` +Most modifiers work by being held down while you push another key. You can use `OSM()` to setup a "One Shot" modifier. When you tap a one shot mod it will remain is a pressed state until you press another key. -### Mod-tap keys +To specify a your modifier you need to pass the `MOD` form of the key. For example, if you want to setup a One Shot Control you would use `OSM(MOD_LCTL)`. + +|Name|Description| +|----|-----------| +|`OSM(mod)`|use mod for one keypress| +|`OSL(layer)`|switch to layer for one keypress| + +## Mod-tap keys These keycodes will press the mod(s) when held, and the key when tapped. They only work with [basic keycodes](basic_keycodes.md). -* `CTL_T(kc)`/`LCTL_T(kc)` LCTL when held, kc when tapped -* `RCTL_T(kc)` RCTL when held, kc when tapped - -* `SFT_T(kc)`/`LSFT_T(kc)` LSFT when held, kc when tapped -* `RSFT_T(kc)` RSFT when held, kc when tapped - -* `ALT_T(kc)`/`LALT_T(kc)` LALT when held, kc when tapped -* `RALT_T(kc)`/`ALGR_T(kc)` RALT when held, kc when tapped - -* `GUI_T(kc)`/`LGUI_T(kc)` LGUI when held, kc when tapped -* `RGUI_T(kc)` RGUI when held, kc when tapped - -* `C_S_T(kc)` LCTL + LSFT when held, kc when tapped -* `MEH_T(kc)` LCTL + LSFT + LALT when held, kc when tapped -* `LCAG_T(kc)` LCTL + LALT + LGUI when held, kc when tapped -* `RCAG_T(kc)` RCTL + RALT + RGUI when held, kc when tapped -* `ALL_T(kc)` LCTL + LSFT + LALT + LGUI when held, kc tapped [more info](http://brettterpstra.com/2012/12/08/a-useful-caps-lock-key/) -* `SCMD_T(kc)`/`SWIN_T(kc)` LGUI + LSFT when held, kc when tapped -* `LCA_T(kc)` LCTL + LALT when held, kc when tapped - -## Shifted symbols - -It's important to remember that all of the keycodes also send a left shift - this may cause unintended actions if unaccounted for. The 4-letter code is preferred in most situations. - -* `KC_TILD`/`KC_TILDE` tilde `~` -* `KC_EXLM`/`KC_EXCLAIM` exclamation mark `!` -* `KC_AT` at sign `@` -* `KC_HASH` hash sign `#` -* `KC_DLR`/`KC_DOLLAR` dollar sign `$` -* `KC_PERC`/`KC_PERCENT` percent sign `%` -* `KC_CIRC`/`KC_CIRCUMFLEX` circumflex `^` -* `KC_AMPR`/`KC_AMPERSAND` ampersand `&` -* `KC_ASTR`/`KC_ASTERISK` asterisk `*` -* `KC_LPRN`/`KC_LEFT_PAREN` left parenthesis `(` -* `KC_RPRN`/`KC_RIGHT_PAREN` right parenthesis `)` -* `KC_UNDS`/`KC_UNDERSCORE` underscore `_` -* `KC_PLUS` plus sign `+` -* `KC_LCBR`/`KC_LEFT_CURLY_BRACE` left curly brace `{` -* `KC_RCBR`/`KC_RIGHT_CURLY_BRACE` right curly brace `}` -* `KC_LT`/`KC_LABK`/`KC_LEFT_ANGLE_BRACKET` left angle bracket `<` -* `KC_GT`/`KC_RABK`/`KC_RIGHT_ANGLE_BRACKET` right angle bracket `>` -* `KC_COLN`/`KC_COLON` colon `:` -* `KC_PIPE` pipe `|` -* `KC_QUES`/`KC_QUESTION` question mark `?` -* `KC_DQT`/`KC_DOUBLE_QUOTE`/`KC_DQUO` double quote `"` - -## Layer adjustments - -* `LT(layer, kc)` turn on layer (0-15) when held, kc ([basic keycodes](basic_keycodes.md)) when tapped -* `TO(layer)` turn on layer when depressed -* `MO(layer)` momentarily turn on layer when depressed (requires `KC_TRNS` on destination layer) -* `DF(layer)` sets the base (default) layer -* `TG(layer)` toggle layer on/off -* `OSL(layer)` switch to layer for one keycode -* `TT(layer)` tap toggle? idk FIXME - -## Unicode - -* `UNICODE(n)`/`UC(n)` if `UNICODE_ENABLE`, this will send characters up to `0x7FFF` -* `X(n)` if `UNICODEMAP_ENABLE`, also sends unicode via a different method \ No newline at end of file +|Name|Description| +|----|-----------| +|`CTL_T(kc)`/`LCTL_T(kc)`|`LCTL` when held, `kc` when tapped| +|`RCTL_T(kc)`|`RCTL` when held, `kc` when tapped| +|`SFT_T(kc)`/`LSFT_T(kc)`|`LSFT` when held, `kc` when tapped| +|`RSFT_T(kc)`|`RSFT` when held, `kc` when tapped| +|`ALT_T(kc)`/`LALT_T(kc)`|`LALT` when held, `kc` when tapped| +|`RALT_T(kc)`/`ALGR_T(kc)`|`RALT` when held, `kc` when tapped| +|`GUI_T(kc)`/`LGUI_T(kc)`|`LGUI` when held, `kc` when tapped| +|`RGUI_T(kc)`|`RGUI` when held, `kc` when tapped| +|`C_S_T(kc)`|`LCTL` + `LSFT` when held, `kc` when tapped| +|`MEH_T(kc)`|`LCTL` + `LSFT` + `LALT` when held, `kc` when tapped| +|`LCAG_T(kc)`|`LCTL` + `LALT` + `LGUI` when held, `kc` when tapped| +|`RCAG_T(kc)`|`RCTL` + `RALT` + `RGUI` when held, `kc` when tapped| +|`ALL_T(kc)`|`LCTL` + `LSFT` + `LALT` + `LGUI` when held, `kc` when tapped [more info](http://brettterpstra.com/2012/12/08/a-useful-caps-lock-key/)| +|`SCMD_T(kc)`/`SWIN_T(kc)`|`LGUI` + `LSFT` when held, `kc` when tapped| +|`LCA_T(kc)`|`LCTL` + `LALT` when held, `kc` when tapped| + +# US ANSI Shifted symbols + +These keycodes correspond to characters that are "shifted" on a standard US ANSI keyboards. They do not have dedicated keycodes but are instead typed by holding down shift and then sending a keycode. + +It's important to remember that all of these keycodes send a left shift - this may cause unintended actions if unaccounted for. The short code is preferred in most situations. + +|Short Name|Long Name|Description| +|----------|---------|-----------| +|`KC_TILD`|`KC_TILDE`|tilde `~`| +|`KC_EXLM`|`KC_EXCLAIM`|exclamation mark `!`| +|`KC_AT`||at sign `@`| +|`KC_HASH`||hash sign `#`| +|`KC_DLR`|`KC_DOLLAR`|dollar sign `$`| +|`KC_PERC`|`KC_PERCENT`|percent sign `%`| +|`KC_CIRC`|`KC_CIRCUMFLEX`|circumflex `^`| +|`KC_AMPR`|`KC_AMPERSAND`|ampersand `&`| +|`KC_ASTR`|`KC_ASTERISK`|asterisk `*`| +|`KC_LPRN`|`KC_LEFT_PAREN`|left parenthesis `(`| +|`KC_RPRN`|`KC_RIGHT_PAREN`|right parenthesis `)`| +|`KC_UNDS`|`KC_UNDERSCORE`|underscore `_`| +|`KC_PLUS`||plus sign `+`| +|`KC_LCBR`|`KC_LEFT_CURLY_BRACE`|left curly brace `{`| +|`KC_RCBR`|`KC_RIGHT_CURLY_BRACE`|right curly brace `}`| +|`KC_LT`/`KC_LABK`|`KC_LEFT_ANGLE_BRACKET`|left angle bracket `<`| +|`KC_GT`/`KC_RABK`|`KC_RIGHT_ANGLE_BRACKET`|right angle bracket `>`| +|`KC_COLN`|`KC_COLON`|colon `:`| +|`KC_PIPE`||pipe `\|`| +|`KC_QUES`|`KC_QUESTION`|question mark `?`| +|`KC_DQT`/`KC_DQUO`|`KC_DOUBLE_QUOTE`|double quote `"`| + +# Layer Changes + +These are keycodes that can be used to change the current layer. + +|Name|Description| +|----|-----------| +|`LT(layer, kc)`|turn on layer (0-15) when held, kc ([basic keycodes](basic_keycodes.md)) when tapped| +|`TO(layer)`|turn on layer when depressed| +|`MO(layer)`|momentarily turn on layer when depressed (requires `KC_TRNS` on destination layer)| +|`DF(layer)`|sets the base (default) layer| +|`TG(layer)`|toggle layer on/off| +|`TT(layer)`|tap toggle? idk FIXME| +|`OSL(layer)`|switch to layer for one keycode| + +# Unicode + +These keycodes can be used in conjuction with the [Unicode](unicode_and_additional_language_support.md) support. + +|`UNICODE(n)`/`UC(n)`|if `UNICODE_ENABLE`, this will send characters up to `0x7FFF`| +|`X(n)`|if `UNICODEMAP_ENABLE`, also sends unicode via a different method| + +# `SAFE_RANGE`, or safely defining custom keycodes + +Sometimes you want to define your own custom keycodes to make your keymap easier to read. QMK provides `SAFE_RANGE` to help you do that. `SAFE_RANGE` is the first available keycode in the `0x0000`-`0xFFFF` range and you can use it when creating your own custom keycode enum: + +``` +enum my_keycodes { + FOO = SAFE_RANGE, + BAR +}; +``` + +You can then use `process_record_user()` to do something with your keycode: + +``` +bool process_record_user(uint16_t keycode, keyrecord_t *record) { + switch (keycode) { + case FOO: + // Do something here + break; + case BAR: + // Do something here + break; + } +} +``` -- cgit v1.2.3 From d59734d3b7f29b95645e96e8560b210f0991d744 Mon Sep 17 00:00:00 2001 From: Jack Humbert Date: Thu, 29 Jun 2017 10:35:09 -0400 Subject: restructure summary --- docs/_summary.md | 63 ++++++++++++++++++++++++++++---------------------------- 1 file changed, 32 insertions(+), 31 deletions(-) diff --git a/docs/_summary.md b/docs/_summary.md index 268ab9954a..f2acad3a71 100644 --- a/docs/_summary.md +++ b/docs/_summary.md @@ -1,35 +1,36 @@ +* Getting started + * [Introduction](home.md) + * [QMK Overview](qmk_overview.md) + * [Build Environment Setup](build_environment_setup.md) + * [Make instructions](make_instructions.md) + * [FAQ: Creating a Keymap](faq_keymap.md) + * [FAQ: Compiling QMK](faq_build.md) -### Getting started -* [Introduction](home.md) -* [QMK Overview](qmk_overview.md) -* [Build Environment Setup](build_environment_setup.md) -* [Make instructions](make_instructions.md) +* Features + * [Layer switching](key_functions.md) + * [Leader Key](leader_key.md) + * [Macros](macros.md) + * [Dynamic Macros](dynamic_macros.md) + * [Space Cadet](space_cadet_shift.md) + * [Tap Dance](tap_dance.md) + * [Mouse keys](mouse_keys.md) -### Making a keymap -* [Keymap overview](keymap.md) -* [Custom Quantum Functions](custom_quantum_functions.md) -* [Keycodes](keycodes.md) - * [Basic Keycodes](basic_keycodes.md) - * [Quantum Keycodes](quantum_keycodes.md) -* [Layer switching](key_functions.md) -* [Leader Key](leader_key.md) -* [Macros](macros.md) -* [Dynamic Macros](dynamic_macros.md) -* [Space Cadet](space_cadet_shift.md) -* [Tap Dance](tap_dance.md) -* [Mouse keys](mouse_keys.md) -* [FAQ: Creating a Keymap](faq_keymap.md) -* [FAQ: Compiling QMK](faq_build.md) -* [The Config File](config_options.md) +* Reference + * [Keymap overview](keymap.md) + * [Keycodes](keycodes.md) + * [Basic Keycodes](basic_keycodes.md) + * [Quantum Keycodes](quantum_keycodes.md) + * [The Config File](config_options.md) + * [Custom Quantum Functions](custom_quantum_functions.md) -### For hardware makers and modders -* [Adding a keyboard to QMK](adding_a_keyboard_to_qmk.md) -* [Porting your keyboard to QMK](porting_your_keyboard_to_qmk.md) -* [Modding your keyboard](modding_your_keyboard.md) -* [Adding features to QMK](adding_features_to_qmk.md) -* [ISP flashing guide](isp_flashing_guide.md) +* For makers and modders + * [Adding a keyboard to QMK](adding_a_keyboard_to_qmk.md) + * [Porting your keyboard to QMK](porting_your_keyboard_to_qmk.md) + * [Modding your keyboard](modding_your_keyboard.md) + * [Adding features to QMK](adding_features_to_qmk.md) + * [ISP flashing guide](isp_flashing_guide.md) -### Other topics -* [General FAQ](faq.md) -* [Differences from TMK](differences_from_tmk.md) -* [Using Eclipse with QMK](eclipse.md) +* Other topics + * [General FAQ](faq.md) + * [Differences from TMK](differences_from_tmk.md) + * [Using Eclipse with QMK](eclipse.md) -- cgit v1.2.3 From 391eae97e49de471a8320f05ed5c8976874aedb0 Mon Sep 17 00:00:00 2001 From: Jack Humbert Date: Thu, 29 Jun 2017 12:13:44 -0400 Subject: testing out new home --- docs/_summary.md | 2 +- docs/features/README.md | 105 +++++++++++++++++++++++++++++++++++++ docs/home.md | 136 ++++++------------------------------------------ 3 files changed, 123 insertions(+), 120 deletions(-) create mode 100644 docs/features/README.md diff --git a/docs/_summary.md b/docs/_summary.md index f2acad3a71..f2229be694 100644 --- a/docs/_summary.md +++ b/docs/_summary.md @@ -6,7 +6,7 @@ * [FAQ: Creating a Keymap](faq_keymap.md) * [FAQ: Compiling QMK](faq_build.md) -* Features +* [Features](features/README.md) * [Layer switching](key_functions.md) * [Leader Key](leader_key.md) * [Macros](macros.md) diff --git a/docs/features/README.md b/docs/features/README.md new file mode 100644 index 0000000000..72187d2d41 --- /dev/null +++ b/docs/features/README.md @@ -0,0 +1,105 @@ +# QMK Features + + +## Space Cadet Shift: The future, built in + +Steve Losh [described](http://stevelosh.com/blog/2012/10/a-modern-space-cadet/) the Space Cadet Shift quite well. Essentially, you hit the left Shift on its own, and you get an opening parenthesis; hit the right Shift on its own, and you get the closing one. When hit with other keys, the Shift key keeps working as it always does. Yes, it's as cool as it sounds. Head on over to the [Space Cadet Shift](space_cadet_shift.md) page to read about it. + +## The Leader key: A new kind of modifier + +Most modifiers have to be held or toggled. But what if you had a key that indicated the start of a sequence? You could press that key and then rapidly press 1-3 more keys to trigger a macro, or enter a special layer, or anything else you might want to do. To learn more about it check out the [Leader Key](leader_key.md) page. + +## Tap Dance: A single key can do 3, 5, or 100 different things + +Hit the semicolon key once, send a semicolon. Hit it twice, rapidly -- send a colon. Hit it three times, and your keyboard's LEDs do a wild dance. That's just one example of what Tap Dance can do. Read more about it on the [Tap Dance](tap_dance.md) page. + +## Temporarily setting the default layer + +`DF(layer)` - sets default layer to _layer_. The default layer is the one at the "bottom" of the layer stack - the ultimate fallback layer. This currently does not persist over power loss. When you plug the keyboard back in, layer 0 will always be the default. It is theoretically possible to work around that, but that's not what `DF` does. + +## Macro shortcuts: Send a whole string when pressing just one key + +How would you like a single keypress to send a whole word, sentence, paragraph, or even document? Head on over to the [Macros](macros.md) page to read up on all aspects of Simple and Dynamic Macros. + +## Additional keycode aliases for software-implemented layouts \(Colemak, Dvorak, etc\) + +Everything is assuming you're in Qwerty \(in software\) by default, but there is built-in support for using a Colemak or Dvorak layout by including this at the top of your keymap: + +``` +#include +``` + +If you use Dvorak, use `keymap_dvorak.h` instead of `keymap_colemak.h` for this line. After including this line, you will get access to: + +* `CM_*` for all of the Colemak-equivalent characters +* `DV_*` for all of the Dvorak-equivalent characters + +These implementations assume you're using Colemak or Dvorak on your OS, not on your keyboard - this is referred to as a software-implemented layout. If your computer is in Qwerty and your keymap is in Colemak or Dvorak, this is referred to as a firmware-implemented layout, and you won't need these features. + +To give an example, if you're using software-implemented Colemak, and want to get an `F`, you would use `CM_F`. Using `KC_F` under these same circumstances would result in `T`. + +## Backlight Breathing + +In order to enable backlight breathing, the following line must be added to your config.h file. + +``` +#define BACKLIGHT_BREATHING +``` + +The following function calls are used to control the breathing effect. + +* `breathing_enable()` - Enable the free-running breathing effect. +* `breathing_disable()` - Disable the free-running breathing effect immediately. +* `breathing_self_disable()` - Disable the free-running breathing effect after the current effect ends. +* `breathing_toggle()` - Toggle the free-running breathing effect. +* `breathing_defaults()` - Reset the speed and brightness settings of the breathing effect. + +The following function calls are used to control the maximum brightness of the breathing effect. + +* `breathing_intensity_set(value)` - Set the brightness of the breathing effect when it is at its max value. +* `breathing_intensity_default()` - Reset the brightness of the breathing effect to the default value based on the current backlight intensity. + +The following function calls are used to control the cycling speed of the breathing effect. + +* `breathing_speed_set(value)` - Set the speed of the breathing effect - how fast it cycles. +* `breathing_speed_inc(value)` - Increase the speed of the breathing effect by a fixed value. +* `breathing_speed_dec(value)` - Decrease the speed of the breathing effect by a fixed value. +* `breathing_speed_default()` - Reset the speed of the breathing effect to the default value. + +The following example shows how to enable the backlight breathing effect when the FUNCTION layer macro button is pressed: + +``` +case MACRO_FUNCTION: + if (record->event.pressed) + { + breathing_speed_set(3); + breathing_enable(); + layer_on(LAYER_FUNCTION); + } + else + { + breathing_speed_set(1); + breathing_self_disable(); + layer_off(LAYER_FUNCTION); + } + break; +``` + +The following example shows how to pulse the backlight on-off-on when the RAISED layer macro button is pressed: + +``` +case MACRO_RAISED: + if (record->event.pressed) + { + layer_on(LAYER_RAISED); + breathing_speed_set(2); + breathing_pulse(); + update_tri_layer(LAYER_LOWER, LAYER_RAISED, LAYER_ADJUST); + } + else + { + layer_off(LAYER_RAISED); + update_tri_layer(LAYER_LOWER, LAYER_RAISED, LAYER_ADJUST); + } + break; +``` \ No newline at end of file diff --git a/docs/home.md b/docs/home.md index df27ebdc5e..334