diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/feature_auto_shift.md | 161 | ||||
| -rw-r--r-- | docs/understanding_qmk.md | 1 |
2 files changed, 162 insertions, 0 deletions
diff --git a/docs/feature_auto_shift.md b/docs/feature_auto_shift.md new file mode 100644 index 0000000000..a054c36528 --- /dev/null +++ b/docs/feature_auto_shift.md @@ -0,0 +1,161 @@ +# Auto Shift: Why do we need a shift key? + +Tap a key and you get its character. Tap a key, but hold it *slightly* longer +and you get its shifted state. Viola! No shift key needeed! + +## Why Auto Shift? + +Many people suffer from various forms of RSI. A common cause is stretching your +fingers repeitively long distances. For us on the keyboard, the pinky does that +all too often when reaching for the shift key. Auto Shift looks to aliviate that +problem. + +## How does it work? + +When you tap a key, it stays depressed for a short period of time before it is +then released. This depressed time is a different length everyone. Auto Shift +defines a constant `AUTO_SHIFT_TIMEOUT` which is typically set to twice your +normal pressed state time. When you press a key, a timer starts and then stops +when you release the key. If the time depressed is greater than or equal to the +`AUTO_SHIFT_TIMEOUT` then a shifted version of the key is emitted. If the time +is less than the `AUTO_SHIFT_TIMEOUT` time, then the normal state is emitted. + +## Are there limitations to Auto Shift? + +Yes, unfortunately. + +1. Key repeat will cease to work. For example, before if you wanted 20 'a' + characters, you could press and hold the 'a' key for a second or two. This no + longer works with Auto Shift because it is timing your depressed time instead + of emitting a depressed key state to your operating system. +2. Auto Shift is disabled for any key press that is accompanied by one or more + modifiers. Thus, Ctrl+A that you hold for a really long time is not the same + as Ctrl+Shift+A. +3. You will have characters that are shifted you did not intend on shifting, and + other characters you wanted shifted, but were not. This simply comes down to + practice. As we get in a hurry, we think we might have hit the key long enough + for a shifted version, but we did not. On the other hand, we may think we are + tapping the keys, but really we have held it for a little longer than + anticipated. + +## How do I enable Auto Shift? + +Add to your `rules.mk` in the keymap folder: + + AUTO_SHIFT_ENABLE = YES + +If no `rules.mk` exists, you can create one. + +Then compile and install your new firmware with Auto Key enabled! That's it! + +## Configuring Auto Shift + +If desired, there is some configuration that can be done to change the +behavior of Auto Shift. This is done by setting various variables the +`config.h` file located in your keymap folder. + +If no `config.h` file exists, you can create one. A sample is + + #ifndef CONFIG_USER_H + #define CONFIG_USER_H + + #include "../../config.h" + + #define AUTO_SHIFT_TIMEOUT 150 + #define NO_AUTO_SHIFT_SPECIAL + + #endif + +### AUTO_SHIFT_TIMEOUT (value in ms) + +This controls how long you have to hold a key before you get the shifted state. +Obviously, this is different for everyone. For the common person a setting of +135 to 150 works great but one should start with a value of at least 175, which +is the default value. Then work down from there. The idea is to have as short +of a time required to get the shifted state without having false positives. + +Play with this value until things are perfect. Many find that all will work well +at a given value, but one or two keys will still emit the shifted state on +occassion. This is simply due to habit and holding some keys a little longer +than others. Once you find this value, work on tapping your problem keys a little +quicker than normal and you will be set. + +{% hint style='info' %} +Auto Shift has three special keys that can help you get this value right very +quick. See "Auto Shift Setup" for more details! +{% endhint %} + +### NO_AUTO_SHIFT_SPECIAL (simple define) + +Do not Auto Shift special keys, which include -_, =+, [{, ]}, ;:, '", ,<, .>, +and /? + +### NO_AUTO_SHIFT_NUMERIC (simple define) + +Do not Auto Shift numeric keys, zero through nine. + +### NO_AUTO_SHIFT_ALPHA (simple define) + +Do not Auto Shift alpha characters, which include A through Z. + +## Using Auto Shift Setup + +This will enable you to define three keys temporailiy to increase, decrease and report your `AUTO_SHIFT_TIMEOUT`. + +### Setup + +Map three keys temporarily in your keymap: + +| Key Name | Description | +|----------|-----------------------------------------------------| +| KC_ASDN | Lower the Auto Shift timeout variable (down) | +| KC_ASUP | Raise the Auto Shift timeout variable (up) | +| KC_ASRP | Report your current Auto Shift timeout value | + +Compile and upload your new firmware. + +### Use + +It is important to note that during these tests, you should be typing +completely normal and with no intention of shifted keys. + +1. Type multiple sentences of alphabetical letters. +2. Observe any upper case letters. +3. If there are none, press the key you have mapped to `KC_ASDN` to decrease + time Auto Shift timeout value and go back to step 1. +4. If there are some upper case letters, decide if you need to work on tapping + those keys with less down time, or if you need to increase the timeout. +5. If you decide to increase the timeout, press the key you have mapped to + `KC_ASUP` and go back to step 1. +6. Once you are happy with your results, press the key you have mapped to + `KC_ASRP`. The keyboard will type by itself the value of your + `AUTO_SHIFT_TIMEOUT`. +7. Update `AUTO_SHIFT_TIMEOUT` in your `config.h` with the value reported. +8. Remove `AUTO_SHIFT_SETUP` from your `config.h`. +9. Remove the key bindings `KC_ASDN`, `KC_ASUP` and `KC_ASRP`. +10. Compile and upload your new firmware. + +#### An example run + +\'\'\' +hello world. my name is john doe. i am a computer programmer playing with +keyboards right now. + +[PRESS KC_ASDN quite a few times] + +heLLo woRLd. mY nAMe is JOHn dOE. i AM A compUTeR proGRaMMER PlAYiNG witH +KEYboArDS RiGHT NOw. + +[PRESS KC_ASUP a few times] + +hello world. my name is john Doe. i am a computer programmer play with +keyboarDs right now. + +[PRESS KC_ASRP] + +115 +\'\'\' + +The keyboard typed `115` which represents your current `AUTO_SHIFT_TIMEOUT` +value. You are now set! Practice on the *D* key a little bit that showed up +in the testing and you'll be golden. diff --git a/docs/understanding_qmk.md b/docs/understanding_qmk.md index 2ac4f30365..99c2306d66 100644 --- a/docs/understanding_qmk.md +++ b/docs/understanding_qmk.md @@ -147,6 +147,7 @@ The `process_record()` function itself is deceptively simple, but hidden within * [`bool process_unicode(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/master/quantum/process_keycode/process_unicode.c#L22) * [`bool process_ucis(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/master/quantum/process_keycode/process_ucis.c#L91) * [`bool process_printer(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/master/quantum/process_keycode/process_printer.c#L77) + * [`bool process_auto_shift(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/master/quantum/process_keycode/process_auto_shift.c#L47) * [`bool process_unicode_map(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/master/quantum/process_keycode/process_unicodemap.c#L47) * [Identify and process quantum specific keycodes](https://github.com/qmk/qmk_firmware/blob/master/quantum/quantum.c#L211) |