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 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 ------------------- -I have a lot of custom keys because of bepo. It is somewhat confusing this interaction -between a keyboard and the software that receives it. +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. -A lot of my pain is invoked by my desire to have dvorak on bepo. Which works just fine, -although an english/cyrillic situation may not work so well. Currently I have -dvorak and beakl on bepo in addition to bepo it's self. +Each definition takes a keycode, the key to modify, and the dead key +to apply to it. -Alternate keycodes for emulating a layout on another locale/language. +``` +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. For this I have a special function that -takes a keycode and gives a proper shifted character for it. It is only a 2 keycode -definition, but it does the basic non-shifted and shifted characters as you define them. +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 ---------------------------- -This is recently new to me. I'm using them on my thumb keys which are all LT's. -the combos allow for layer locking for the Nav layer, and a oneshot for symbols -among other things. -I followed the simple example at the end of the doc than uses the -combos.def file to define the combos. +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. -Tap-mods -------------------------------------- -I had been using MT on my thumbs for GUI,CTRL,ALT on hold along with -Escape, Enter, space and backspace, my thumb keys. I then added shift to my home row pinky key. -I had layer shifts to symbols, numbers, navigation all on the home row of both hands. -It worked nicely but choppy I think, switching hands for the holder of the layer is -a little like having no caps lock. It was a lot of work adding them to all my maps. -This is what prompted my mod_layer. So much easier. No maps to modify. - -Then I moved to all home row mods with layers on my thumb keys. - -This does allow for more rolls, and I have found chord/rolls simply from having my -xmonad controls be GUI-some-home-row-key-or-close. When Gui is your index finger, -everything gets easier. - -Somewhere along the way I got a corne, and everything had to be small. and I realized -that everything really was small. My layers are blending back, with LTs near the -home row, and all the thumbs. On my dactyl I currently have 8 thumb keys per thumb, -I don't know what to do with them all. Remembering a time I thought that would be -awesome. - -### tap_taplong and open_openclose -In process_records.c I have a nice couple of functions, -tap_taplong(), and open_openclose() for my non MT/LT functionality. - - * I have home row mods for Shift, Ctrl, Alt, and Gui on both hands. - * I have a number of LT mods to raise layers nearby. Nav, toprows, symbol, keypad - are on both hands on the first and third rows around home row. - * Xmonad tap_taplong to pull up desktops or terminals with tap or hold. - * C-c/C-v, C-t/C-n, C-w/C-q are all on my Navigation layer as custom keys with tap_taplong. - * My thumbs are Enter/space and Esc/backspace which are also Navigation and toprows and symbol layers. They used to be GUI,CTRL,ALT,SFT. but all that's on the home row now. - * All of the paired characters on my symbol layer have a hold which closes them, and moves the cursor back between. - -### caps word +[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. -BEPO vs Qwerty Locale/language/Layers ---------------------- -Essentially they are different keycode sets. So anything that needs them, causes a layer. -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. +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. -I only have bepo, dvorak and beakl on bepo. There are a bunch for Qwerty. -I have a ton of basic layers. I'm most interested in beakl at the moment, but I've used Dvorak for more than 20 years. There is also qwerty, colemak, norman, carplax, etc. +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. -The navigation/mouse layer is not affected by bepo/qwerty, but symbols and numbers are. -There are bepo versions of everything that needs it. +// Keycode, layer/mod. +// list of keycodes to ignore. -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. -This layer is not affected by bepo/qwerty, but symbols and numbers are. -There are bepo versions of everything that needs it. +SMLM(SMLM_LSFT, MOD_LSFT, + ___VI_ARROWS___, + ___HOME_PGDN_PGUP_END___, + ___TAB_PGDN_PGUP_BKTAB___, + ___SML_MODS_L___) -Arrow combos work just fine, in emacs I use SFT(arrows) to move between windows. -To do this; shift is my left pinky home, Nav is right thumb Enter, and one of the four -home keys of my left hand are the arrows. Home row mods allow this to work well. +SMLL(SML_NAV, _NAV, ___NAVA_3x10___) -I don't use the arrows on the dactyl and kinesis, even though they are there. +``` -Symbol Layer -------------------- -The symbol layer is based on the Beakl15 symbol layer. -The beakl symbol layer is intuitive and fairly easy to remember. There are 3 versions. -The original, an extended called A, and an extended and enhanced for vi, called B. -The primary purpose of the extension was to provide keys which might not be available -elsewhere on the default layer. B, takes this further and moves :/? to better places. +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. -TopRows Layer --------------------- -I think, truly this is the layer that makes tiny keyboards accessible in the beginning. -This is basically the number row, the shifted number row and the function key row. -I have them so it is numbers on the home row, shifted keys above and functions below. -There are multiple choices, I currently use the beakl number row, with everything -else as you would expect. +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. -Keypad Layer +``` +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 -------------- -There are several variations of keypads and function key pads in various sizes. -Currently I am using a Beakl Keypad on the left hand and 3x4 funcpad on the right. +This is just basic send string functionality using *SEND_STRING* and +*SEND_STRING_DELAY*. Each entry defines a key to send a string. -OLED --------------------- -It shows the basic stuff I could find in most places. The -default layer, the current layer, the mods, the locks, the last key pressed, and -a map of the current layer as simply as possible. I'm sure there is more that could -be done. @Drashna has some fancy stuff. If the display is big enough, there is even -a display of the current layer's keymap. +``` +SEND_STR(MYKEY, "this is a test") +SEND_STR_DELAY(VRSN, QMK_KEYBOARD ":" QMK_KEYMAP " @ " QMK_VERSION ", Built on: " QMK_BUILDDATE) +``` -XMonad ---------------------- -I use xmonad. Gui is my hot key for that. With home row mods I have home -row chords which give me access to my desktops, my scratchpads/terminals, -custom key KC_XM_PORD, among others. It sometimes feels that I am playing -an instrument when I invoke xmonad to do something. +Console key logging - for heat maps. +---------------------- +Both CONSOLE_ENABLE and CONSOLE_KEY_LOGGER_ENABLE must be enabled for this to work. -I had an xmonad layer at one time, it was basically dvorak, I would invoke it -with a GUI mod, so that even on bepo, or colemak, my xmonad commands remain the same. +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) -I'm going to need to revisit that, as things are, all the commands move when I change -to a different default layer from dvorak. +There is a script ```listen_keylogger.sh``` which should be run to collect +the keylogger data. -Combo's can alleviate some of this pain. More to play with. +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 have a lot of tap dance, It's turned off. It's big. tap-hold works pretty well most of the time, instead. +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. -Switching the OS keyboard -------------------------- -This varies from system to system. I use Arch Linux, so I use ```setxkbmap```. -I've included a helper script which makes it easy to switch between EN and FR Bepo, -called switch-kbd. In xmonad I invoke this with a keystroke. so, same deal. just map -the keystroke to a key. - |