summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorAndrew C <47721334+polarbearhoodie@users.noreply.github.com>2025-11-03 23:06:56 -0800
committerGitHub <noreply@github.com>2025-11-04 15:06:56 +0800
commita1096e1dec7abae4c3cb957c992b7ac47877fe83 (patch)
tree796d651f64cda38b002fc63e09ea2dc79e3ddae4
parenta9739f78681dee290ede955c02b360f5c133f783 (diff)
Deprecate LAYOUT() macro in favor of JSON matrix definitions
* Indicate <keyboard>.h LAYOUT() deprecation in understanding_qmk.md Initial documentation uses <keyboard>.json to define matrix pin definitions, rather than having users #define the LAYOUT() macro in <keyboard>.h - This change brings this docs inline with the [porting_guidelines](https://docs.qmk.fm/porting_your_keyboard_to_qmk), QMK MSYS will also throw an error if this is attempted. * Update understanding_qmk.md enclosed '<' using backtick * style guideline, now builds correctly prior version indicates directory, new indicates config. still the same idea.
-rw-r--r--docs/understanding_qmk.md4
1 files changed, 2 insertions, 2 deletions
diff --git a/docs/understanding_qmk.md b/docs/understanding_qmk.md
index ad5afdc56a..a47617c418 100644
--- a/docs/understanding_qmk.md
+++ b/docs/understanding_qmk.md
@@ -51,7 +51,7 @@ Matrix Scanning runs many times per second. The exact rate varies but typically
51 51
52Once 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. 52Once 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.
53 53
54At 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: 54At the keyboard level, QMK will generate a macro (typically named `LAYOUT()`) from our configuration file `info.json`, which then maps our keyboard's matrix to physical keys. Sometimes the matrix does not have a switch in every location, and QMK will 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:
55 55
56```c 56```c
57#define LAYOUT( \ 57#define LAYOUT( \
@@ -71,7 +71,7 @@ At the keyboard level we define a C macro (typically named `LAYOUT()`) which map
71 71
72Notice 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. 72Notice 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.
73 73
74You can also use this macro to handle unusual matrix layouts, for example the [Alice](https://github.com/qmk/qmk_firmware/blob/325da02e57fe7374e77b82cb00360ba45167e25c/keyboards/sneakbox/aliceclone/aliceclone.h#L24). Explaining that is outside the scope of this document. 74This macro can handle unusual matrix layouts, for example the [Alice](https://github.com/qmk/qmk_firmware/blob/325da02e57fe7374e77b82cb00360ba45167e25c/keyboards/sneakbox/aliceclone/aliceclone.h#L24). Explaining that is outside the scope of this document.
75 75
76##### Keycode Assignment 76##### Keycode Assignment
77 77