Modifier for toggle keys

[bitoj]

It would be useful to have access to the state of *Lock keys (CapsLock, NumLock, ScrollLock) and possible other toggle keys (on Asian keyboards, I think) in combo rules. Currently we have modifiers with a state up, down or tapped. Toggled could be a fourth state of a modifier,

Another approach could be to introduce special modifiers that represent the state of a toggle key. There is a precedent in the CAPSON virtual key that can be sent. Those could be defined in code, like CAPSON.

A third approach could be a mapping syntax to make one of the current virtual modifiers MOD9 - MOD15 reflect the state of a toggle key, with a mapping defined in a configuration with new syntax. Perhaps another variant of REWIRE, or a new keyword.

As an example of what I would like to accomplish, see the following configuration, that uses a currently non-existent modifier MOD16, which in this example somehow reflects the toggle state of the CapsLock key.

[CONFIG_7]
OPTION configName mod16

COMBO ' [.... .... ...^ ...^] > deadkey(')
COMBO DEADKEY-' E [^... .... ...^ ...^] > altchar(0233) # é
COMBO DEADKEY-' E [&... .... ...| ...|] > altchar(0233) # é
COMBO DEADKEY-' E [^... .... ...| ...|] > altchar(0201) # É
COMBO DEADKEY-' E [&... .... ...^ ...^] > altchar(0201) # É

As a proof of concept I added support for this state by hardcoding it in capsicain.cpp function processCombos. (That is the second approach described above.)

        if (modcombo.vkey == loopState.vcode)
        {
            unsigned short downOrToggled = modifierState.modifierDown;
            if ((GetKeyState(VK_CAPITAL) & 0x0001))
                downOrToggled |= 0x8000;
            if (
                (modifierState.activeDeadkey == modcombo.deadkey) &&
                (downOrToggled & modcombo.modAnd) == modcombo.modAnd &&
                (modcombo.modOr == 0 || (downOrToggled & modcombo.modOr) > 0) &&
                (downOrToggled & modcombo.modNot) == 0 &&
                ((modifierState.modifierTapped & modcombo.modTap) == modcombo.modTap)
                )
            {

With this modification, the example given above actually works as intended.

[cajhin]

Nice. I see you didn't forget how to read and write C code :)
AltChars and CäPSLøCK state is an unsolved problem.

What I like is that your solution is clean and straight forward.
Disadvantages:

1. you now have to define 4 combos for each accented char

2. for GetKeyState(), you need to call Windows and that adds overhead to the key processing.
   It's only ~10 microseconds, sounds negligible, but that is 50% more time for every key event. And it might be much more if Windows is busy. For accented chars I don't care much, they are rather slow and rare anyway, but ideally it shouldn't impact the common case, the 99.9% of normal key events.

What I've been thinking about is along the lines of a "consider capslock state" flag CLS, like

COMBO DEADKEY-' E  [ CLS  ...^ ...^] > altchar(0233) # é
COMBO DEADKEY-' E  [ CLS  ...| ...|] > altchar(0201) # É

The "CLS" would tell processCombo to not use the plain Shift state, but first calculate the 'effective shift state' (CapslockState XOR Shift).
With that, you'd need only two combos, and the lookup of the system capslock state would only happen for special characters.

I'm unhappy with the .ini syntax, though. [ CLS ...^ ...^] makes the modstring even more unintuitive than it already is... any ideas?

[bitoj]

Doubling the number of combo rules would not be a real problem for configuration maintenance, because there is a pattern to it. That means duplication can be scripted. Run-time evaluation of twice the number of rules might be a more significant issue.

Evaluating GetKeyState for each key press (or even more often - I think I put it in an inner loop in the PoC) should of course not be necessary in a real world solution. That leads to a requirement on the way this should be configured: the modifier that somehow represents the toggled state should be recognizable as such, so that evaluation can wait until it has been determined that it is necessary to do so, based on static criteria (other modifiers) that are matched first.

Your candidate syntax satisfies this requirement. But I think we might be able to find an even better syntax, though I don't have an answer ready.

Let's discuss the aspect that struck me immediatelely: bitwise operators are encoded in two ways. In one line there is an operation keyword CLS, with one implied operand (let's call it CAPSON) and a list of operators to apply to other bits that together provide the second operand.

To me this suggests there should be a elaboration of the derivation logic. Perhaps there might be a convenient way to generally express combinations of modifier states, with an effect like

DERIVE SHIFTED LSHF | RSHF
DERIVE CAPITAL SHIFTED ^ CAPSON          # XOR; or another symbol, because ^ already used

DERIVE CAPITAL (LSHF | RSHF) ^ CAPSON    # or even full expressions

COMBO DEADKEY-' E (CAPITAL)  > altchar(0201) # É
COMBO DEADKEY-' E (!CAPITAL) > altchar(0233) # é

Something tlike this would be a completely new way to describe bit patterns that should replace or be an distinct alternative to the current syntax. Right now I can't imagine an extension to the original bit pattern syntax with AND, OR and XOR operators and precedence rules that will be appropriate in all use cases. Even now the combination of OR and AND only works more or less intuitively, because we only use OR for combing left OR right shift/control/alt keys.

[bitoj]

I have given your CLS proposal some more thought and reconsidered my desire to have a completely general solution for all combinations of all possible toggle keys. As a first step towards a compromise, I am currently testing with a CLS-like XOR operator ~. Here is the most obvious scenario, with the CapsLock state hardcoded on the MOD16 pseudo-mofier as before.

COMBO DEADKEY-' U [~... .... ...| ...|] > altchar(0218) # Ú
COMBO DEADKEY-' U [.... .... .... ....] > altchar(0250) # ú

As you see I haven't come up with a pattern for the inverse result, but relied upon a fallthrough match with a broader scope.

The ~ XOR oparator takes the result of the | evaluation as one of its operands. That means the following patterns are equivalent.

COMBO R [.... .... ...~ ...~] > moddedkey(R + &)
COMBO R [.... .... .... ....] > moddedkey(R + .)

COMBO T [.... .... ...~ ...|] > moddedkey(T + &)
COMBO T [.... .... .... ....] > moddedkey(T + .)

I also heavily optimized the GetKeyState access from my earlier proof of concept, to prevent most unnecessary calls. All changes are in the caps-mod branch of my fork. Maybe you can see that I had to relearn a bit of C++ for this experiment.

Would you like me to prepare a pull request to have a closer look?

[cajhin]

I'm also thinking of retiring the AltChar system, or support two systems.
SendInput() directly sends any Unicode char to the foreground window. This is much nicer to configure than AltChars,
but (there's always a but), this can cause new trouble: apps cannot send key presses to other apps that have a higher "security level". Capsicain is nothing special, so it can send its keys to the keyboard driver all day, but SendInput() will fail if the target is either some kind of security box, and (like AltChar) it doesn't work in Linux VMs.
It works in RDP sessions though.
Same as AutoHotkey, basically.

If you want to try it out, replace your betaTest() with this and then press ESC+B

void betaTest() //ESC+B
{
    //test SendInput
    {
        // Create a keyboard event structure
        INPUT ip;
        ip.type = INPUT_KEYBOARD;
        ip.ki.time = 0;
        ip.ki.dwExtraInfo = 0;

        // Press a unicode "key"
        ip.ki.dwFlags = KEYEVENTF_UNICODE;
        ip.ki.wVk = 0;
        ip.ki.wScan = 0x0E8; // è
        SendInput(1, &ip, sizeof(INPUT));

        // Release key
        ip.ki.dwFlags = KEYEVENTF_UNICODE | KEYEVENTF_KEYUP;
        SendInput(1, &ip, sizeof(INPUT));
    }

[bitoj]

I hope to examine this further next weekend. But I have a strong suspicion that it won't work for my remote work, which is the current full time standard.

Not because of SendInput, but because you are sending characters instead of keys. I base this conclusion on my experiences with AHK, using something like this.

Numpad1::
  SendInput one
  Return

Numpad2::
  SendInput {text}two
  Return

The first sends key strokes based on the current keyboard lay-out. It works both locally and remotely.

The second sends characters. It doesn't work remotely, likely because the PCoIP client I have to use to access AWS WorkSpaces only uses input with scan codes, that it feeds in the remote input stream for the virtual keyboard of the remote session. Characters seem to be ignored.

The explanation for my experiences above is only based on the AHK documentation though. I haven't examined the AHK source code or tested with something like your example above.

That SendInput {text} doesn't work was actually the reason that I started looking for an alternative for AHK. I was happy to find a solution that specializes in properly handling keys and even allows alt-combinations for any keyboard layout without needing elavated privileges (unlike AHK SendPlay). A nice program called capsicain, you might have heard of.

[bitoj]

Confirmed: the SendInput betaTest works locally, but not remotely.

[cajhin]

I chewed on this problem a bit recently. The design in my head is

a) SendInput would be an addition to altChar, not a replacement. It should allow strings ("Hello"). Probably confusing for newbies why this doesn't always work.

b) altChar could be extended like this:

altChar ( 0123 ) #types a single character
altCharShift ( 0123 , 0124 ) # type one or the other, depending on Shift xor Caps state
altCharUnicode ( € ) # translates the char to "+8364" and types it. Requires .ini in UTF-8. Nicer to read, easier to write when you have a character table.

Open questions:

1. would one need a dedicated altCharShiftCaps that evaluates both Shift and CapsLock state, or can we blindly assume that pairs of characters are always upper/lowercase, thus caps always shifts? I can only think of !¡ and ?¿ , those should not be affected by caps, but both ! and ? are already covered. (by default, CapsLock only shifts the A-Z keys, but doesn't impact other keys. Do we need to define where Caps does and does not shift?)

2. is unicode in the .ini a good idea or a source of more trouble?

[bitoj]

The default you describe about A-Z and CapsLock behavior, seems somewhat biased by QWERTY or Swiss QWERTZ usage.

You might want to take into account that CapsLock on some keyboard layouts (like French and Belgian AZERTY, German QWERTZ) is actually a "ShiftLock". But not for all keys. The ` and L\ keys are typically exceptions. Another peculiarity is the Windows Czech QWERTZ layout, where Shift does not always produce capitals, but CapsLock does.

So people might have different expectations about different keys. Perhaps several variations should be available to choose from by the user that makes the configuration.

Unicode is a very good idea for .ini files. I am surprised you ask, because the 3 ini files you supplied in the v80 distribution are all UTF-8. Two of them even have a byte order mark.

A very minor bit of trouble is that Capsicain currently doesn't handle the BOM well (sorry, should have opened an issue). But that only affects the first line, which is often a comment.

Of course more small bugs could come to light when capsicain performs more processing with Unicode code points, or at least those from the BMP in Windows UTF-16 wide characters. Now the Unicode ini content is all in comments.

[cajhin]

I looked at your code (kinda forgot it since it appeared in the middle of this thread). I probably don't understand it completely, but it looks like it should work. Just some loose thoughts below...

Its weakness (as I see it) is that you have a lot of logic that implements a quasi generic solution for a problem class, but, at the end of the day, can only cover a very specific case (shiftlock). That could have been easier with specific code triggered by altCharCaps or similar, that explicitly evaluates the capslock state for specific cases, with hardcoded logic.
Unless you want to have xor for other cases - but who needs LCtrl xor (LAlt || RAlt) ?

For a truly generic solution, you probably want to define that 'capsLock state' is a modifier (which it is, basically).
Then you could set bit 16 of modifierState.modifierDown depending on the capsLock state, and just process all modifiers as usual, without explicit capslock checks.
To be able to rely on that bit, you'd have to either a) read the capslock state for every keypress or b) set the bit on key send (capsicain knows when it sends the capslock key, so it could know the state without asking Windows. Only need to read it on startup and resume from disabled/off).

An option that might be easier to understand would be '1' instead of 'xor', testing that exactly 1 of the modifiers is down.
like [1... .... ...1 ...1]
(result is non-standard when you press both Shift keys, that's a bit academic though).

The ini symbol ^ is a bit unfortunate, in hindsight. Down v Up ^ is intuitive, but inconsistent with the C symbols & | ^ ~ ...

[bitoj]

I completely agree that the XOR operator is a solution to a limited set of requirements. I do not currently foresee using it in combination with anything else than shift and something else. But it has the following merits.

• It works.
• It is a simple extension of current syntax.
• The pattern can at least be useful when applied to other toggle keys when their state is made available in a similar way, especially NumLock (for full numeric keypad simulation, inclusing navigation keys, on a small keyboard). Your altchar proposals up to now are limited to CapsLock combinations.

But anyway, the XOR operator is only a way to reduce the number of rules by one third, so there is no real need for it. I can enjoy Capsicain without it, as I said earlier. It was more an experiment to implement something like your earlier CLS idea, but without introducing completely new syntax.

The code indeed has a lot of new lines, but not primarily for the XOR operator. Most code involves the new modifier CapsLocked. But not as plainly as you wrote in your third paragraph above or in my earlier proof of concept.

The construction to test the modifier state combinations in several stages is meant to limit the number of excursions to Windows for GetKeyState to get the current CapsLock state. I concluded that we cannnot rely on a stored CapsLock state, because that state can change without using the physical keyboard, and consequently without Capsicain observing the change. Namely, applications like MS Word have auto-correct options that actually reset that state, perhaps using something like SendInput.

As you said yourself, getting that state for each keypress could be expensive. Even more so when the other toggle keys (at least ScrollLock and NumLock) are added to the mix.

I think my next experiment will be to add those, and put all toggles on bits 17 and higher and skip 16 for other purposes. That will involve some bitmap size changes, obviously.

[cajhin]

The first question would be, why do you want to change the result of a keypress depending on NumLock and ScrLock?
I totally get CapsLock, but not 'other' toggle keys (not something I would want to use, I don't like toggle very much since when you're typing blindly, it adds insecurity).

To solve the "capslock with altChar()" issue, my favorite solution still is some kind of
combo ... > altCharIfCaps( 123, 456 )

Implementation is a bit convoluted, since the config reader can only pass keys (and key sequences) to the core.
For new special cases, you need new virtual keys that trigger the feature.
e.g. new VK_CPS_IFCAPS = (next free scancode)

In config, translate altCharIfCaps(123,456) to the key sequence
VK_CPS_IFCAPS alt 1 2 3 VK_CPS_IFCAPS alt 3 4 5

(or define a 2nd vk: "VK_CPS_IFCAPS 1 2 3 VK_CPS_ELSECAPS 4 5 6", bit easier to read but an extra VK

Then in playKeyEventSequence()
detect the VK_CPS_IFCAPS,
evaluate state of capslock and shift,
cut out the correct sub-sequence (alt123 or alt456)
playKeyEventSequence(sub-sequence)

That of course handles only the very specific issue, but it does it well (probably).
Simple .ini syntax and efficient processing (runs only when a rule with altCharIfCaps fires)

[bitoj]

Let's indeed leave the XOR discussion for now and concentrate on the main subject of this thread, toggle keys.

I agree with your objection to toggles when you are typing blindly. But my indended use is not about continously working in a certain way, but switching modes.

A large part of my day job is reviewing other people's work. That is mainly browsing through documents (not code, b.t.w.), and occasionally switching to commenting. Other blocks in my calendar are again devoted to producing stuff myself.

So there are two distinct modes with different keyboard usage patterns. For browsing through a document without editing or commenting, I prefer to use the same keys I use for navigation that I use while editing, but without pressing a modifier. I do not like switching to the layout that the keyboard manufacturer created, for only one of these modes.

Currently I do this with different configurations, something like:

[CONFIG_1]
OPTION configName Main
INCLUDE editing

[CONFIG_2]
OPTION configName Review
INCLUDE navigation

[editing]
COMBO U      [.... .^&. .... ....] > comboNtimes(DOWN, 8)

[navigation]
COMBO U      [.... .^.. .... ....] > comboNtimes(DOWN, 8)

It works, but the disadvantage is that I cannot see which mode I am in, e.g. when I return from a Teams meeting on one of my other computers or some other interruption. I would really like to see the ScrLock LED to have a visual confirmation tthat I am reviewing.

So instead, I would prefer a configuration like below.

[CONFIG_3]
OPTION configName Everything
INCLUDE navigation-scrlock
INCLUDE editing

[navigation-scrlock]
COMBO U [..&. .... .^.. .... ....] > comboNtimes(DOWN, 8)

[editing]
COMBO U      [.... .^&. .... ....] > comboNtimes(DOWN, 8)

The CapsLock experiments I did until now, I really consider only a preparation for the above. CapsLock is not really significant in my work. I chose it as an example, because I suspected it is relevant to more people.

But, given the fact that there is a desire for CapsLock improvements, I really like your approach. It looks like a clever way to introduce the CapsLock state in the decision logic. If you can somehow take into account the different expectations of different international users I mentioned earlier, I think you have a winner.

But our approaches are not really that different with respect to performance, because we both match on other modifiers first, and only look at the CapsLock state when it is finally necessary to make that distinction. The main differences are, I think, that your approach takes fewer lines of configuration, and my approach allows other functions than altchar, like perhaps sequence or moddedkey. (The latter might be useful in certain base layouts with AltGr). And of course my approach allows generalizations like the one I would like for ScrLock, like in the hypothetical example above with comboNtimes.

[cajhin]

First question is, do you aim to develop something cool, or do you want to solve your issue at hand...
For the latter I think of

• my own solution for distinct "reading" and "writing" modes is to just have a keyboard with physical cursor keys. I can lean back and use my left hand when I'm not typing for a while

• if the difference for you is just the capsLock key: I recently kicked out the "sticky mods" feature during a clean up, as I wasn't using it. You could tap any modifier while ESC was down; then the "modifier up" was dropped, and both capsicain and Windows believed the key was still down. Reset with Esc or tap the modifier again. If you want this, I can put it back in in like 3 minutes

• I recently put in the dedicated on/off key, which can control the LEDs. Would be easy to have a dedicated "toggle last two configs" key with LED control (I almost did it because it seems easy, but I didn't see the use case for it)

• a possible convenient feature I was toying with in my mind is auto-switching configs depending on the active Window. Like
  [config_2]
  ifActiveWindow Photoshop
  ...
  [config_3]
  ifActiveWindow Cyberpunk
  ...

  The open issues are performance (don't want to test for active Window change on every key event), and reliability (not sure how to detect the Window, its title might change). Both should be not too hard to solve.

[bitoj]

Thanks for thinking with me.

A variation of the third option would best fit my style of working. Switching to a known explicitly set configuration would be better than switching between last two configs, I think. With the last two configs variation, I still would need to remember what I did most recently, to know what the LED means and predictably end up where I want.

That would be a generalization of, or alternative to, the CapsicainOnOfKey setting, like ToggleConfigKey, combined with something like AlternativeConfig (with default 0 in the first case).

Some comments on the other options:

• Hardware navigation keys are typically inconveniently split in two islands. And my trials with a separate physical numeric keypad for some reason were not very succesful. Something to do with combining modifiers on the main keyboard with the numpad. Also, I would prefer a fixed layout for navigation that even works on a laptop keyboard (whenever we will be travelling for work again).
• Sticky modifiers do not appeal to me. It sounds limiting, and something you have to work around in a config design. With a separate toggle you increase options, but with a sticky modifier you reduce options.
• The active window approach would not work in my usual remote access settting. Also, when I switch from reviewing to
  commenting on a document, it would usually be in the same window. It sounds like a neat idea, though. A bit comparable to the Windows option to remember the last used keyboard layout for each window. (An option that I switched off, because this often resulted in having the wrong layout for a new window.)

[cajhin]

Option 1: a killer feature of dedicated cursor keys is that you can easily feel them. Always takes brain activity to position your hand over jkl;
Option 2: sticky modifiers are actually super simple. All they do is keep a key pressed, so you don't have to hold down a modifier for 3 minutes
Option 4: right, win detection will fail in RDP sessions

Option 3: shouldn't be too hard, but, I have no clear vision how that should work.
If you use a single key (let's say ScrollLock because it has an LED), then you can only toggle between two states.
What should those states be, if not "the last two configs"?
Fixed configured like "ScrollLock -> toggle config 1 and 3" ? "Toggle config 3 and previous config" ?

My favorite for my own config would probably be two dedicated combos, like
tap Ctrl, tap ScrLock -> switchConfig(3) and LED on
tap ScrLock -> switchConfig(1) and LED off

Edit: no longer like the approach below, after writing and reading it...

GLOBAL ToggleConfigKey NUMLOCK 1/3 //toggle config 1 / 3
or
GLOBAL ToggleConfigKey NUMLOCK 1/OFF //toggle main config / off
or
GLOBAL ToggleConfigKey NUMLOCK ON/OFF //toggle on/off, no config change

would cover all common cases. Still need to define when/which LED lights up, so you could toggle with Numpad+ and show state with NumLock LED. Getting a bit complicated.
What should happen when you are on config 7 and press the 'toggle 1/3' key?

[bitoj]

Maybe make each switch explicit, by defining it in the configuration itself. Please have a look at my PR.

An improvement on that would be to add new virtual keys LEDON and LEDOFF and allow sequence(LEDON:SCRLLOCK).