From 384fef72d3a08f6bdc4e8557caf0bb78953dab32 Mon Sep 17 00:00:00 2001 From: noroadsleft Date: Thu, 21 Feb 2019 15:24:44 -0800 Subject: [PATCH] Replace instances of KEYMAP with LAYOUT Many instances in the QMK Docs referenced KEYMAP macros, which is outdated terminology. Replaced most instances of KEYMAP with LAYOUT, to reflect the desired usage. --- docs/faq_keymap.md | 4 ++-- docs/feature_advanced_keycodes.md | 2 +- docs/feature_macros.md | 6 +++--- docs/hand_wire.md | 2 +- docs/keymap.md | 8 ++++---- ...r_keyboard_to_qmk_(arm_and_other_chibios_cpus).md | 4 ++-- docs/understanding_qmk.md | 12 ++++++------ 7 files changed, 19 insertions(+), 19 deletions(-) diff --git a/docs/faq_keymap.md b/docs/faq_keymap.md index ae01e93878..0a627469e7 100644 --- a/docs/faq_keymap.md +++ b/docs/faq_keymap.md @@ -151,13 +151,13 @@ This turns right modifier keys into arrow keys when the keys are tapped while st */ 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, \ diff --git a/docs/feature_advanced_keycodes.md b/docs/feature_advanced_keycodes.md index 9edb9fcebc..b20acf3c44 100644 --- a/docs/feature_advanced_keycodes.md +++ b/docs/feature_advanced_keycodes.md @@ -11,7 +11,7 @@ People often define custom names using `#define`. For example: #define ALT_TAB LALT(KC_TAB) ``` -This will allow you to use `FN_CAPS` and `ALT_TAB` in your `KEYMAP()`, keeping it more readable. +This will allow you to use `FN_CAPS` and `ALT_TAB` in your keymap, keeping it more readable. ## Caveats diff --git a/docs/feature_macros.md b/docs/feature_macros.md index aa13fb97f4..79419abd20 100644 --- a/docs/feature_macros.md +++ b/docs/feature_macros.md @@ -183,11 +183,11 @@ A macro can include the following commands: ### Mapping a Macro to a Key -Use the `M()` function within your `KEYMAP()` to call a macro. For example, here is the keymap for a 2-key keyboard: +Use the `M()` function within your keymap to call a macro. For example, here is the keymap for a 2-key keyboard: ```c const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = { - [0] = KEYMAP( + [0] = LAYOUT( M(0), M(1) ), }; @@ -216,7 +216,7 @@ If you have a bunch of macros you want to refer to from your keymap while keepin #define M_BYE M(1) const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = { - [0] = KEYMAP( + [0] = LAYOUT( M_HI, M_BYE ), }; diff --git a/docs/hand_wire.md b/docs/hand_wire.md index ba2eee7125..697a508052 100644 --- a/docs/hand_wire.md +++ b/docs/hand_wire.md @@ -216,7 +216,7 @@ Farther down are `MATRIX_ROW_PINS` and `MATRIX_COL_PINS`. Change their definitio ### `.h` -The next file you'll want to look at is `.h`. You're going to want to rewrite the `KEYMAP` definition - the format and syntax here is extremely important, so pay attention to how things are setup. The first half of the definition are considered the arguments - this is the format that you'll be following in your keymap later on, so you'll want to have as many k*xy* variables here as you do keys. The second half is the part that the firmware actually looks at, and will contain gaps depending on how you wired your matrix. +The next file you'll want to look at is `.h`. You're going to want to rewrite the `LAYOUT` definition - the format and syntax here is extremely important, so pay attention to how things are setup. The first half of the definition are considered the arguments - this is the format that you'll be following in your keymap later on, so you'll want to have as many k*xy* variables here as you do keys. The second half is the part that the firmware actually looks at, and will contain gaps depending on how you wired your matrix. We'll dive into how this will work with the following example. Say we have a keyboard like this: diff --git a/docs/keymap.md b/docs/keymap.md index 382a0e911b..49e6654a26 100644 --- a/docs/keymap.md +++ b/docs/keymap.md @@ -1,6 +1,6 @@ # Keymap Overview -QMK keymaps are defined inside a C source file. The data structure is an array of arrays. The outer array is a list of layer arrays while the inner layer array is a list of keys. Most keyboards define a `KEYMAP()` macro to help you create this array of arrays. +QMK keymaps are defined inside a C source file. The data structure is an array of arrays. The outer array is a list of layer arrays while the inner layer array is a list of keys. Most keyboards define a `LAYOUT()` macro to help you create this array of arrays. ## Keymap and Layers @@ -119,7 +119,7 @@ The main part of this file is the `keymaps[]` definition. This is where you list const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = { -After this you'll find a list of KEYMAP() macros. A KEYMAP() is simply a list of keys to define a single layer. Typically you'll have one or more "base layers" (such as QWERTY, Dvorak, or Colemak) and then you'll layer on top of that one or more "function" layers. Due to the way layers are processed you can't overlay a "lower" layer on top of a "higher" layer. +After this you'll find a list of LAYOUT() macros. A LAYOUT() is simply a list of keys to define a single layer. Typically you'll have one or more "base layers" (such as QWERTY, Dvorak, or Colemak) and then you'll layer on top of that one or more "function" layers. Due to the way layers are processed you can't overlay a "lower" layer on top of a "higher" layer. `keymaps[][MATRIX_ROWS][MATRIX_COLS]` in QMK holds the 16 bit action code (sometimes referred as the quantum keycode) in it. For the keycode representing typical keys, its high byte is 0 and its low byte is the USB HID usage ID for keyboard. @@ -131,7 +131,7 @@ Here is an example of the Clueboard's base layer: /* Keymap _BL: Base Layer (Default Layer) */ - [_BL] = KEYMAP( + [_BL] = LAYOUT( F(0), KC_1, KC_2, KC_3, KC_4, KC_5, KC_6, KC_7, KC_8, KC_9, KC_0, KC_MINS, KC_EQL, KC_GRV, KC_BSPC, KC_PGUP, \ KC_TAB, KC_Q, KC_W, KC_E, KC_R, KC_T, KC_Y, KC_U, KC_I, KC_O, KC_P, KC_LBRC, KC_RBRC, KC_BSLS, KC_PGDN, \ KC_CAPS, KC_A, KC_S, KC_D, KC_F, KC_G, KC_H, KC_J, KC_K, KC_L, KC_SCLN, KC_QUOT, KC_NUHS, KC_ENT, \ @@ -149,7 +149,7 @@ Some interesting things to note about this: Our function layer is, from a code point of view, no different from the base layer. Conceptually, however, you will build that layer as an overlay, not a replacement. For many people this distinction does not matter, but as you build more complicated layering setups it matters more and more. - [_FL] = KEYMAP( + [_FL] = LAYOUT( KC_GRV, 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_DEL, BL_STEP, \ _______, _______, _______,_______,_______,_______,_______,_______,KC_PSCR,KC_SLCK, KC_PAUS, _______, _______, _______, _______, \ _______, _______, MO(_CL),_______,_______,_______,_______,_______,_______,_______, _______, _______, _______, _______, \ diff --git a/docs/porting_your_keyboard_to_qmk_(arm_and_other_chibios_cpus).md b/docs/porting_your_keyboard_to_qmk_(arm_and_other_chibios_cpus).md index 50d291a230..c32c428cf0 100644 --- a/docs/porting_your_keyboard_to_qmk_(arm_and_other_chibios_cpus).md +++ b/docs/porting_your_keyboard_to_qmk_(arm_and_other_chibios_cpus).md @@ -54,10 +54,10 @@ This is where all of the custom logic for your keyboard goes - you may not need ## `/keyboards//.h` -Here is where you can (optionally) define your `KEYMAP` function to remap your matrix into a more readable format. With ortholinear boards, this isn't always necessary, but it can help to accommodate the dead spots on your matrix, where there are keys that take up more than one space (2u, staggering, 6.25u, etc). The example shows the difference between the physical keys, and the matrix design: +Here is where you can (optionally) define your `LAYOUT` function to remap your matrix into a more readable format. With ortholinear boards, this isn't always necessary, but it can help to accommodate the dead spots on your matrix, where there are keys that take up more than one space (2u, staggering, 6.25u, etc). The example shows the difference between the physical keys, and the matrix design: ``` -#define KEYMAP( \ +#define LAYOUT( \ k00, k01, k02, \ k10, k11 \ ) \ diff --git a/docs/understanding_qmk.md b/docs/understanding_qmk.md index 20ead2b3f5..bf4b5eadcd 100644 --- a/docs/understanding_qmk.md +++ b/docs/understanding_qmk.md @@ -57,10 +57,10 @@ Matrix Scanning runs many times per second. The exact rate varies but typically 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: +At the keyboard level we define a C macro (typically named `LAYOUT()`) 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 `LAYOUT()` macro for a numpad: ```c -#define KEYMAP( \ +#define LAYOUT( \ k00, k01, k02, k03, \ k10, k11, k12, k13, \ k20, k21, k22, \ @@ -75,17 +75,17 @@ At the keyboard level we define a C macro (typically named `KEYMAP()`) which map } ``` -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. +Notice how the second block of our `LAYOUT()` 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/e1203a222bb12ab9733916164a000ef3ac48da93/keyboards/clueboard/66/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: +At the keymap level we make use of our `LAYOUT()` 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( +[0] = LAYOUT( KC_NLCK, KC_PSLS, KC_PAST, KC_PMNS, \ KC_P7, KC_P8, KC_P9, KC_PPLS, \ KC_P4, KC_P5, KC_P6, \ @@ -94,7 +94,7 @@ const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = { } ``` -Notice how all of these arguments match up with the first half of the `KEYMAP()` macro from the last section? This is how we take a keycode and map it to our Matrix Scan from earlier. +Notice how all of these arguments match up with the first half of the `LAYOUT()` macro from the last section? This is how we take a keycode and map it to our Matrix Scan from earlier. ##### State Change Detection