-# Frequently Asked Keymap Questions
+# Keymap FAQ
-This page covers questions people often have about keymaps. If you haven't you should read [Keymap Overview](keymap.html) first.
+This page covers questions people often have about keymaps. If you haven't you should read [Keymap Overview](keymap.md) first.
## What Keycodes Can I Use?
-See [Basic Keycodes](keycodes.html) and [Quantum Keycodes](quantum_keycodes.html) for most of the keys you can define.
+See [Keycodes](keycodes.md) for an index of keycodes available to you. These link to more extensive documentation when available.
Keycodes are actually defined in [common/keycode.h](https://github.com/qmk/qmk_firmware/blob/master/tmk_core/common/keycode.h).
-## `KC_SYSREQ` isn't working
+## What Are the Default Keycodes?
+
+There are 3 standard keyboard layouts in use around the world- ANSI, ISO, and JIS. North America primarily uses ANSI, Europe and Africa primarily use ISO, and Japan uses JIS. Regions not mentioned typically use either ANSI or ISO. The keycodes corresponding to these layouts are shown here:
+
+<!-- Source for this image: http://www.keyboard-layout-editor.com/#/gists/bf431647d1001cff5eff20ae55621e9a -->
+
+
+## Some Of My Keys Are Swapped Or Not Working
+
+QMK has two features, Bootmagic and Command, which allow you to change the behavior of your keyboard on the fly. This includes, but is not limited to, swapping Ctrl/Caps, disabling Gui, swapping Alt/Gui, swapping Backspace/Backslash, disabling all keys, and other behavioral modifications.
+
+As a quick fix try holding down `Space`+`Backspace` while you plug in your keyboard. This will reset the stored settings on your keyboard, returning those keys to normal operation. If that doesn't work look here:
+
+* [Bootmagic](feature_bootmagic.md)
+* [Command](feature_command.md)
+
+## The Menu Key Isn't Working
+
+The key found on most modern keyboards that is located between `KC_RGUI` and `KC_RCTL` is actually called `KC_APP`. This is because when that key was invented there was already a key named `MENU` in the relevant standards, so MS chose to call that the `APP` key.
+
+## `KC_SYSREQ` Isn't Working
Use keycode for Print Screen(`KC_PSCREEN` or `KC_PSCR`) instead of `KC_SYSREQ`. Key combination of 'Alt + Print Screen' is recognized as 'System request'.
See [issue #168](https://github.com/tmk/tmk_keyboard/issues/168) and
-- http://en.wikipedia.org/wiki/Magic_SysRq_key
-- http://en.wikipedia.org/wiki/System_request
+* http://en.wikipedia.org/wiki/Magic_SysRq_key
+* http://en.wikipedia.org/wiki/System_request
-## Power key doesn't work
-Use `KC_PWR` instead of `KC_POWER` or vice versa.
-- `KC_PWR` works with Windows and Linux, not with OSX.
-- `KC_POWER` works with OSX and Linux, not with Windows.
+## Power Keys Aren't Working
-More info: http://geekhack.org/index.php?topic=14290.msg1327264#msg1327264
+Somewhat confusingly, there are two "Power" keycodes in QMK: `KC_POWER` in the Keyboard/Keypad HID usage page, and `KC_SYSTEM_POWER` (or `KC_PWR`) in the Consumer page.
-## Oneshot modifier
-Solves my personal 'the' problem. I often got 'the' or 'THe' wrongly instead of 'The'. Oneshot Shift mitgates this for me.
+The former is only recognized on macOS, while the latter, `KC_SLEP` and `KC_WAKE` are supported by all three major operating systems, so it is recommended to use those instead. Under Windows, these keys take effect immediately, however on macOS they must be held down until a dialog appears.
+
+## One Shot Modifier
+Solves my personal 'the' problem. I often got 'the' or 'THe' wrongly instead of 'The'. One Shot Shift mitigates this for me.
https://github.com/tmk/tmk_keyboard/issues/67
-## Modifier/Layer stuck
+## Modifier/Layer Stuck
Modifier keys or layers can be stuck unless layer switching is configured properly.
For Modifier keys and layer actions you have to place `KC_TRANS` on same position of destination layer to unregister the modifier key or return to previous layer on release event.
-- https://github.com/tmk/tmk_core/blob/master/doc/keymap.md#31-momentary-switching
-- http://geekhack.org/index.php?topic=57008.msg1492604#msg1492604
-- https://github.com/tmk/tmk_keyboard/issues/248
+* https://github.com/tmk/tmk_core/blob/master/doc/keymap.md#31-momentary-switching
+* http://geekhack.org/index.php?topic=57008.msg1492604#msg1492604
+* https://github.com/tmk/tmk_keyboard/issues/248
## Mechanical Lock Switch Support
This feature is for *mechanical lock switch* like [this Alps one](http://deskthority.net/wiki/Alps_SKCL_Lock). You can enable it by adding this to your `config.h`:
-
+
```
#define LOCKING_SUPPORT_ENABLE
#define LOCKING_RESYNC_ENABLE
Old vintage mechanical keyboards occasionally have lock switches but modern ones don't have. ***You don't need this feature in most case and just use keycodes `KC_CAPS`, `KC_NLCK` and `KC_SLCK`.***
-## Input special charactors other than ASCII like Cédille 'Ç'
+## Input Special Characters Other Than ASCII like Cédille 'Ç'
NO UNIVERSAL METHOD TO INPUT THOSE WORKS OVER ALL SYSTEMS. You have to define **MACRO** in way specific to your OS or layout.
See this post for example **MACRO** code.
http://deskthority.net/workshop-f7/tmk-keyboard-firmware-collection-t4478-120.html#p195620
On **Windows** you can use `AltGr` key or **Alt code**.
-- http://en.wikipedia.org/wiki/AltGr_key
-- http://en.wikipedia.org/wiki/Alt_code
+* http://en.wikipedia.org/wiki/AltGr_key
+* http://en.wikipedia.org/wiki/Alt_code
On **Mac** OS defines `Option` key combinations.
-- http://en.wikipedia.org/wiki/Option_key#Alternative_keyboard_input
+* http://en.wikipedia.org/wiki/Option_key#Alternative_keyboard_input
On **Xorg** you can use `compose` key, instead.
-- http://en.wikipedia.org/wiki/Compose_key
+* http://en.wikipedia.org/wiki/Compose_key
And see this for **Unicode** input.
-- http://en.wikipedia.org/wiki/Unicode_input
+* http://en.wikipedia.org/wiki/Unicode_input
+## `Fn` Key on macOS
-## Apple/Mac keyboard Fn
-Not supported.
+Unlike most Fn keys, the one on Apple keyboards actually has its own keycode... sort of. It takes the place of the sixth keycode in a basic 6KRO HID report -- so an Apple keyboard is in fact only 5KRO.
-Apple/Mac keyboard sends keycode for Fn unlike most of other keyboards.
-I think you can send Apple Fn key using Apple venter specific Page 0xff01 and usage 0x0003. But you have to change HID Report Descriptor for this, of course.
+It is technically possible to get QMK to send this key. However, doing so requires modification of the report format to add the state of the Fn key.
+Even worse, it is not recognized unless the keyboard's VID and PID match that of a real Apple keyboard. The legal issues that official QMK support for this feature may create mean it is unlikely to happen.
-https://opensource.apple.com/source/IOHIDFamily/IOHIDFamily-606.1.7/IOHIDFamily/AppleHIDUsageTables.h
+See [this issue](https://github.com/qmk/qmk_firmware/issues/2179) for detailed information.
-## Media control keys in Mac OSX
-#### KC_MNXT and KC_MPRV does not work on Mac
+## Media Control Keys in Mac OSX
+#### KC_MNXT and KC_MPRV Does Not Work on Mac
Use `KC_MFFD`(`KC_MEDIA_FAST_FORWARD`) and `KC_MRWD`(`KC_MEDIA_REWIND`) instead of `KC_MNXT` and `KC_MPRV`.
See https://github.com/tmk/tmk_keyboard/issues/195
-## Keys supported in Mac OSX?
+## Keys Supported in Mac OSX?
You can know which keycodes are supported in OSX from this source code.
`usb_2_adb_keymap` array maps Keyboard/Keypad Page usages to ADB scancodes(OSX internal keycodes).
https://opensource.apple.com/source/IOHIDFamily/IOHIDFamily-606.1.7/IOHIDFamily/IOHIDConsumer.cpp
-## JIS keys in Mac OSX
+## JIS Keys in Mac OSX
Japanese JIS keyboard specific keys like `無変換(Muhenkan)`, `変換(Henkan)`, `ひらがな(hiragana)` are not recognized on OSX. You can use **Seil** to enable those keys, try following options.
* Enable NFER Key on PC keyboard
https://pqrs.org/osx/karabiner/seil.html
-## RN-42 Bluetooth doesn't work with Karabiner
+## RN-42 Bluetooth Doesn't Work with Karabiner
Karabiner - Keymapping tool on Mac OSX - ignores inputs from RN-42 module by default. You have to enable this option to make Karabiner working with your keyboard.
https://github.com/tekezo/Karabiner/issues/403#issuecomment-102559237
-See these for the deail of this problem.
+See these for the detail of this problem.
https://github.com/tmk/tmk_keyboard/issues/213
https://github.com/tekezo/Karabiner/issues/403
-## Esc and `~ on a key
-
-Use `GRAVE_ESC` or `KC_GESC` in your keymap. `GUI`+`GRAVE_ESC` results in `` ` `` and `SHIFT`+`GRAVE_ESC` results in `~`.
+## Esc and <code>`</code> on a Single Key
-Note that this will break the CTRL+SHIFT+ESC shortcut to the Windows task manager. Use `#define GRAVE_ESC_CTRL_OVERRIDE` in your `config.h` to get the shortcut back. With this option, `ESC_GRAVE` results in `ESC` if `CTRL` is held, even if `SHIFT` or `GUI` are also held.
+See the [Grave Escape](feature_grave_esc.md) feature.
-## Arrow on Right Modifier keys with Dual-Role
-This turns right modifer keys into arrow keys when the keys are tapped while still modifiers when the keys are hold. In TMK the dual-role function is dubbed **TAP**.
+## Arrow on Right Modifier Keys with Dual-Role
+This turns right modifier keys into arrow keys when the keys are tapped while still modifiers when the keys are hold. In TMK the dual-role function is dubbed **TAP**.
```
#include "keymap_common.h"
*/
const uint8_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
/* 0: qwerty */
- [0] = KEYMAP( \
+ [0] = LAYOUT( \
ESC, 1, 2, 3, 4, 5, 6, 7, 8, 9, 0, MINS,EQL, NUHS,BSPC, \
TAB, Q, W, E, R, T, Y, U, I, O, P, LBRC,RBRC,BSLS, \
LCTL,A, S, D, F, G, H, J, K, L, SCLN,QUOT,ENT, \
LSFT,NUBS,Z, X, C, V, B, N, M, COMM,DOT, SLSH,FN0, ESC, \
FN4, LGUI,LALT, SPC, APP, FN2, FN1, FN3),
- [1] = KEYMAP( \
+ [1] = LAYOUT( \
GRV, F1, F2, F3, F4, F5, F6, F7, F8, F9, F10, F11, F12, TRNS,TRNS, \
TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,\
TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS, \
Not sure what keycode Eject is on genuine Apple keyboard actually. HHKB uses `F20` for Eject key(`Fn+f`) on Mac mode but this is not same as Apple Eject keycode probably.
-## What's weak_mods and real_mods in action_util.c
+## What's `weak_mods` and `real_mods` in `action_util.c`
___TO BE IMPROVED___
real_mods is intended to retains state of real/physical modifier key state, while
-weak_mods retains state of virtual or temprary modifiers which should not affect state real modifier key.
+weak_mods retains state of virtual or temporary modifiers which should not affect state real modifier key.
-Let's say you hold down physical left shift key and type ACTION_MODS_KEY(LSHIFT, KC_A),
+Let's say you hold down physical left shift key and type ACTION_MODS_KEY(LSHIFT, KC_A),
with weak_mods,
* (1) hold down left shift: real_mods |= MOD_BIT(LSHIFT)
* (2) press ACTION_MODS_KEY(LSHIFT, KC_A): weak_mods |= MOD_BIT(LSHIFT)
-* (3) release ACTION_MODS_KEY(LSHIFT, KC_A): waek_mods &= ~MOD_BIT(LSHIFT)
+* (3) release ACTION_MODS_KEY(LSHIFT, KC_A): weak_mods &= ~MOD_BIT(LSHIFT)
real_mods still keeps modifier state.
without weak mods,
weak_mods is ORed with real_mods when keyboard report is sent.
https://github.com/tmk/tmk_core/blob/master/common/action_util.c#L57
-
-## Timer functionality
-
-It's possible to start timers and read values for time-specific events - here's an example:
-
-```c
-static uint16_t key_timer;
-key_timer = timer_read();
-
-if (timer_elapsed(key_timer) < 100) {
- // do something if less than 100ms have passed
-} else {
- // do something if 100ms or more have passed
-}
-```
-
-It's best to declare the `static uint16_t key_timer;` at the top of the file, outside of any code blocks you're using it in.
projects / qmk_firmware.git / blobdiff