diff options
Diffstat (limited to 'users/ericgebhart/readme.md')
| -rwxr-xr-x | users/ericgebhart/readme.md | 1708 |
1 files changed, 1540 insertions, 168 deletions
diff --git a/users/ericgebhart/readme.md b/users/ericgebhart/readme.md index 4a081bd344..446a1411b4 100755 --- a/users/ericgebhart/readme.md +++ b/users/ericgebhart/readme.md @@ -1,212 +1,1584 @@ Overview ======== -Warning: dvorak touch typist, that uses qwerty and bepo locales on my -computer. 40+ years of vi, 30 years of vi in Emacs. - -Recent years I have gone minimal, I don't use most of the keys on my ergodox, -or original edition dactyl. These maps work great on large and small keyboards, -my preference seems to be 40% split ergo keyboards like the corne. - -I think that what is special here is the layouts. I don't worry too -much about leds, or RGB, although I do like oled. But really its mod_layer.h, -all the simple layer chunks and definitions, and the ability to apply that -to any keyboard with minimal effort. The other thing is the example it -provides for defining keymaps based on different OS locales. I use both -dvorak on Qwerty, and bepo/dvorak on bepo. That means I must change my -locale on my OS to match my keyboard which can do qwerty or bepo locales. - -It is possible, as I do, to send a keycode invoking xmonad, to execute my -qwerty - bepo switch on my computer. - -Besides using dvorak, another thing that colors my keyboard code is that I -have used the kinesis -advantage for for more than 2 decades. I have used the ergodox ez for several years -as well, so the evolution of my keymaps starts there with space, enter, backspace -and delete keys on the thumbs. - -Layouts +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 evolved from the old layout...wrapper code. Calling everything a wrapper seems -silly. So I took a step back. - -Also, with all these layers it was a real pain to apply mods consistently and -easily. 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. - -All layouts, almost, boil down to a 3x5 x 2 matrix. Bepo is 3x6. Mostly, I want -my controls to stay the same. As we have been conditioned, these are the keys on -the edges, or middle. Not that they can't change but I don't usually change them -much, except the side edges, - the extra pinky columns. -the F keys, the columns to the left and right and the row on the bottom. -Thumb keys if you have them. Even the number row is practically the same. - -With that in mind, reducing my layouts to 3x10 or 12 matrices would be great. -At the same time extracting my mods so they are easy to apply to any matrix. -So that's what is here. - -At the bottom is the LAYOUT, needed by the keeb you have. Then I have my Layouts -to feed it with my ROWS macros which are my MOD layer. At the end of it all, -I give a 3x10 or 12 to a layout and I have a complete keyboard definition. -Creating a new keyboard map is super simple. - - * mod_layer.h is the place for home row mods or any other mods. - * layouts.h is where I define a new matrix using the ROW macros when I need one. - * core_keys.h - where I define my custom keys. Ya know, the big enum. - * altlocal_keys.c - Alternate key/shift keys for emulation on other locales. - * core_keysets.h - Base layers; qwerty, dvorak, beakl, colemak, norman, carplax... - * edge_keys.h - defines the edges and bottom/thumb keys of a keyboard. - * layers.h - defines actual layers for navigation, symbols, keypad, layers, top rows, etc. +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 ar |