Modifier Strings

Modifier Strings

Capsicain tracks the state of all real and virtual modifiers.

To define a COMBO rule you must specify for which modifier state the rule applies.
To do so, you write a modifier string like [&.&.]

Autohotkey does it like "A & LCONTROL & LSHIFT :: B"
Capsicain would say "A [&&] > key(B)"

AHK style is easier for easy things.
Capsicain is easier for difficult things (but you have to understand these mod strings first).

Each position in the mod string represents one modifier.

Modifier Positions in the modifier string

 ┌Invalid
 │┌MOD15
 ││┌MOD14
 │││┌MOD13
 ││││
 ││││ ┌MOD12
 ││││ │┌MOD11
 ││││ ││┌MOD10
 ││││ │││┌MOD9
 ││││ ││││ 
 ││││ ││││ ┌Right Alt
 ││││ ││││ │┌Right Win
 ││││ ││││ ││┌Right Control
 ││││ ││││ │││┌Right Shift
 ││││ ││││ ││││ 
 ││││ ││││ ││││ ┌Left Alt
 ││││ ││││ ││││ │┌Left Win
 ││││ ││││ ││││ ││┌Left Control
 ││││ ││││ ││││ │││┌Left Shift
 ││││ ││││ ││││ ││││
[.... .... .... ...&]  <- an & in position 1, counted from the right, this means "& LeftShift"
[.... .... .... ..&.]  <- an & in position 2, this means "& LeftControl"
[.... .... .... &...]  <- an & in position 4, counted from the right, this means "& LeftAlt"
[.... .... .... ..&&]  <- this means "& LeftControl & LeftShift"
[.... ...& ..&& ..&&]  <- this means "& MOD9 & RightControl & RightShift & LeftControl & LeftShift"

Modifier State Symbols

You can test modifiers for any of the following states:

    &   AND: the modifier is down  
    |   OR:  any one or several of the OR modifiers is down  
    ^   NOT: the modifier is up  
    T   Tapped: The modifier was tapped. You can combine as many tapped and pressed modifiers as you want.  
    .   ignore this modifier, dont care about its state

(for coders: each of these conditions is stored in a 16-bit var. We could use a 64-bit var, but which Earthling can deal with 64 modifiers?)

EXAMPLES

modifier string [.... .... .... ..&.] means "Left Control is down, don't care about other modifiers"  

modifier string [&.] means the same. An & in position 2 from the right.  
Spaces and leading '.' are just for pretty formatting.

 A [...&]       matches key combo [LeftShift] + key [A].  All other modifiers may or may not be pressed.  
 A [..&.]       matches LeftControl + A  
 A [.&..]       matches LeftWin + A  
 A [&...]       matches LeftAlt + A  
 A [...& ....]  matches RShift + A

 A [...| ...|]  matches ( RShift OR LShift ) + A
 A [...| ..&|]  matches LCtrl AND ( RShift OR LShift ) + A
 A [..|| ..||]  matches any Ctrl or Shift key is down + A

 A [&..&]       matches LShift + LAlt + A  
 A [^..&]       matches LShift and NOT-LAlt + A  
 B [...& ...&]  matches RightShift + LeftShift + B  

 C [...T]       matches Tapped-LShift, then C  
 C [..TT]       matches Tapped-LShift AND Tapped-LCtrl, then C  
 D [.&TT]       matches Tapped-LShift, Tapped-LControl, then Win + D

 A [.... .... ...&] matches same as A [...&]  
 E [...& .... ....] matches MOD9 key + E
 F [&.. .... .... ....] matches MOD15 + F (MOD15 is the highest modifier)

 F [&&&& &&&&]  is  all 8 standard modifiers down + F

 G []           matches any G, modifiers do not matter

Is this clear enough? If not, please open a ticket.

Background

Shadowing: many keyboards have limits about how many (and which) keys you can press at the same time.

For example, on my Apple keyboard, the [ESC]+[CapsLock] combo shadows (blocks) all keys on the home row (asdfg hjkl).

The real modifiers are usually no problem; vendors make sure many of them can be pressed at the same time.

If you rewire regular keys to modifiers, you might have problems to press many of them simultaneously.

We are dealing with physical keys here, NOT with characters

"key A" means "the electrical switch on the left side that sends scancode #30 - on a standard US IBM keyboard it has a plastic keycap with an A printed on it".

In other words, the labels on your keyboard do not always tell the truth. The "semicolon" switch on a German keyboard has a "Ö" keycap on it. Windows (or Linux or MacOS) will later translate incoming "semicolon" to "Ö" if a German layout is active. Capsicain sees the semicolon, it knows nothing about language settings and other fancy stuff.

Deep down the driver stack, the labels on the IBM Model M (US) keyboard are the only truth. It says that the bottom left key is "key 44", and that key will always send a "44" (unless you have special hardware like a DVORAK board, but then you already know all this). If your keyboard layout is "Standard English", then your OS translates "key 44" to "Character Z".

What Windows knows matters

Usually, Windows receives all incoming keys, and processes them with standard Windows rules.

With Capsicain, this changes. If you REWIRE CAPS MOD9, then the CapsLock key will only trigger matching MOD9 combos, but "CapsLock" is never forwarded to Windows (because it was rewired), and "MOD9" is never forwarded, because the the virtual MODifiers are capsicain only, Windows does not know them. Your text editor will never know when you press the CapsLock key.

On the other hand, if there is no matching rule that consumes the key event, Capsicain forwards all regular keys to Windows. Which means that Windows knows when LWIN is down, and this may trigger Windows behaviour (for example, Windows standard is that tapped-LWIN means "open the Start menu").

If you configure many clever combos with the WIN key, I recommend you rewire it to MOD11 first. I will otherwise predict many open Start menus in your future.