keychron_qmk_firmware/users/ericgebhart/readme.md

Overview
========

This is as much a keymap framework as it is a keymap. It can take many
shapes with just a few configuration choices. Base layers, Mods, thumb clusters, 
edge_keys, all can be changed with just a configuration option.
There are over 50 base layouts to choose from, as well as multiple 
choices of navigation, mouse, media, 
symbols, and keypads. Home row mods come in a few flavors or none,
in a mod layer which is easily understandable and can be turned on
or off, or switched. There are Miryoku options for everything if
that is your thing.

If there is a oled of 64x128 the maps of each layer will be displayed, which
helps a lot in remembering and learning.

This is an easily configurable keymap for keymap exploration. It is for
primarily for minimalist, ortho split keyboards but does support some rectangles.
It´s first keyboard was an Ergodox-ez many years ago. My daily driver
is now a Kyria or a Corne, but I still use an original dactyl, rebound 
and ergodox-ez regularly although most of the love goes to the Kyria and Corne.

The framework is Language
agnostic, it supports having layers for different locales which can be
cycled through.
There are multiple mods layers to choose or
not, home row mods or not, a variety of thumb layouts, mouse/no mouse,
smart lock layers and mods, N-Shot mods like callum's, swapper. Combos,
tap_hold, accented keys, alternate shifted keys, automatic custom
keys, key overrides. Minimal or no C-code required for most things. 
Language, mods, layouts and extensions are encapsulated, so that they 
do not interact in the configuration which makes it much easier to modify 
and grow. Mods and combos are by key location rather than specific key codes.

Quick start
-------------

Everything is encapsulated here. Base layers, functional layers, mods,
or no mods, even the language. This means that anything can change 
independently and easily.

If you don't mind dvorak, beakl or hands down, you can probably 
just use what is configured. Or just change it to a base layer
of your choice. The fastest way to get started is to just change
the base layers to the ones you want, compile and flash. 

Edit _config.h_,
  * Set the lang_is, probably to EN.
    * US international and BEPO are also supported out of the box.
  * Uncomment the base layers you wish to have.
    * comment the ones you don't.
    * keep the number below 5 if you enable a second locale.
  * Set the thumb clusters
  * Choose a mod layer
  * Choose an edge key set if you need one.
  * Choose the layer flavors that you want.
  * For Miryoku, copy the `miryoku_hd_gold_config.h` over `config.h`
    It is a complete config with miryoku choices. Choose the base
    layers you wish if Hands Down Gold and Qwerty is not your thing.
  
  ** do not turn off extensions until you know them **
  It will likely cause a stream of errors for the keycodes that
  go missing when something is turned off. There are known
  interactions between combos, smart locks, not_dead, and alt local keys.
  Turning encoders or oled on and off certainly won´t break
  anything.
  
  There are other interactions between your choices.
  Edge keys, thumbs, combos, other extensions, 
  may use the extensions that are enabled.
  
### Look here to see the parts
  * Everything can be turned on and off in *config.h*
  * Base layers are in *base_layers/*
  * Edge keys are in *layers/edge_keys.h*
  * Thumbs can be reviewed in *layers/thumbs.h*
  * Mods are in *mod_layers/*
  * All other layers are also in *layers/*


The long version
-----------------

All can be turned on or off in the config. 
supports en-us and fr-bepo Support for other languages is easily added.

Layouts are human readable, all extensions are defined with def files.
If an 128x64 oled is available, a map of the current layer is shown if enabled.

I'm an Xmonad, emacs in vi emulation programmer, that 
just means that _Gui, Esc, :/?!% and ._ are all easy access and I like my
arrow and mouse keys in a 4 column row.

I have also become minimalist in my keyboard choices. I don't use
number rows, not even on my kinesis, dactyl, or ergodox_ez, which have them. 
Although my maps do reasonably support these bigger keyboards as that is where
it all started for me and I do still use them. My preference for keyboards 
is more in line with the Kyria and Corne. I still use 6 columns, but have been
looking to use only 5.

Note: Combos at QMK master do not currently support multiple reference layers which this
configuration uses. Combos still work as always, but do not support all the features
found here. To get fully functioning multi-reference combos, see my *ericgebhart_dev*
branch and pull request below.

Actually, at the moment, the fix is in my ericgebhart branch, since I accidently
pushed it.  I'll remedy that soon.

A more current version of my QMK user can be found here in
A sparse tree [of my QMK User Space ](https://github.com/EricGebhart/MyQMK/users/ericgebhart)

For full multi-lingual combo functionality you will need my [pull request for fully functioning multi-reference combos which can found here.](https://github.com/qmk/qmk_firmware/pull/16699)

Things which effect the thinking.
  * No mouse. 
  * Preference for 3x10 layouts. Corne, Kyria, etc.
  * Still works with bigger keyboards like xd75, kinesis, dactyl, ergodox, viterbi.
  * Change mods without changing any maps.
  * No number row preference. - all layouts have them if needed.
  * Xmonad window manager, GUI key is the entrance to the Xmonad world.
  * Typing in other languages.
  * Curious about keyboard layouts and experimenting.
  * Must be easy to maintain, extend and modify.
  * Minimize digging in code to add new things, or change old ones.
  * Minimize process record user.
  * Easy to add enums for keys and layers, as well as oled display.
  * Easy to support multiple languages regardless of maps.
  * Minimize the need to write C code.
  * Encapsulate C code, so that it is extensible through data.


Features:
  * Everything is configurable from config.h and .def files.
  * Def files for most things.
  * Custom key codes are mostly defined automatically.
  * Everything is chosen or turned on and off in config.h
  * Lots of macros to make it easy to redefine things without a refactor.
  * Multiple edge/outer pinky column sets.
  * Multiple thumb clusters to choose from.
  * Thumb clusters and mods can be changed on a map by map basis.
  * Easily define thumb clusters with an alpha letter.
  * Easily define thumb clusters for non-base layer.
  * Multiple base layers to choose from.
  * Several variations of function layers to choose from
  * Miryoku layers, thumbs and mods if desired
  * Miryoku hands down gold config can be swapped with config.h
  * Navigation and mouse layers
  * A selection of symbol, keypads, and other layers.
  * Regular and Beakl keypad and number rows
  * Multi language support, (locales in the code).
  * Multiple mod layers to choose from. Easy to add more.
    * home row mods - a selection 
    * no mods
    * alt mods 
    * miryoku mods
  * Extensions are easily defined in def files.
    * N-shot mods
    * One-shot mods
    * swapper
    * Smart lock mods 
    * Smart lock layers.
    * Accent keys
    * Alternate shift keys
    * Alternate local keys
    * key overrides
    * Tap hold
    * Not dead keys
    * Send unicode
    * Send string
    * Encoders
  * Display a map of the current layer on the oled.
  * Adding a new layer is painless.
  * Adding or changing most things, is not difficult.
  * Console key logging for [heatmap analysis.](https://precondition.github.io/qmk-heatmap)
  
  
Layout shape and keyboard choices.
-------------------------------------

   In all cases these keyboards are defined in a matrix which is
   a set of rows. Maybe like so, or less. Kinesis has one more row.
                                                       
``` 
   -------------------------|------------------------ */
   | Left0 | Numbers L | mid|dle0 | numbers R | Right0 |
   | Left1 | keys0-5   | mid|dle1 | Keys6-10  | Right1 |
   | Left2 | keys11-15 | mid|dle2 | Keys16-20 | Right2 |
   | Left3 | keys20-25 | mid|dle3 | Keys25-30 | Right3 |
   | Row5L                  |                    Row5R |
   |               ThumbsL  | ThumbsR                  |
   -------------------------|------------------------ 
```

Generally speaking, the keys on the right and left and middle don't change.
Neither do the bottom row or the thumbs, unless asked. Frequently the numbers 
row is identical across layers. 

For automatic edge columns set EDGE_COLS. 
Outside pinky keys are 'yes'.  This is on by default.
N rows by 6 columns per side.
Should be undef/def'd by the keyboard's keymap if no.
#define EDGE_COLS yes. this is all taken care of for supported keyboards.

Thumbs and Edge keys are grouped into sets so that different sets can be chosen in
the config. 

All layer macros take 3x10 or 3x12 as needed. Edge columns are
added as needed, and middle keys fill up the gap.
Thumb keys are added as asked.

keyboard shapes: 
Matrix size + 5th row + thumbs.
Matrix size + thumbs.

 * kinesis
   4x6 + 4 + 6 - 18 func keys.
 * dactyl - Morpho handwire
   4x6 + 5 + 6
 * ergodox_ez
   4x6 + 5 + 6 & 3 pairs of center keys.
 * crkbd - corne
   3x6 + 3 or 3x5 + 3
 * xiudi/xd75
   5x15
 * keebio/viterbi
   5x14
 * montsinger/rebound/rev4
   4x12 + 3 center keys.
 * -- 4x12
 * splitkb/kyria
   3x6 + 7 or 3x5 + 7
 
The parts of a keymap
---------------------

  * keymap
    * defined in _keymap/keymap.c_. 
    * Completely configurable from config.h
    * Separated into logical chunks.
    * Uses a language setting to create all maps.
    * Creates the same maps in multiple languages.
    * More than one language simultaneously on one keyboard.
    * Currently provides these languag settings and keycodes. 
      * US - US-intl (US_)
      * EN - US-en (KC_), 
      * BEPO - fr-bepo (BP_).
    * Choosing dvorak, and enabling bepo as the second locale, 
    will produce two base layers to choose from on the keyboard. 
    Dvorak on US and BEPO.
   
 * Base layers
   * Simple and compact definitions.
   * Base layers are pure.
   * Mods are defined separately.
   * OLED Maps for 128x64 sized oleds.
   * Language agnostic.
   * Core layer chunks are 3x10.
     * Except for few exceptions which are 3x12
   * More than 50 base layers to choose from.
   
   **Caution: Choosing too many base layers will result in toprows or keypad layer LT's 
   to stop working. If bepo is enabled, all base layers are doubled so it's
   easy to hit the 16 layer limit for LT.**

 * Locales
    * Locales, defines a set of layers for a locale.
    * Layer definitions are language agnostic. - see lang.h.

 * Extensions - Defs.
    * Can be selected in config.h
    * Defined in easy to read .def files.
    * Correspondance between *extensions/* and *defs/*

    * accented_keys.def - direct access to altgr keys
    * altlocal_keys.def - alternate un/shifted pairs.
    * alt_shift.def - alternate shifting behaviors for existing keycodes.
    * not_dead.def - definitions for non-dead dead keys.
    * caps_word - no def file.
    * combos.def - 
    * custom_keys.def  - list of custom keys.
    * encoders.def - encoder behaviors by mod/layer.
    * key_overrides.def - Bigger more complex alt keys.
    * mod_lock.def - smart locking mods with a set of ignore keys.
    * nshot.def - N-shot locking mods
    * oneshot.def - One-shot locking mods
    * smart_lock.def - Smart lock layers and mods.
    * swapper.def - key substitution, reverser.
      * eg. toggle between tab, backtab on a key, with a reverse key.
    * tap_hold.def - Define key for tap and hold for tapping term for qqc autre.
    * unicode.def - keycodes to send unicode strings.
    * send_string.def - keycodes to send strings.


 * Layers 
    * Multiple selections of the Transient layers.
    * Layer chunks are 3x10, with some options.
    * Full Navigation layer - stable and well used.
    * Mouse keys or without.
    * 1 or 2 layer nav, 2nd for mouse. or all on one. - choices.
    * Multiple choices of an easy to use _top rows_ layer similar 
      to `raise` and `lower`. 
    * A fully complete symbol layer, Used for coding and writing.
    * Accented letters and dead key layers.
    * Keypads and function pads.
    * Beakl keypads and symbol layers.
    * Control layers.
        * Layers
        * Adjust
        * RGB
   
 * OLED A simple, configurable implementation.
   * Current base layer
   * Current locale
   * Current transient layer
   * Last key, matrix location and value.
   * Mods and locks
   * Map of the current layer. (Oled 128x64)
   * key logger

 * Keyboards
    * nothing is needed in keymaps/*/keymap.c
    * Layouts - keyboard matrix adaptation.
        * Adaptive. Usually taking 3x10 maps and filling the edges and thumbs.
        * 4x10 or whatever is possible. 
        * 3 versions, thinking in a split kb, way.
            * 5 columns in, 5 out. 
            * 5 columns in, 6 out. 
            * 6 columns in, 6 out. 
   * per keyboard shape.
   * There are layouts per keyboard.
     * Base layout with mods and thumbs and edges added.
     * Transient layout which can be KC_TRANS, in those same places.
   * The number row addition can be turned on and off as needed by the layout.
   * Layouts can hard code the number row, negating the need for giving one.
     
 * Multiple edge key sets
 
 * Multiple Thumb clusters - see config or thumbs.h for up to date choices.
   * Support for multiple definitions. 
     * mods
     * layers
     * mods_layers
     * mods_layers_nav
     * beakl wi
     * beakl wi - official.
     * test  - to play with.
     * trans - transparent, could be used in the transient layout to allow alternates.
     * miryoku with keypad
     * miryoku with toprows
     * mods_layers with left thumb letter
     * hands down approximation with left thumb letter
     * miryoku with keypad, letter on left, space on right. - no tab.
     * miryoku with toprows, letter on left, space on right. - no tab.
     
 * Mod Layers
   * Completely independent of any layer or base layer definition.
   * Easy to create a new one by copying the transparent version.
   * Can be changed on a layer per layer basis.
   * Based on position in the matrix.
   * Chosen in config.
   * Multiple choices.
     * Home Row Mods. sacg, gacs, gasc
       Left and right mods on left and right.
     * Transparent - the default if not chosen.
     * Alt - Non home row mod variant.
     * miryoku HRMS is sacg plus right alt/altgr on third row.

 * Alternate language/locale support
   * Happens at the lowest level
   * All maps work with any of the [keymap extras.](https://docs.qmk.fm/#/reference_keymap_extras)
   * Language support is simple to add with just a new, very simple macro.
   
The language keycodes can be found 
[here.](https://github.com/qmk/qmk_firmware/tree/master/quantum/keymap_extras)


Architecture
-----------------
The idea here is that most things don't change, and the things that do are
easy to understand and change. The defs directory is where all the extras are,
tap_hold, alternate shift keys, combos, keycodes, smart lock, one shot mods,etc.

If layers exist that you want and like, then all other behaviors are defined in
def files which are much nicer than working directly with C code. If there is
need there is always the copy pasta way too.

Things that are likely to be changed when adapting a layout to personal preferences
are *layers/thumbs.h* and *mod_layers/*.  The function layers are all in the
layers folder and should be easy to understand. Once added, it is only necessary to
add the appropriate defines in _config.h_

Adding new layers requires changes in layer_names, *oled/oled_layers.h* and *oled/oled_cartes.h* and the appropriate *keymap/ .h* file.

Adding a new keyboard is done in keyboards and should be fairly obvious.
```
.
├── base_layers
│   ├── accents.h
│   ├── alt.h
│   ├── base_layers.h
│   ├── beakl.h
│   ├── bepo.h
│   ├── carpalx.h
│   ├── dvorak.h
│   ├── gap.h
│   ├── hands_down.h
│   ├── keymaps.txt
│   ├── maks.h
│   ├── qwerty.h
│   └── toprows.h
├── config.h
├── defs
│   ├── accented_keys.def
│   ├── altlocal_keys.def
│   ├── alt_shift.def
│   ├── combos.def
│   ├── custom_keys.def
│   ├── encoders.def
│   ├── key_overrides.def
│   ├── mod_lock.def
│   ├── not_dead.def
│   ├── nshot.def
│   ├── oneshot.def
│   ├── send_string.def
│   ├── smart_lock.def
│   ├── swapper.def
│   ├── tap_hold.def
│   └── unicode.def
├── ericgebhart.c
├── ericgebhart.h
├── extensions
│   ├── accented_keys.c
│   ├── accented_keys.h
│   ├── altlocal_keys.c
│   ├── altlocal_keys.h
│   ├── alt_shift.c
│   ├── caps_word.c
│   ├── caps_word.h
│   ├── console_key_logger.c
│   ├── console_key_logger.h
│   ├── encoders.c
│   ├── encoders.h
│   ├── extensions.h
│   ├── keycodes.h
│   ├── keymap_combo.h
│   ├── key_overrides.h
│   ├── mod_lock.c
│   ├── mod_lock.h
│   ├── not_dead.c
│   ├── nshot_mod.c
│   ├── nshot_mod.h
│   ├── oneshot.c
│   ├── oneshot.h
│   ├── process_locales.h
│   ├── process_nshot.h
│   ├── process_smart_lock.h
│   ├── send_string.c
│   ├── smart_lock.c
│   ├── smart_lock.h
│   ├── swapper.c
│   ├── swapper.h
│   ├── tap_dances.c
│   ├── tap_dances.h
│   ├── tap_hold.c
│   ├── tap_hold.h
│   ├── unicode.c
│   └── unicode.h
├── keyboards
│   ├── keyboards.h
│   └── layouts.h
├── keymap
│   ├── keymap.c
│   ├── map_accented.h
│   ├── map_alt.h
│   ├── map_beakl.h
│   ├── map_bepo.h
│   ├── map_carpalx.h
│   ├── map_dvorak.h
│   ├── map_funcs.h
│   ├── map_gap.h
│   ├── map_hd.h
│   ├── map_keypads.h
│   ├── map_maks.h
│   ├── map_qwerty.h
│   ├── map_symbols.h
│   └── map_toprows.h
├── lang
│   ├── lang.h
│   ├── lang_map.h
│   ├── locale_layers.h
│   ├── locales.c
│   └── locales.h
├── layer_names
│   ├── base_names.h
│   ├── func_names.h
│   ├── layer_names.h
│   └── util_names.h
├── layers
│   ├── edge_keys.h
│   ├── keypads.h
│   ├── layers.h
│   ├── nav.h
│   ├── symbols.h
│   ├── thumbs.h
│   ├── toprows.h
│   └── utility.h
├── listen_keylogger.sh
├── mod_layers
│   ├── alt_mods.h
│   ├── hrm_gacs.h
│   ├── hrm_gacs_miryoku.h
│   ├── hrm_gasc.h
│   ├── hrm_sacg.h
│   ├── hrs_nav.h
│   ├── mod_layer.h
│   └── trns_mods.h
├── oled
│   ├── oled_cartes.c
│   ├── oled_layers.c
│   ├── oled_stuff.c
│   └── oled_stuff.h
├── process_records.c
├── readme.md
└── rules.mk

10 directories, 118 files
```

Locales
-------------------
There are currently three locales.  LANG_IS defines the one in use.
The map changes this value as it goes, to get the maps that are asked for.
I have recently renamed some variables, such that it seems that only 2 locales
are possible. It seems more than two might be too many. And keeping at 2 is
a little easier.

 * EN - en-us, **KC_** keycodes.
 * US-INT - us-international variant, **US_** keycodes.
 * BEPO - bepo-fr, **BP_** keycodes.

Switching LANG_IS before adding a new map will cause that map to 
use LANG keycodes and keymap chunks when building the map.

Enabling a second locale to bepo, will cause bepo versions of the chosen layers to
be added to the keymap.

### defining a locale.

This is to manage BEPO and Qwerty Locale/language/Layers
Each locale is defined with a start and end layer from the layers enum.

This is only necessary to give contextual base layer choices based on
the current locale setting, which the keyboard tracks.

The first and last defines are all done with the magic of defines in 
ericgebhart.h where the layers enum is defined.

This could potentially hold multiple locales, The map turns on off the layers 
and their enums if they are not enabled so that the layer array does not 
fill up with too many base layers, or other layers because LT only works 
up to layer 15.

What this does is allow the keyboard to know which locales it has, and which
layers go with them.

If you have an oled, the locale will be displayed after the layout name. Currently
en-us and bepo-fr are there.

Locales are tracked, as to the layer ranges which belong to them in the layers enum.
This allows for a `KC_NEXT_LOCALE` key and a `KC_NEXT_BASE_LAYER` key, on the _layers_
layer. 
`KC_SET_BASE` sets the default layer in the eeprom.

When cycling through layers only the layers for the chosen local will appear.

The layers are different keycode sets. 
So there are two symbol layers, two toprows layers, two keypad layers. 
One for Qwerty and one for bepo. The Navigation layer is not affected because
it has only control keycodes which are independent of locale. 


### Locales, how they work in layouts.

This is done through consistent naming patterns and macros.
Here are the macros that support creation of layout parts by locale.
All are defined in **lang.h**

 * Keycode Prefix - KC or BP, etc. 
    `LANG_KC(_A) -> KC_A or BP_A`

 * Defined key/layer Suffix - SYMB_EN, SYMB_BP, ... 
    `LANG_N(NAME) -> NAME_EN, NAME_BP`
 
 * Map chunk Suffix - _EN, SYMB_BP, etc.
    `MAP_CHUNK(15_BOTTOM) --> ___15_BOTTOM_EN___ or ___15_BOTTOM_BP___`

_lang.h_ has the macro definitions used in the keymap resolution,
A new locale, will need a new set of macros that match the others.
They use LANG_IS, Follow the patterns. It should be reasonably obvious.

It is only necessary to create new base level macros that are used by these
macros.  All of them are similar.

**LANG_KC** uses these macros to resolve it's values.
```
    // Give the right keycode prefix by LANG_IS
    #define LANG_PFX CAT(LANG_IS_, KC)
    #define BEPO_KC BP_
    #define EN_KC KC_
```

Adding a new one is just a matter of adding the a macro named with
this format. `LANG_IS _Keycode prefix`.
for Slovak, if the **LANG_IS** value is `SK` that would be,

    `#define SK_KC SK_`

LANG_N macro uses these similar macros for it's resolution.

```
    // Give the right symbol suffix by LANG_IS
    #define LANG_SFX CAT(CAT(LANG_IS, _), SFX)
    #define BEPO_SFX _BP
    #define EN_SFX _EN
```
Adding Slovak support to the LANG_N macro looks like this.

    `#define SK_SFX _SK`


### Thumb clusters.

Thumb clusters can be chosen by layer with the value of **THUMBS_ARE**.

The easiest way to see them is to look in *layers/thumbs.h*.

At the core of the thumb clusters are a set of six keys which
can be changed to a one of a set of keys, with settings in the config. 
Supporting a 4 key thumb cluster would just need a similar set.

The newer Hands down variants also have need of thumb clusters which
can take a letter.  A default can be given in config.h.
Each keymap layer entry can give it's letter to change the thumb cluster.
This is needed for hands down, maltron, rsthd, and beakl wi.

These layouts use a special thumb cluster variant which will use the value
of *THUMB_LETTER* to place a letter on one of the thumb keys.

It is reasonably easy to add a new thumb cluster and use it. Add it to
thumbs.h, add to the list of macros for it's suffix, and turn it on 
by setting it to *THUMBS_ARE* in config.h

Additionally a thumb cluster can be set for the various function layers as
well. The transparent thumbs can be used, or something else. The nav and 
mouse layers have the mouse buttons if mouse keys are enabled.

It is also possible to use a Miryoku thumb cluster and layers 
or mix the other layers in as desired.

The language of thumb clusters is managed at the lowest level.
These keys are mostly not language specific.

Here is the definition for my space and symbol layer key. 
This changes the name of the layer given like this.

_SYMB becomes *_SYMB_EN* or *_SYMB_BP*. Depending on the value of *LANG_IS*

    `#define SPC_SYMB LT(LANG_N(_SYMB), KC_SPC)`


Edge key sets
----------------
Edge keys, or the 6th, and outer pinky column are often not specified
in base keymaps and are not strictly necessary. There are a few sets
to choose from here. A NOKC set with no keys, NORM which is sorta normal
with grave, equal, tab, -, and \/. There is also a smart lock set
which gives access to smart lock layers tab and -. Last there is 
test, so its easy to try new things. Edge keys are defined in
*layers/edge_keys.h*.


Base Layers
-----------------
I like to experiment with layouts. So I have a few. 
They can be turned on in config.h.

To switch base layers there is a combo to raise the layers layer.
Hold both pinkies on their lower row keys to get the layer.
Tap the home row left middle finger to change layers.
Tap the ring finger to set it to eeprom if you want it to stick.

The left index finger will cycle through locales if you have them.

Here is a list of some of the base layers..

 * Dvorakish
    * Dvorak
    * Capewell-Dvorak
    * Ahei
    * Boo
    * Dvorak RLC-UI
 * Beakl
    * 15
    * 19
    * 27
    * WI
 * Qwertyish
    * Qwerty
    * Azerty
    * Workman
    * Norman
 * Maks
    * Colemak
    * Colemak_DH
    * Halmak
    * Minimak
    * Minimak 8
    * Minimak 12
 * Carpalx 
    * QFMLWY
    * QGMLWB
    * QGMLWY
 * Hands Down
    * Neu
    * Neu narrow
    * Titanium
    * Gold
    * Platinum
    * Silver
    * Bronze
    * Elan
    * Dash
    * Ref
 * MTGAP
    * Mtgap
    * Ctgap
    * Apt
    * Canary
 * Others
    * Maltron
    * Eucalyn
    * Rsthd
    * Isrt
    * Hands Up
    * White
    * Soul
    * Niro
    * Asset
    * Whorf
    * Whorf6
 * Bepo, layers with accented letters.
    * Bepo
    * Optimot
    * Optimot compact
    * Beakl19bis

### Adding a new base layer, or any layer 

Adding a new base layer is easy. They all live in *base_layers/*. A base layer
entry looks like this. There is an empty template in *base_layers.h* which collects
all the other maps. The name of the carte  de map, should be **CARTE** followed by
the layer name that will be used. Layer names are usually an underscore followed by
the name.  For dvorak, that is *_DVORAK*, which because of the language layer ultimately
and magically becomes *_DVORAK_EN*, *_DVORAK_US*, *_DVORAK_BP* as needed. 

```
#define CARTE_DVORAK                            \
  carte_de_map(" ',.py fgcrl ",                 \
               " aoeui dhtns ",                 \
               " ;qjkx bmwvz ")

#define ___DVORAK___                                                    \
  LANG_MAP(TL_QUOT,  TL_COMM, TL_DOT, _P,  _Y,   _F, _G, _C, _R, _L,               \
           _A,       _O,      _E,     _U,  _I,   _D, _H, _T, _N, _S,    \
           TL_SCLN,  _Q,      _J,     _K,  _X,   _B, _M, _W, _V, _Z)
```

#### TL_ keycodes 

Use TL_ keycodes for any punctuation, this allows for targeting
of these keys by language and by target layout as needed.
for instance *TL_COMM* -> TLKC(_COMM). The *Target-Language-comma*, 
becomes BP_BK_COMM, or KC_DV_COMM, US_HD_COMM, or whatever it
needs to be based on current language and target layout. If your layer has special
puncuation needs, 

  * Add key entries to *altlocal_keys.def* 
  * Edit to *lang/lang_map.h* to add the new *TARGET_PFX* entry.
  * Set the appropriate value to *ALT_TARGET_IS* in the layer's keymap entry.

#### Integration

Integrating the new map into the rest of the framework is just a simple entry
in a few places. 
  * *layer_names* needs to know about the new name so we can use it, 
  * The oled needs to know about it so it can display it.
  * The config needs to know about it so we can turn it on.

Follow these steps. Everything is very simple, and just one to 3 lines. 
Just follow the same patterns as all the rest. 

  * Add the layer definition and map of the definition in *base_layers/<appropiate>.h*.
  * Add the layer name to *layer_names/base_names.h*
  * Add the layer name to *keymap/<appropiate>.h*
  * Add the layer entry to *oled/oled_layers.c*
  * Add the layer map entry to *oled/oled_cartes.c*
  * Add the define for the layer enable to *config.h*

Adding a new functional layer follows the same patterns, although their
keymap and oled entries may be more complex, since it is usually trying
to pick one from a set of choices.

### Adding a new thumb cluster configuration

Adding a new thumb keys definition is done in *layers/thumbs.h*.
The keys that change are just 6 and they all have the name of *___6_ERGO_THUMBS_...*.

  * Define a new thumb definition with a nice suffix like all the rest.
  * Add an entry to the *THUMB_EXT* list with the nice new suffix.
  * Set the appropriate *THUMBS_ARE* defines in config.h to it's 
  new thumb extension name.
  
### Adding a new mod layer

This is also easy. Mod layers live in the mod_layers folder. Each file
there is a separate mod layer, which is tracked in *mod_layers.h*
The file, *trns_mods.h* is the transparent mods layer and by definition has
no modifiers applied, providing a clean slate. 

The steps are these:
  * Make a new copy of an existing mod layer.
  * Edit the new file and change the names to your new name.
      * ie. *_trns* changes to *_my_new_mods*
  * Add the mods you want. MT's and LT's, tap holds, etc. 
  * Edit  *mod_layers/mod_layer.h*
    * Add the include for the new mods file*
    * Add the *MOD_EXT* entry for the new name
  * Define *MODS_ARE* in _config.h_ to use the new name.


Keymaps
-----------
I only have one. It's in keymap/keymap.c.  
My config.h has all the current usable settings.
Turn on the layers by enabling and choosing them in config.h. 
Most keyboards don't need a keymap.c. 

There are corresponding Bepo layers, as needed, which will arrive if *SECOND_LOCALE* is
set to _BEPO_.
This essentially doubles the number of keymaps.  
Nav, mouse, media, layers, RGB, and Adjust are not duplicated as there is no 
current need.

## Mods, home row and otherwise.
With all these layers it was a real pain to apply mods consistently and 
easily with the old wrapper code. So I changed the way I use keymap macro 
wrappers and added in my own mod layer. The only thing it has is the mods 
to apply. No more editing keymaps to apply mods.  I do it once, and it 
works everywhere I want by location.

Multiple versions are possible. Just copy the trns_mod_layer.h to a new
name and modify it with a new extension name, (replace '_trns'). Then add it's include to mod_layer.h, to be used when the config says.

The defines for *MODS_ARE* and *DEFAULT_MODS* determine which mods are applied
to a given keymap layer. 

Keyboard matrix Layouts
-----------
This is where the keymap of the
keyboard meets the mods and all the edge, middle and thumb keys, and makes 
it easy to give just a 3x10 definition for most layers regardless of which 
keyboard it is going to.

To use an existing layout for a different keyboard, simply make an entry
in *keyboards.h* to assign the proper layouts that fit that keyboard.
So a planck could use the 4x12 layout out of the box. In the keyboards 
keymap there is only a need for config.h or rules.mk if something needs
changing. For the keyboard an empty keymap.c will do.

The base layout can be anything really.
The base layer sets the thumbs and anything outside of the 3x10.
The mod layer is wrapped in the base layout and adds the mods, and a 6th 
outer pinky column as needed.

Some layouts take an extra number row.
Layouts can be any shape, all of these take a 3x10, 3x12, 4x10 or 4x12, 
and make it fit the keyboard.

The layouts defined in _layouts.h_ take a list of keys. and give them
to the keyboard's layout.  The Corne (crkbd), uses a layout called
  `LAYOUT_split_3x6_3`. So for the corne, I have a `Base_3x6_6` that
  is the same shape, in its resolution.
  
There are layouts for Corne, ergodox, kinesis, dactyl, viterbi, xd75, rebound.

Currently, 3 layouts are needed per keyboard. 
 * A Base layout, for default/base layers, 
 * A transient layout for the function layers.
 * A version which takes 3x12 for the larger bepo base layers.

The base layouts can take 3 or 4 rows by 10 columns as desired.
They add in the mods, and any pieces of matrix outside of
the 3x10 center, function, numbers, lower rows, outside pinky keys,
and thumb clusters. 


Functional layers
--------------------
There are quite a few of these to choose from. The easiest way to see
them all is to go look at them in _layers/_. They are logically divided
into files, and their cartes/maps are easy to look at. There are 
minimalist Miryoku versions as needed.

## Navigation Layer
I do not use a mouse. I use Xmonad as my window manager, and I have
practically no use for one.  They are necessary however. So I have
a Navigation layer which is all mouse, arrows, home, end, tab, page
up, down,  5 mouse buttons and so on. 

There are a growing number of choices, left and right sided mouse layers
right side arrows etc, and some monolithic nav layers like the one shown
below.

There is also a split layer, with arrows etc on the right, and smart mods
and N-shots on the other. A left side mouse layer is accessible from
the first nav layer.  There are various choices at this point. It is
best to look at the config.h for clues. 

The miryoku nav and mouse layers are somewhat but not terribly different.


#### One of the Navigation layers.
                                                       
```
M = Mouse
B = Button
W = Wheel
AC   = Acceleration
CCCV = Tap -> Ctrl-C, hold for double tap duration -> Ctrl-V
CTCN = Tap -> Ctrl-T, hold for double tap duration -> Ctrl-N
CWCQ = Tap -> Ctrl-W, hold for double tap duration -> Ctrl-Q
HOME = TAB & PGDN
END = BKTAB & PGUP
Lock/Unlock LAYER = PGDN & PGUP
 
MB5  MB4    MB3    MB2  MB1     MAC0  |  CTCN  MB1    MB2    MB3  MB4   MB5 
TAB  MLeft  MDown  MUp  MRight  MAC1  |  CCCV  Left   Down   UP   Right TAB 
     WLeft  WDown  WUp  WRight  MAC2  |  CWCQ  TAB    PGDN   PGUP BKTAB
                                                                             
     Left   Down   Up   Right   CCCV  |  CCCV  MLeft  MDown  MUp  MRight
     
     
```
                                                                            

## Symbol Layer

The symbol layer is based on the Beakl15 symbol layer. It was very similar to a symbol
layer that I had before beakl, but this felt better, and has been through a few 
iterations at this point. Vi likes using :/?! a lot. The = is not that important to
me, as the : for the vi ex: command. The ! is very satisfying in this location.

For US-intl and Bepo which have dead keys, the symbol layer uses the *not_dead* extension
to give _'`"^~_ which are not dead.

The beakl symbol layer is intuitive and fairly easy to remember. There are 3 versions.
The original, an extended, and an extended and enhanced for vi.
The primary purpose of the extension was to provide keys which might not be available
elsewhere on the default layer. The vi version takes this further and moves :/? 
to better places.

I prefer a modified beakl15 symbol layer. here it is, left and right.
This layer has some extra characters so it works with non-beakl base layouts.
The beakl wi symbol layer is not an improvement on this IMO.
Miryoku symbols layer is only left sided, and minimalist as well.
This might be a little vi centric, with the : in the middle. ymmv.

There are a few choices, this is one.

```
        `<$>'  ?[_-] 
      - \("#)  !{:/} ;
        @=*+;  %&^~|
```


## TopRows Layer

The toprows layer is a nice way to transition to small keyboards.
I think, truly this is the layer that makes tiny keyboards accessible in the beginning.
Everything can remain familiar. I use this one with a beakl number row.
The default, if no choices are made, aside from enabling toprows, will  
have a normal qwerty number row, as in the second map.

I do not use F keys, The latest addition has _smart_ and _nshot mods_ in the third row.
There is a miryoku thumb cluster which uses this layer instead of a keypad.

    ```
    !@#$%   ^&*()
    40123   76598
    F1   ---  F10
    ```
 or

    ```
    !@#$%   ^&*()
    12345   67890
    F1   ---  F10
    ```

## Keypad and Funcpad Layers

There are several variations of keypads and function key pads in various sizes,
and left and right. 
There are also versions with smart and nshot mods instead of F-keys.
There are monolithic, left and right, and also half keyboard left mostly...
A miryoku version also exists.
The keypad can be chosen in config.h.

```
    523:  F9-12 
   7.104  F5-8
   /698,  F1-4
```
## Media Layer

A simple Miryoku, media layer, controls on the right.

OLED
--------------------
The oled shows the basic stuff I could find in most places. 
* Default layer
* Current layer
* Locale
* Mods 
* Locks 
* Last key pressed
* Map of the current layer as simply as possible. (128x64)

Process_records.c
--------------------
This is where the keycodes are processed...
It tends to be where cruft gathers. Mostly I try to keep it empty
and do all my processing with the extensions.  The file, _extensions.h_ 
takes care of inserting them in process_records with it's macro.


Extensions
---------------------
Extensions are all in the extensions directory and have a single 
entry point via extensions.h which provides a macro to place in **process_record_user**. 
The intention is that they are easy to copy and use as is without digging around
in the C code. Custom keys are also defined there. Any keycodes defined by
an extension are automatically added to the custom keys enumeration so there is no need to define them manually.

A new extension can be added with a process record entry in
extensions.h. Just follow the same code pattern. If an extension defines keycodes, 
add it's include entry in *keycodes.h* so that they are automatically added to the enum. 
Keycodes.h is also where all the miscellaneous short cut key defines are done. 

To copy all the extensions, 
  * Copy the extensions and defs folders, 
  * Copy process_records.c file or adapt yours.
  * Adapt your custom keycodes to custom_keys.def.
  * Copy the pertinant parts of config.h so that everything can be enabled.
  * Define _USERSPACE_H such that all the extensions can find your stuff.

To adapt to your own process_record_user do this;
Include extensions.h in your process_record_user,then add this 
above the switch.
```
PROCESS_EXTENSIONS
```
This will cause process records to use whatever extensions are turned on.

Many extensions have a _.def_ file in _/defs_ for any data that is needed.

Because many of them use custom keycodes or layers in their definitions, 
it is necessary to include your userspace .h such that keycodes and layer
codes can be found. To simplify this, simply add a define to config.h
to point at your .h or wherever your custom codes can be found.

In my case;
```c
#define USERSPACE_H "ericgebhart.h"
```


Custom keys
-------------------
The Custom keys are in __custom_keys.def__.

__keycodes.h__ is an extension of sorts. It is the custom keys enumeration.
The __custom_keys.def__ has a few random keycodes in it.

All other keys are automatically generated from the other def files.

For the extensions that have key definitions those keys are enumerated
automatically. The keys are defined in the def files so there is no need
to add them to the enumeration manually.

It will complain as usual if there are duplicates.

Mostly, __keycodes.h__ is key defines to make shortcuts, since the enumeration
is done almost completely automatically. When adding a new extension
which defines keycodes, that extension will also need an entry in 
keycodes.h in order to automatically define the new key enumerations
it´s def file creates.


Accent keys
-----------------
This is a way to create keycodes which access keys
which are normally only accessible with an Altgr/Ralt and a dead key.

Each definition takes a keycode, the key to modify, and the dead key
to apply to it.

```
ACCENTED(BP_OCIR, BP_O, BP_DCIR)
ACCENTED(BP_ACIR, BP_A, BP_DCIR)
```


Alternate keycodes 
-----------------------------
Normally, a keycode has unshifted and shifted key values. These are defined
by the OS and it's locale, not the keyboard. This feature allows a keycode 
to be defined that uses arbitrary unshifted and shifted keycodes and their modifiers. 
This is necessary, because, for instance, qwerty has , and ; paired. Other
locales may not. Bepo, and Beakl both have different pairings as do many other
layouts.

Because of wanting dvorak and beakl on bepo there was the necessity to create keys
from keycodes which were not combined. key overrides were not 
sufficient because some keys are not actually keys that can be accessed
without modifiers. Each keycode for the new key specifies it's own
modifiers making any character available as an unshifted or shifted key.

Alternate keys for a locale, are defined in **altlocal_keys.def**.
These are to emulate a key, from 2 keycodes. 

This is for emulating keys on another locale/language.
Dvorak on Bepo-fr, or Qwerty on sk-SK, or de_DE.

It is also good for alternate shifted and unshifted pairs like
what is needed for beakl or hands down on en-us/qwerty.

This feature is usually only needed for punctuation keys 
and the top row number keys. Where the unshifted and shifted keys
are not the same character as the keyboard local on the OS.

It has turned out that most of these keys have a destination language,
and a target language/layout. 
The target is to emulate something on some language. QMK uses keycode prefixes,
so this works pretty well and the names stay consistent with all the others,
but with a middle name.

The pattern is Language prefix, target language prefix, name.
The target prefix is made up. BK -> beakl, DV -> dvorak, HD -> hands down, etc.

The naming pattern is only important in that it works with all of the Lang
macros elsewhere in this userspace. A macro is provided on a per key 
basis, which can be used at the base layer definition, such that *TL_COMM*; 
target-language-comma, becomes BP_BK_COMM, or KC_BK_COMM, or whatever it 
needs to be based on 
current language and target layout.

Here is a def entry to create the 1/! keycode for dvorak in the Bepo-fr locale
in *altlocal_keys.def*.
```
  MK_KEY(BP_DV_1,    BP_DQUO, MOD_LSFT,      BP_DCIR, MOD_LSFT)
```

Here is what some Beakl keys look like for en-us/qwerty.
Beakl has dot with @, comma with ! and " with `.

In *altlocal_keys.def*.
```
  // Keys for BEAKL on Qwerty
  MK_KEY(KC_BK_DOT,  KC_DOT, MOD_NONE,    KC_2, MOD_LSFT)
  MK_KEY(KC_BK_COMM, KC_COMMA, MOD_NONE,  KC_1, MOD_LSFT)
  MK_KEY(KC_BK_QUOT, KC_QUOT, MOD_NONE,   KC_GRV, MOD_NONE)
```

Not Dead keys
--------------------
As a writer dead keys give me access to accented letters in other languages,
As a programmer they are a pain, especially for a vi user. This problem is
limited to a few characters; "'`^ and ~. This extension helps to fix these
characters and make them accessible as non-dead keys. It does this by adding
a space afterward. The space is eaten by the OS keyboard driver and the letter
emerges as needed. Here are some non dead keys for US-Intl.
In use, I put these on the symbol layer, and let all the others remain dead.

```
NOT_DEAD(US_DQUO_ND, US_DQUO)
NOT_DEAD(US_GRV_ND,  US_GRV)
NOT_DEAD(US_QUOT_ND, US_QUOT)
NOT_DEAD(US_CIRC_ND, US_CIRC)
NOT_DEAD(US_TILD_ND, US_TILD)
```

Alternate shifts
---------------------
The alt shift extension is very simple, it uses a usual keycode, it does
not define custom keys. It allows for an existing key like dot or semi-colon 
to have a different letter on its shifted value. 

There are currently three types of shift mods.
  * Give a different character than usual on shift.
  * Give two of the usual character instead of one.
  * Give three of the usual character instead of one.

They are all defined in *defs/alt_shift.def*.
Here are some silly examples.

```
ALT_SHIFT(US_EXLM, US_PERC)
SHIFT_FOR_2(US_AT)
SHIFT_FOR_3(US_DLR)
```


Key Overrides
-------------------
These are the standard QMK key overrides. For un/shifted pair keys *altlocal_keys* is
much, +3x, smaller and direct in that it makes keycodes that can be placed anywhere.
However, if ko's are desired, this extension is an easy place to start.

There are nice macros which take care of defining everything that is possible
with the ?_ko() functions

This first example is better done with **altlocal_keys**.

```
// KOL(slash_pipe,      MOD_MASK_SHIFT, KC_SLSH, KC_PIPE, _DVORAK_EN)
```

Other key overrides can be defined with these.

```
KO(name, mods, key, replacement)

KOL(name, mods, modded_key, replacement, layer)

KOLN(name, mods, key, replacement, layer, neg_mods)

KOLNO(name, mods, key, replacement, layer, neg_mods, options)
```

Combos/Chords
----------------------------

The combos here use multiple reference layers which is a pending
pull request in the dev branch of QMK. The combos here will still work
to an extent if *COMBO_ONLY_FROM_LAYER* is set to the correct layer number.

[See my pull request to enhance combos here](https://github.com/qmk/qmk_firmware/pull/16699)

This pull request defines a hook function for combos to determine the
reference layer for the current layer.  This allows for multiple reference
layers to be used depending on the situation.

Reference layers will be created and used according to the following
defines. 
If the reference layer is enabled, it will automatically be assigned to
COMBO_REF_DEFAULT and that will be the default reference if none
is specified. If not specified, the reference will be the current layer.

  * #define COMBO_REF_LAYER_ENABLE // enable a reference layer.
  * #define COMBO_REF_LAYER_TWO_ENABLE // enable a second reference layer
  * #define COMBO_ONLY_FROM_LAYER 2
  * #define COMBO_REF_DEFAULT 2
    Works in config.h if you know the number of your layer.
    Automatically set if ref layer is enabled.

Defining layer specific combo reference layers by layer in combos.def
In this case, the default will be _COMBO_REF, the NAV layer will
reference it's self, while bepo dvorak will reference the second
combo reference layer. Keys start or end with CB or CB2.
    
```
COMBO_REF_LAYER(_DVORAK_BP, _COMBO_REF2)
COMBO_REF_LAYER(_NAV, _NAV)
```

The combo reference layers follow an easy to remember keycode naming
convention so that it is easy to define combos based on position.
Keycodes are prefixed by CB or CB2, the first number is the row,
followed by L or R for left and right, then the column number,
for each hand left to right.

Row 0 is the number row, there are 4 rows possible.

`CB_1L1` is the left pinky, `CB_1R1` is the inside right hand index column.

```
  _1L1,  _1L2, _1L3, _1L4,  _1L5,   _1R1, _1R2, _1R3, _1R4, _1R5, 
```

If there are edge keys, they are named accordingly, left and right.

```
L0_CB, L1_CB, L2_CB, L3_CB
R0_CB, R1_CB, R2_CB, R3_CB
```

Thumb keys use the COMBO and COMBO2 thumb settings which give keycodes
like this.

```
#define ___6_ERGO_THUMBS_COMBO___  CB_TH1, CB_TH2, CB_TH3, CB_TH4, CB_TH5, CB_TH6
#define ___6_ERGO_THUMBS_COMBO2___ CB2_TH1, CB2_TH2, CB2_TH3, CB2_TH4, CB2_TH5, CB2_TH6
```

Tap-Hold
-----------------------

Tap hold currently has *tap_taplong* and *open_openclose* functions.
These are in *tap_hold.c*, *tap_hold.h* and *tap_hold.defs*.
Both use **TAP_HOLD_TERM** as the hold duration.

Tap_taplong sends one keycode on tap, and another after a hold of tapping term.
Open_openclose, sends one keycode on tap, hold sends that, plus the second, 
followed by a back arrow.

Additionally, open_openclose will send a triple of the open keycode when tapped with
the shift modifier on.

There as also a __not dead__ version of open_openclose that accomodates using
dead keys like quote so that the functionalty behaves as if the key were not
a dead key, giving a quote, a pair of quotes or a triple of quotes.

The file _tap_hold.defs_ contains all the definitions. Like combos,
these entries are processed with a function call from **process_user_record**
`process_tap_hold_user(keycode, record);`

Define your keys in *tap_hold.defs*.

Here is Ctrl-C, Ctrl-V, as tap and long tap.
```
TP_TPL(KC_CCCV, LCTL(KC_C), LCTL(KC_V))
```

For tap open, hold for open and close then a back arrow.
Here is __(__ or __()__ with tap and long tap.

```
OPEN_OCL(KC_OCPRN, KC_LPRN, KC_RPRN)

OPEN_OCL(KC_OCQUOT, KC_QUOT, KC_QUOT)
// non dead version of quote.
OPEN_OCL_ND(BP_OCQUOT, BP_QUOT, BP_QUOT)
OPEN_OCL_ND(US_OCQUOT, US_QUOT, US_QUOT)
```

It is also possible to trigger a smart lock with a hold.
This example creates a keycode, `ENTNAV` which can be used
to type enter, or smart lock the nav layer.
Note that `SML_NAV` should be defined in `smart_lock.defs`.

__Caveat:__
This does have the unfortunate behavior of delaying the action
until key up. So it may not be that useful. I did not like it
for this particular example.

```
TP_SML(ENTNAV, KC_ENTER, SML_NAV)
```

Caps Word
-------------
This is a slightly modified version of caps word which adds a *CAPS_WORD_ON* keycode
which can be used to turn caps word on explicitly. This is useful for mapping a
single key or creating a combo.

[As documented in here.](https://getreuer.info/posts/keyboards/caps-word/index.html)
Holding both pinkies on home row for double tapping term, is effectively 
right-shift and left-shift, invokes caps-word. The next word will be capitalized. 
It continues until it shouldn't.

Smart lock
----------------
They are defined in *smart_lock.def*. They need
a custom keycode, and a layer or mods, not mod keycode, to apply, 
followed by a list of keycodes to ignore and stay active. 
This allows popping to layer which will stick until it doesn't. 
Or to apply mods until it shouldn't. Each definition has it's
own list of key codes to ignore. Derived from _smart_layers_
by @possumvibes.

Add a keycode to custom_keys.def then assign it to it's action in smart_lock.def.
```
// SMLL = smart lock layer.
// SMLM = smart lock mod.

// Keycode, layer/mod.
// list of keycodes to ignore.

SMLM(SMLM_LSFT, MOD_LSFT,
  ___VI_ARROWS___,
  ___HOME_PGDN_PGUP_END___,
  ___TAB_PGDN_PGUP_BKTAB___,
  ___SML_MODS_L___)

SMLL(SML_NAV, _NAV, ___NAVA_3x10___)

```

Mod lock
----------------
Mod lock is originally from @possumvibes, it has ignore keys as well,
but these keys apply to all locks defined. which gives a slightly smaller 
memory footprint than smart locks. The mods, are keycodes, rather than mod codes.

The behavior is the same as smart lock mods, but less flexible, and smaller.
First create a keycode in custom_keys.def, then assign it to the mod you want.

Ignore keys are universal for all mod locks.

```
// mod lock keys. takes keymods not mods.
// keycode should be defined in custom_keys.def.
// custom key,  modkey to activate
MODL(ML_LSFT, KC_LSFT)
MODL(ML_LCTL, KC_LCTL)
MODL(ML_LALT, KC_LALT)
MODL(ML_LGUI, KC_LGUI)

// Keycodes which will NOT cancel mod lock mode.
IGNORE_KC( KC_LEFT)
IGNORE_KC( KC_RGHT)
```

N-shot mods
----------------
I simply modified N-shots to use a def file. This is essentially @possumvibes
fancier version of @callum's one shot mods. It has ignore and cancel keys,
and there are one shot mods or N shot mods. Ignore and cancel keys apply
to all oneshot and n-shots.

```
// Define keycodes in custom keys.
// KEYCode, mod keycode, to set for n-shot.
// ONESHOT is for one.
// NSHOT takes a count.

// oneshots
ONESHOT(OS_LSFT, KC_LSFT)

// N-Shots
NSHOT(TS_LCTL, KC_LCTL, 2)

// Keys which will cancel the n-shots.
CANCEL_KEY( PANIC)

// Keys which will be ignored by n-shots.
IGNORE_KEY( SML_NAV)
```

One-shot mods
----------------
This code came by way of @jurgen-kluft, I encapsulated the code and made 
the user functions definable with a .def file. This is similar to N-shots. 
This one keeps track of the last key consumed which helps it's decision making. 
It also has cancel and ignore keys like N-shots.

Essentially the same as n-shots, but with less elegant C code. Choose one or
the other. 

In evaluation.  The code for nshots is better.

```
// custom-key, Oneshot name.
ONESHOT( OS_LSFT, ONESHOT_LSFT)

// keys to cancel
CANCEL_KEY( KC_ESC)

// keys to ignore.
IGNORE_KEY( SPC_NAV)
```

Swapper
----------------
I added the defs code so they are easy to define. This is a way to
alternate between 2 keycodes for a key by sending another keycode. An
example is tab or backtab on one key, which reverses when you press a
second key. It also allows for mods to be applied. The following defines
SW_WIN, which sends left alt-tab and shift- left alt- tab, when reversed
by SW_REV.

```
SWAPPER_KEY(SW_WIN, SW_REV, KC_TAB, S(KC_TAB), KC_LALT)
```
Note: The switch key is not automatically defined in the custom keys enum in
_keycodes.h_. It is convenient to use the same one which causes problems
for automatically adding it. Add it to *custom_keys.def*

Encoders
----------------
This is basic encoder stuff, modified to use a def file which makes it a lot easier
to define and use. It can switch the encoder functions based on layers and mods.
Give it a layer name and/or mods to match on, and the clockwise and counter 
clockwise keycodes to send.

I used LEFT and RIGHT, but really it's just 0-N, but I happen to have one
on the left and one on the right. If you have one, use 0 or LEFT.

The code scans the entries for matches on layer first, checking for a match for
mods. If an encoder entry is not found it then scans for entries with
layer set to LAYER_NONE.

RGB light controls require calling the functions directly, for this
there is a special macro and function that does this. The functions
should take no arguments.

```
// Layer/none, encoder index 0/1, CW_KC, CCW_KC, Qualifying mod or none
// LAYER_NONE and MOD_NONE for a single use.
// LEFT and RIGHT for index. they go on from there, 2, 3, etc
// if one encoder, LEFT/0, is the first one, on the master side.

// default encoders, all layers no mods.
ENCODER_ACTION(LAYER_NONE, RIGHT,  KC_PGDN, KC_PGUP, MOD_NONE)
ENCODER_ACTION(LAYER_NONE, LEFT,  KC_DOWN, KC_UP, MOD_NONE)
ENCODER_ACTION(LAYER_NONE, LEFT,  KC_PGDN, KC_PGUP, MOD_LSFT)

// Symbol layer encoders.
ENCODER_ACTION(_SYMB, LEFT, KC_LEFT, KC_RIGHT, MOD_NONE)

// RGB function encoders
ENCODER_FUNCTION(_RGB, LEFT,
                rgb_matrix_increase_speed_noeeprom,
                rgb_matrix_decrease_speed_noeeprom, MOD_NONE)
```


Unicode
----------------
This is just the basic unicode example everyone seems to have.
Add your keys to send unicode strings like so.

```
 UC_STR(UC_DISA, "ಠ_ಠ")
```

Send_string
--------------
This is just basic send string functionality using *SEND_STRING* and 
*SEND_STRING_DELAY*. Each entry defines a key to send a string.

```
SEND_STR(MYKEY, "this is a test")
SEND_STR_DELAY(VRSN, QMK_KEYBOARD ":" QMK_KEYMAP " @ " QMK_VERSION ", Built on: " QMK_BUILDDATE)
```

Console key logging - for heat maps.
----------------------
Both CONSOLE_ENABLE and CONSOLE_KEY_LOGGER_ENABLE must be enabled for this to work.

This is a console key logger which can save keys typed for analysis of keymaps
using Vlad/Precondition's heat map tool. The code for the logger came from
[here](https://precondition.github.io/qmk-heatmap#how-to-collect-the-required-data)
The explanation and use of the heatmap is [here](https://precondition.github.io/qmk-heatmap)

There is a script ```listen_keylogger.sh``` which should be run to collect
the keylogger data. 

This does require **hid_listen** to be installed on the computer.
On Arch linux this can by installed from the AUR with ```yay -S hid_listen```

The output can also be seen just by using ```qmk console```.

Note: _print.h_ is automatically included when CONSOLE_ENABLE is set. This allows 
for debug messages anwhere in the code base as needed to see what might be going
on.

Tap Dance
--------------------
I had a lot of tap dance, It's turned off. It's big. tap-hold works pretty well most of the time, instead.
My favorites were tab-backtab,  home-end.