docs/feature_auto_shift.md

   1 # Auto Shift: Why Do We Need a Shift Key?
   2
   3 Tap a key and you get its character. Tap a key, but hold it *slightly* longer
   4 and you get its shifted state. Voilà! No shift key needed!
   5
   6 ## Why Auto Shift?
   7
   8 Many people suffer from various forms of RSI. A common cause is stretching your
   9 fingers repetitively long distances. For us on the keyboard, the pinky does that
  10 all too often when reaching for the shift key. Auto Shift looks to alleviate that
  11 problem.
  12
  13 ## How Does It Work?
  14
  15 When you tap a key, it stays depressed for a short period of time before it is
  16 then released. This depressed time is a different length for everyone. Auto Shift
  17 defines a constant `AUTO_SHIFT_TIMEOUT` which is typically set to twice your
  18 normal pressed state time. When you press a key, a timer starts and then stops
  19 when you release the key. If the time depressed is greater than or equal to the
  20 `AUTO_SHIFT_TIMEOUT`, then a shifted version of the key is emitted. If the time
  21 is less than the `AUTO_SHIFT_TIMEOUT` time, then the normal state is emitted.
  22
  23 ## Are There Limitations to Auto Shift?
  24
  25 Yes, unfortunately.
  26
  27 1. Key repeat will cease to work. For example, before if you wanted 20 'a'
  28    characters, you could press and hold the 'a' key for a second or two. This no
  29    longer works with Auto Shift because it is timing your depressed time instead
  30    of emitting a depressed key state to your operating system.
  31 2. You will have characters that are shifted when you did not intend on shifting, and
  32    other characters you wanted shifted, but were not. This simply comes down to
  33    practice. As we get in a hurry, we think we have hit the key long enough
  34    for a shifted version, but we did not. On the other hand, we may think we are
  35    tapping the keys, but really we have held it for a little longer than
  36    anticipated.
  37
  38 ## How Do I Enable Auto Shift?
  39
  40 Add to your `rules.mk` in the keymap folder:
  41
  42     AUTO_SHIFT_ENABLE = yes
  43
  44 If no `rules.mk` exists, you can create one.
  45
  46 Then compile and install your new firmware with Auto Key enabled! That's it!
  47
  48 ## Modifiers
  49
  50 By default, Auto Shift is disabled for any key press that is accompanied by one or more
  51 modifiers. Thus, Ctrl+A that you hold for a really long time is not the same
  52 as Ctrl+Shift+A.
  53
  54 You can re-enable Auto Shift for modifiers by adding another rule to your `rules.mk`
  55
  56     AUTO_SHIFT_MODIFIERS = yes
  57
  58 In which case, Ctrl+A held past the `AUTO_SHIFT_TIMEOUT` will be sent as Ctrl+Shift+A
  59
  60 ## Configuring Auto Shift
  61
  62 If desired, there is some configuration that can be done to change the
  63 behavior of Auto Shift. This is done by setting various variables the
  64 `config.h` file located in your keymap folder. If no `config.h` file exists, you can create one.
  65
  66 A sample is
  67
  68     #ifndef CONFIG_USER_H
  69     #define CONFIG_USER_H
  70
  71     #include "../../config.h"
  72
  73     #define AUTO_SHIFT_TIMEOUT 150
  74     #define NO_AUTO_SHIFT_SPECIAL
  75
  76     #endif
  77
  78 ### AUTO_SHIFT_TIMEOUT (Value in ms)
  79
  80 This controls how long you have to hold a key before you get the shifted state.
  81 Obviously, this is different for everyone. For the common person, a setting of
  82 135 to 150 works great. However, one should start with a value of at least 175, which
  83 is the default value. Then work down from there. The idea is to have the shortest time required to get the shifted state without having false positives.
  84
  85 Play with this value until things are perfect. Many find that all will work well
  86 at a given value, but one or two keys will still emit the shifted state on
  87 occasion. This is simply due to habit and holding some keys a little longer
  88 than others. Once you find this value, work on tapping your problem keys a little
  89 quicker than normal and you will be set.
  90
  91 {% hint style='info' %}
  92 Auto Shift has three special keys that can help you get this value right very
  93 quick. See "Auto Shift Setup" for more details!
  94 {% endhint %}
  95
  96 ### NO_AUTO_SHIFT_SPECIAL (simple define)
  97
  98 Do not Auto Shift special keys, which include -\_, =+, [{, ]}, ;:, '", ,<, .>,
  99 and /?
 100
 101 ### NO_AUTO_SHIFT_NUMERIC (simple define)
 102
 103 Do not Auto Shift numeric keys, zero through nine.
 104
 105 ### NO_AUTO_SHIFT_ALPHA (simple define)
 106
 107 Do not Auto Shift alpha characters, which include A through Z.
 108
 109 ## Using Auto Shift Setup
 110
 111 This will enable you to define three keys temporarily to increase, decrease and report your `AUTO_SHIFT_TIMEOUT`.
 112
 113 ### Setup
 114
 115 Map three keys temporarily in your keymap:
 116
 117 | Key Name | Description                                         |
 118 |----------|-----------------------------------------------------|
 119 | KC_ASDN  | Lower the Auto Shift timeout variable (down)        |
 120 | KC_ASUP  | Raise the Auto Shift timeout variable (up)          |
 121 | KC_ASRP  | Report your current Auto Shift timeout value        |
 122 | KC_ASON  | Turns on the Auto Shift Function                    |
 123 | KC_ASOFF | Turns off the Auto Shift Function                   |
 124 | KC_ASTG  | Toggles the state of the Auto Shift feature         |
 125
 126 Compile and upload your new firmware.
 127
 128 ### Use
 129
 130 It is important to note that during these tests, you should be typing
 131 completely normal and with no intention of shifted keys.
 132
 133 1. Type multiple sentences of alphabetical letters.
 134 2. Observe any upper case letters.
 135 3. If there are none, press the key you have mapped to `KC_ASDN` to decrease
 136    time Auto Shift timeout value and go back to step 1.
 137 4. If there are some upper case letters, decide if you need to work on tapping
 138    those keys with less down time, or if you need to increase the timeout.
 139 5. If you decide to increase the timeout, press the key you have mapped to
 140    `KC_ASUP` and go back to step 1.
 141 6. Once you are happy with your results, press the key you have mapped to
 142    `KC_ASRP`. The keyboard will type by itself the value of your
 143    `AUTO_SHIFT_TIMEOUT`.
 144 7. Update `AUTO_SHIFT_TIMEOUT` in your `config.h` with the value reported.
 145 8. Remove `AUTO_SHIFT_SETUP` from your `config.h`.
 146 9. Remove the key bindings `KC_ASDN`, `KC_ASUP` and `KC_ASRP`.
 147 10. Compile and upload your new firmware.
 148
 149 #### An Example Run
 150
 151     hello world. my name is john doe. i am a computer programmer playing with
 152     keyboards right now.
 153
 154     [PRESS KC_ASDN quite a few times]
 155
 156     heLLo woRLd. mY nAMe is JOHn dOE. i AM A compUTeR proGRaMMER PlAYiNG witH
 157     KEYboArDS RiGHT NOw.
 158
 159     [PRESS KC_ASUP a few times]
 160
 161     hello world. my name is john Doe. i am a computer programmer playing with
 162     keyboarDs right now.
 163
 164     [PRESS KC_ASRP]
 165
 166     115
 167
 168 The keyboard typed `115` which represents your current `AUTO_SHIFT_TIMEOUT`
 169 value. You are now set! Practice on the *D* key a little bit that showed up
 170 in the testing and you'll be golden.