qmk-dactyl-manuform-a/docs/faq_keymap.md

157 lines
7.7 KiB
Markdown
Raw Normal View History

# Keymap FAQ
2015-01-14 01:11:36 +01:00
This page covers questions people often have about keymaps. If you haven't you should read [Keymap Overview](keymap.md) first.
2015-01-13 21:19:43 +01:00
2017-07-03 10:30:36 +02:00
## What Keycodes Can I Use?
See [Keycodes](keycodes.md) for an index of keycodes available to you. These link to more extensive documentation when available.
2017-07-03 10:30:36 +02:00
Keycodes are actually defined in [common/keycode.h](https://github.com/qmk/qmk_firmware/blob/master/tmk_core/common/keycode.h).
2017-12-09 06:36:32 +01:00
## 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: https://www.keyboard-layout-editor.com/#/gists/bf431647d1001cff5eff20ae55621e9a -->
![Keyboard Layout Image](https://i.imgur.com/5wsh5wM.png)
## How Can I Make Custom Names For Complex Keycodes?
Sometimes, for readability's sake, it's useful to define custom names for some keycodes. People often define custom names using `#define`. For example:
```c
#define FN_CAPS LT(_FL, KC_CAPSLOCK)
#define ALT_TAB LALT(KC_TAB)
```
This will allow you to use `FN_CAPS` and `ALT_TAB` in your keymap, keeping it more readable.
## 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:
Remove Full Bootmagic (#13846) * disambiguate Bootmagic rules in keymaps The files edited by this commit were added at a point in time where `BOOTMAGIC_ENABLE = yes` enabled full Bootmagic. This commit edits the files to specify that full Bootmagic is intended. * remove BOOTMAGIC_ENABLE=full setting * unify commented BOOTMAGIC_ENABLE rules in keyboards Explicitly sets `BOOTMAGIC_ENABLE = no` in keyboards where the rule was commented out. Command: ``` find keyboards/ -type f -name 'rules.mk' -and -not -path '*/keymaps/*' -exec sed -i -e 's;#[ \t]*\(BOOTMAGIC_ENABLE\)[ \t=]\+\([a-zA-Z]\+\).*;\1 = no # Virtual DIP switch configuration;g' {} + ``` * remove commented Bootmagic rules from keymap/user level Command: ``` find keyboards/ layouts/ users/ -type f -name 'rules.mk' -exec sed -i -e '/#.*\(BOOTMAGIC_ENABLE\)[ \t=]\+\([a-z]\+\).*/d' {} + ``` * update keyboard BOOTMAGIC_ENABLE rule formatting Sets the formatting of BOOTMAGIC_ENABLE rules to `BOOTMAGIC_ENABLE = [value]`, without the inline comments (which will be replaced later). Command: ``` find keyboards/ -type f -name 'rules.mk' -and -not -path '*/keymaps/*' -exec sed -i -e 's;\(BOOTMAGIC_ENABLE\)[ \t=]\+\([a-z]\+\).*;\1 = \2;g' '{}' + ``` * update keyboards' BOOTMAGIC_ENABLE settings Updates keyboard `rules.mk` files to use `BOOTMAGIC_ENABLE = lite` where `BOOTMAGIC_ENABLE = full` was being used. Command: ``` find keyboards/ -type f -name 'rules.mk' -and -not -path '*/keymaps/*' -exec sed -i -e 's;\(BOOTMAGIC_ENABLE = \)full;\1lite;g' '{}' + ``` * update keymap/user BOOTMAGIC_ENABLE settings Updates keymap/user `rules.mk` files to use `BOOTMAGIC_ENABLE = lite` where `BOOTMAGIC_ENABLE = full` was being used. Commands: ``` find keyboards/ -type f -name 'rules.mk' -and -path '*/keymaps/*' -exec sed -i -e 's;\(BOOTMAGIC_ENABLE[ \t=]\+\)full;\1lite;g' '{}' + find layouts/community/ users/ -type f -name 'rules.mk' -exec sed -i -e 's;\(BOOTMAGIC_ENABLE[ \t=]\+\)full;\1lite;g' '{}' + ``` * remove and replace inline comments in keyboards and keymap/user files Removes and replaces the inline comments, which have been updated to read `Enable Bootmagic Lite`. Commands: ``` find keyboards/ -type f -name 'rules.mk' -and -path '*/keymaps/*' -exec sed -i -e 's;\(BOOTMAGIC_ENABLE\)[ \t=]\+\([a-z]\+\).*;\1 = \2;g' '{}' + find layouts/community/ users/ -type f -name 'rules.mk' -exec sed -i -e 's;\(BOOTMAGIC_ENABLE\)[ \t=]\+\([a-z]\+\).*;\1 = \2;g' '{}' + find keyboards/ layouts/community/ users/ -type f -name 'rules.mk' -exec sed -i -e 's;\(BOOTMAGIC_ENABLE = lite\);\1 # Enable Bootmagic Lite;g' '{}' + find keyboards/ layouts/community/ users/ -type f -name 'rules.mk' -exec sed -i -e 's;\(BOOTMAGIC_ENABLE = yes\);\1 # Enable Bootmagic Lite;g' '{}' + find keyboards/ layouts/community/ users/ -type f -name 'rules.mk' -exec sed -i -e 's;\(BOOTMAGIC_ENABLE = no\);\1 # Enable Bootmagic Lite;g' '{}' + ``` * rename improperly named makefiles Some files intended to be used as makefiles had improper names causing them to not be used as intended when building. This commit corrects the filenames of the affected files. * update renamed file with new rule formatting * update QMK's template files Updates QMK's `rules.mk` templates to use the new inline comment. * update QMK Docs - remove documentation of full Bootmagic - update links to Bootmagic Lite doc - add doc for Magic Keycodes * rules.mk patch for coarse/ixora and coarse/vinta
2021-08-07 08:59:56 +02:00
* [Bootmagic Lite](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.
2017-12-09 06:36:32 +01:00
## `KC_SYSREQ` Isn't Working
2015-01-13 21:16:09 +01:00
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'.
2015-01-13 21:15:42 +01:00
See [issue #168](https://github.com/tmk/tmk_keyboard/issues/168) and
* https://en.wikipedia.org/wiki/Magic_SysRq_key
* https://en.wikipedia.org/wiki/System_request
2015-01-13 21:03:47 +01:00
2018-08-05 12:09:42 +02:00
## Power Keys Aren't Working
2014-11-27 02:40:02 +01:00
2018-08-05 12:09:42 +02:00
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.
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.
2014-11-27 02:40:02 +01:00
2017-12-09 06:36:32 +01:00
## One Shot Modifier
2017-12-09 06:49:07 +01:00
Solves my personal 'the' problem. I often got 'the' or 'THe' wrongly instead of 'The'. One Shot Shift mitigates this for me.
2014-11-27 02:40:02 +01:00
https://github.com/tmk/tmk_keyboard/issues/67
2017-12-09 06:36:32 +01:00
## Modifier/Layer Stuck
2014-11-27 02:40:02 +01:00
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
* https://geekhack.org/index.php?topic=57008.msg1492604#msg1492604
* https://github.com/tmk/tmk_keyboard/issues/248
2014-11-27 02:40:02 +01:00
## Mechanical Lock Switch Support
This feature is for *mechanical lock switch* like [this Alps one](https://deskthority.net/wiki/Alps_SKCL_Lock). You can enable it by adding this to your `config.h`:
2017-12-09 06:56:58 +01:00
2017-07-03 10:30:36 +02:00
```
#define LOCKING_SUPPORT_ENABLE
#define LOCKING_RESYNC_ENABLE
```
2014-11-27 02:40:02 +01:00
2017-07-03 10:30:36 +02:00
After enabling this feature use keycodes `KC_LCAP`, `KC_LNUM` and `KC_LSCR` in your keymap instead.
2014-11-27 03:11:41 +01:00
2017-07-03 10:30:36 +02:00
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`.***
2014-11-27 03:11:41 +01:00
2017-12-09 06:36:32 +01:00
## Input Special Characters Other Than ASCII like Cédille 'Ç'
2014-11-27 03:11:41 +01:00
See the [Unicode](feature_unicode.md) feature.
2015-03-07 06:19:44 +01:00
2018-08-05 17:51:33 +02:00
## `Fn` Key on macOS
2015-03-07 06:19:44 +01:00
2018-08-05 17:51:33 +02:00
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.
2015-03-07 06:19:44 +01:00
2018-08-05 17:51:33 +02:00
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.
2015-03-07 06:19:44 +01:00
2018-08-05 17:51:33 +02:00
See [this issue](https://github.com/qmk/qmk_firmware/issues/2179) for detailed information.
2015-03-07 06:19:44 +01:00
2017-12-09 06:36:32 +01:00
## Keys Supported in Mac OSX?
2015-03-07 06:19:44 +01:00
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/Cosmo_USB2ADB.c
And `IOHIDConsumer::dispatchConsumerEvent` handles Consumer page usages.
2015-03-24 08:30:35 +01:00
https://opensource.apple.com/source/IOHIDFamily/IOHIDFamily-606.1.7/IOHIDFamily/IOHIDConsumer.cpp
2017-12-09 06:36:32 +01:00
## JIS Keys in Mac OSX
2015-03-24 08:39:28 +01:00
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.
2015-03-24 08:30:35 +01:00
2015-03-24 08:39:04 +01:00
* Enable NFER Key on PC keyboard
* Enable XFER Key on PC keyboard
* Enable KATAKANA Key on PC keyboard
2015-03-24 08:30:35 +01:00
2015-05-16 16:58:50 +02:00
https://pqrs.org/osx/karabiner/seil.html
2017-12-09 06:36:32 +01:00
## RN-42 Bluetooth Doesn't Work with Karabiner
2015-05-16 16:58:50 +02:00
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
2017-12-09 06:49:07 +01:00
See these for the detail of this problem.
2015-05-16 16:58:50 +02:00
https://github.com/tmk/tmk_keyboard/issues/213
2015-10-04 20:51:26 +02:00
https://github.com/tekezo/Karabiner/issues/403
2017-12-09 06:36:32 +01:00
## Esc and <code>&#96;</code> on a Single Key
2015-10-06 08:49:17 +02:00
See the [Grave Escape](feature_grave_esc.md) feature.
2015-10-06 21:09:04 +02:00
2015-10-21 00:03:01 +02:00
## Eject on Mac OSX
2017-07-03 10:30:36 +02:00
`KC_EJCT` keycode works on OSX. https://github.com/tmk/tmk_keyboard/issues/250
2015-10-28 22:03:25 +01:00
It seems Windows 10 ignores the code and Linux/Xorg recognizes but has no mapping by default.
2015-10-28 21:50:25 +01:00
2015-12-09 04:03:07 +01:00
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.
2017-12-09 06:36:32 +01:00
## What's `weak_mods` and `real_mods` in `action_util.c`
2015-12-09 04:03:07 +01:00
___TO BE IMPROVED___
real_mods is intended to retains state of real/physical modifier key state, while
2017-12-09 06:49:07 +01:00
weak_mods retains state of virtual or temporary modifiers which should not affect state real modifier key.
2015-12-09 04:03:07 +01:00
2017-12-09 06:56:58 +01:00
Let's say you hold down physical left shift key and type ACTION_MODS_KEY(LSHIFT, KC_A),
2015-12-09 04:03:07 +01:00
with weak_mods,
2015-12-09 04:04:14 +01:00
* (1) hold down left shift: real_mods |= MOD_BIT(LSHIFT)
* (2) press ACTION_MODS_KEY(LSHIFT, KC_A): weak_mods |= MOD_BIT(LSHIFT)
2017-12-09 06:49:07 +01:00
* (3) release ACTION_MODS_KEY(LSHIFT, KC_A): weak_mods &= ~MOD_BIT(LSHIFT)
2015-12-09 04:03:07 +01:00
real_mods still keeps modifier state.
without weak mods,
2015-12-09 04:04:14 +01:00
* (1) hold down left shift: real_mods |= MOD_BIT(LSHIFT)
* (2) press ACTION_MODS_KEY(LSHIFT, KC_A): real_mods |= MOD_BIT(LSHIFT)
* (3) release ACTION_MODS_KEY(LSHIFT, KC_A): real_mods &= ~MOD_BIT(LSHIFT)
2015-12-09 04:03:07 +01:00
here real_mods lost state for 'physical left shift'.
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