Support for key suppression

[boppreh]

Right now all events report after-the-fact. It should be possible to suppress keys, keeping them from being processed by applications down the line. This allows users to create global hotkeys without affecting the focused application, for example.

This is possible in Windows, but would require moving the hotkey processing back into the hook.

Linux seems to be trickier. Maybe relying on X, like https://github.com/alols/xcape ?

Finally, extreme care must be taken to not introduce input lag. Because all hotkeys will be processed in the main thread, blocking the event they analyze, it would be too easy to add precious milliseconds to every key press, which is not acceptable.

[boppreh]

There are three major complications.

1. Linux events are emitted after-the-fact, so there's nothing we can do to suppress it. Any solution here will require radically changing the way Linux events are captured, possibly requiring special code for each environment (console, X, Wayland).
2. Even when we can technically suppress events (Windows makes it easy, for example), there's input lag. Python is not a fast language, and power users may be registering hundreds of hotkeys. We must assure they will all be processed in no more than a couple of milliseconds, otherwise the user starts experiencing uncomfortable delays when typing.
3. What happens if one hotkey is contained in another? If I register ctrl+a and ctrl+a, space, what should happen? Should we block the event to see if the next key is a space (tremendous input lag)? Should the second hotkey never be triggered (would require some sort of warning)? It's not an easy problem.

I am interested in resolving this issue for the windows platform and may contribute if I have time. The main information that I would like to clarify before beginning is what the general architecture for this will be. Personally I believe the best option in a practical sense would be to allow the user to register key combinations to be blocked (this could be done by simply adding suppress=True to any applicable functions). If done this way, suppression can be done only purely within keyboard, which would allow delays to be strictly controlled.

Moving to the delays specifically: suppression is something that may need to be done using cython. What I'm envisioning is something like this:

1. User calls keyboard.add_hotkey(...suppress=True)
2. Everything that currently happens now happens. But in addition, keyboard stores they key combination in keys_to_suppress.
3. Keyboard registers an os-specific cython module with the operating system that simply compares input to the keys_to_suppress and suppresses the input if there is a match.
4. Keyboard calls the user function, which may or may not duplicate (pass through) the original request.

Regarding your third point, that would simply be up to the user. So if the user added suppress=False (which would be the default) to the ctrl+a, space, then input would not be blocked. But if the user added suppress=True, then it would. Input would only be blocked up until the point where it would not be able to satisfy keys_to_suppress.

[boppreh]

Sorry, I'm on my phone and misclicked. Please ignore the previous message.

Hi xoviat. Thank you for your interest.

I'm not sure I understand why cython may be needed. The library actually had this feature at the beginning, via a "blocking=True" parameter, and only ctypes was needed. Are you suggesting using cython for performance?

I like your idea of the keys_to_suppress variable. I agree this looks like the correct answer to avoid putting all hot keys on the critical path.

I don't understand your comment about ctrl+a, space. If the user registers both ctrl+a and ctrl+a, space (in this order), both with suppress=True, then types ctrl+a, space. What should happen?

Should both hotkeys be triggered? One could argue this is incorrect because the first one matched and requested suppress=True, which should suppress further hotkeys from accepting it.

Should only the first one trigger? But the user explicitly asked for the second hotkey to be triggered, and the user typed the key sequence. The library knew about the conflict at the time of registration, so an exception or at least a warning should be raised, instead of accepting a useless request. This is still a problem because users may be using the library in a background process, so they won't see the warning, and exceptions would only make everything stop working. I'm personally tending to this side, but I'm not happy.

What do you think?

I'm not sure I understand why cython may be needed.

If we're going to check all keys against the keys_to_suppress, then as you noted, we will need a very tight loop. Cython can significantly improve execution time. I am not saying that we will need this but it is an option if there is too much delay in the user input.

Should only the first one trigger?

My point was that this is not as critical as it seems because these events will not be happening within the loop that is suppressing the keys. In other words, if 'ctrl+a, space` is registered to be suppressed, then the entire sequence of keys needs to be put on hold regardless of others keys that have been registered.

With respect to program delay, that's not related specifically to this issue. I'm not specifically sure what would happen, but the answer is: whatever currently happens. The only difference that this change is going to make is whether other applications receive keyboard input. This change won't affect what keyboard sees. Personally, however, I do agree that an exception should be raised when a duplicate hotkey is registered because overusing exceptions is the Pythonic way to do things. Just look at removing a file that you aren't sure exists.

[glitchassassin]

For a possibly more pertinent example, how will this be affected if the user has different hotkeys (with suppression) set up for "ctrl+a" and "a"?

I'll create a truth table so everyone can understand behavior clearly. The answer is: it will be suppressed under the behavior that I have described if keyboard currently calls the handler. The only relevant difference with this is timing.

The current behavior appears to be the following:

add_hotkey('a', print, args=['a was pressed'])
add_hotkey('Ctrl+a', print, args=['Ctrl+a was pressed'])
[Ctrl+a] a was pressed
[a] a was pressed

add_hotkey('Ctrl+a', print, args=['Ctrl+a was pressed'])
add_hotkey('Ctrl+a, space', print, args=['Ctrl+a, space was pressed'])
[Ctrl+a, space] Ctrl+a was pressed
[Ctrl+a] Ctrl+a was pressed

It appears to be that only the shortest combination is recognized and all others are ignored. So, under the implementation that I am proposing, any longer key combination would simply be suppressed and would not actually call a handler.

Update: looking at the API, setting blocking=False would call the other handlers, so whether other handlers are in fact called would depend on the value of this option.

Ctrl+a, suppress	Ctrl+a, blocking	a, suppress	a, blocking	Behavior
True	True	True	True	Suppress all Call a handler
True	True	True	False	Suppress all Call both
True	True	False	True	Suppress Ctrl+a Call a
True	False	True	True	Suppress all Call a handler
False	True	True	True	Suppress all Call a handler
True	True	False	False	Suppress Ctrl+a Call both
True	False	False	True	Suppress Ctrl+a Call a handler
False	False	True	True	Suppress all Call a handler
True	False	False	False	Suppress Ctrl+a Call both
False	False	False	False	Suppress none Call both

Note: "Suppress Ctrl+a" means wait for the entire key combination before allowing input.

For my own reference:

using System;
using System.Diagnostics;
using System.Windows.Forms;
using System.Runtime.InteropServices;

class InterceptKeys
{
    private const int WH_KEYBOARD_LL = 13;
    private const int WM_KEYDOWN = 0x0100;
    private static LowLevelKeyboardProc _proc = HookCallback;
    private static IntPtr _hookID = IntPtr.Zero;

    public static void Main()
    {
        _hookID = SetHook(_proc);
        Application.Run();
        UnhookWindowsHookEx(_hookID);
    }

    private static IntPtr SetHook(LowLevelKeyboardProc proc)
    {
        using (Process curProcess = Process.GetCurrentProcess())
        using (ProcessModule curModule = curProcess.MainModule)
        {
            return SetWindowsHookEx(WH_KEYBOARD_LL, proc,
                GetModuleHandle(curModule.ModuleName), 0);
        }
    }

    private delegate IntPtr LowLevelKeyboardProc(
        int nCode, IntPtr wParam, IntPtr lParam);

    private static IntPtr HookCallback(
        int nCode, IntPtr wParam, IntPtr lParam)
    {
        if (nCode >= 0 && wParam == (IntPtr)WM_KEYDOWN)
        {
            int vkCode = Marshal.ReadInt32(lParam);
            Console.WriteLine((Keys)vkCode);
        }
        return CallNextHookEx(_hookID, nCode, wParam, lParam);
    }

    [DllImport("user32.dll", CharSet = CharSet.Auto, SetLastError = true)]
    private static extern IntPtr SetWindowsHookEx(int idHook,
        LowLevelKeyboardProc lpfn, IntPtr hMod, uint dwThreadId);

    [DllImport("user32.dll", CharSet = CharSet.Auto, SetLastError = true)]
    [return: MarshalAs(UnmanagedType.Bool)]
    private static extern bool UnhookWindowsHookEx(IntPtr hhk);

    [DllImport("user32.dll", CharSet = CharSet.Auto, SetLastError = true)]
    private static extern IntPtr CallNextHookEx(IntPtr hhk, int nCode,
        IntPtr wParam, IntPtr lParam);

    [DllImport("kernel32.dll", CharSet = CharSet.Auto, SetLastError = true)]
    private static extern IntPtr GetModuleHandle(string lpModuleName);
}

[boppreh]

I really the ideas here so far. Unfortunately I'm on vacation, with little to no computer or even Internet access until the 27th of December. So I can't contribute much until then.

I will still be able to answer questions, but with some hours of delay.

I believe that my implementation is almost complete. What is a bit disturbing though is that while running the tests, the _depressed variable in KeyTable was not correctly tracking the number of keys that were depressed at the time (it believed that significantly more keys were depressed than was actually the case), which does not bode well for multistep combinations. The code that I am using to track how many keys are depressed is the following:

    if is_up:
        depressed = self._depressed - 1
    else:
        depressed = self._depressed + 1

    if not depressed:
        key = self.SEQUENCE_END

is_up comes from simply checking whether the event is a KEY_UP event:

if allowed_keys.is_allowed(name, event_type == KEY_UP):

[boppreh]

I'm back from the holidays. I had been following this pull request, and I have to say it'd very impressive. I'll schedule some time to properly review it as soon as possible.

Thank you