Merge branch 'master' into default_atreus_layout

[qmk_firmware.git] / doc / keymap.md

diff --git a/doc/keymap.md b/doc/keymap.md
index d1985e567c86d54ad34a59d1820434910744c66d..2b0d2cd9592111d6a63eccb8eb5c3bc9a0fb6ace 100644 (file)
--- a/doc/keymap.md
+++ b/doc/keymap.md
@@ -455,6 +455,35 @@ Turn the backlight on and off without changing level.
 
 
 
+### 2.6 Swap-Hands Action
+The swap-hands action allows support for one-handed keyboards without requiring a separate layer. Set `ONEHAND_ENABLE` in the Makefile and define a `hand_swap_config` entry in your keymap. Now whenever the `ACTION_SWAP_HANDS` command key is pressed the keyboard is mirrored. For instance, to type "Hello, World" on QWERTY you would type `^Ge^s^s^w^c W^wr^sd`
+
+### 2.6.1 Configuration
+The configuration table is a simple 2-dimensional array to map from column/row to new column/row. Example `hand_swap_config` for Planck:
+
+```
+const keypos_t hand_swap_config[MATRIX_ROWS][MATRIX_COLS] = {
+  {{11, 0}, {10, 0}, {9, 0}, {8, 0}, {7, 0}, {6, 0}, {5, 0}, {4, 0}, {3, 0}, {2, 0}, {1, 0}, {0, 0}},
+  {{11, 1}, {10, 1}, {9, 1}, {8, 1}, {7, 1}, {6, 1}, {5, 1}, {4, 1}, {3, 1}, {2, 1}, {1, 1}, {0, 1}},
+  {{11, 2}, {10, 2}, {9, 2}, {8, 2}, {7, 2}, {6, 2}, {5, 2}, {4, 2}, {3, 2}, {2, 2}, {1, 2}, {0, 2}},
+  {{11, 3}, {10, 3}, {9, 3}, {8, 3}, {7, 3}, {6, 3}, {5, 3}, {4, 3}, {3, 3}, {2, 3}, {1, 3}, {0, 3}},
+};
+```
+
+Note that the array indices are reversed same as the matrix and the values are of type `keypos_t` which is `{col, row}` and all values are zero-based. In the example above, `hand_swap_config[2][4]` (third row, fifth column) would return {7, 2} (third row, eighth column).
+
+### 2.6.2 Advanced Swap Commands
+- **`ACTION_SWAP_HANDS()`** Swaps hands when pressed, returns to normal when released (momentary).
+- **`ACTION_SWAP_HANDS_TOGGLE()`** Toggles swap on and off with every keypress.
+- **`ACTION_SWAP_HANDS_TAP_TOGGLE()`** Toggles with a tap; momentary when held.
+- **`ACTION_SWAP_HANDS_TAP_KEY(key)`** Sends `key` with a tap; momentary swap when held.
+- **`ACTION_SWAP_HANDS_ON_OFF()`** Alias for `ACTION_SWAP_HANDS()`
+- **`ACTION_SWAP_HANDS_OFF_ON()`** Momentarily turns off swap.
+- **`ACTION_SWAP_HANDS_ON()`** Turns on swapping and leaves it on.
+- **`ACTION_SWAP_HANDS_OFF()`** Turn off swapping and leaves it off. Good for returning to a known state.
+
+
+
 ## 3. Layer switching Example
 There are some ways to switch layer with 'Layer' actions.
 
@@ -520,6 +549,9 @@ Layer switching with tap key:
 
 [dual_role]: http://en.wikipedia.org/wiki/Modifier_key#Dual-role_keys
 
+When user hold a key after tap, it repeat the tapped key rather to hold a modifier key.
+If you prefer to hold a modifier instead, define `TAPPING_FORCE_HOLD` in `config.h`.
+See https://github.com/qmk/qmk_firmware/issues/889 for the detail.
 
 ### 4.2 Tap Toggle
 This is a feature to assign both toggle layer and momentary switch layer action to just same one physical key. It works as momentary layer switch when holding a key but toggle switch with several taps.