Internal Global Hotkey Support (keybinder.py)

Xlib-based global hotkey-binding code

class KeyBinder(x_display=None)

A convenience class for wrapping XGrabKey.

Parameters:

x_display (Optional[Display]) – An Xlib display handle. If None, a new connection will be opened.

Raises:

XInitError – Failed to open a new X connection.

static _vary_modmask(modmask, ignored)

Generate all possible variations on modmask that need to be taken into consideration if we can’t properly ignore the modifiers in ignored. (Typically NumLock and CapsLock)

Parameters:

• modmask (Union[int, Gdk.ModifierType]) – An integer or Gdk.ModifierType bitfield to be combinatorically grown.

• ignored (Iterable[Union[int, Gdk.ModifierType]]) – Integer or Gdk.ModifierType modifiers to be combined with modmask.

Return type:

Iterator[int]

Returns:

The power set of ignored with modmask bitwise ORed onto each entry.

>>> list(KeyBinder._vary_modmask(Gdk.ModifierType.MOD1_MASK, []))
[8]
>>> list(KeyBinder._vary_modmask(Gdk.ModifierType.MOD1_MASK,
...                              [Gdk.ModifierType.MOD2_MASK,
...                               Gdk.ModifierType.LOCK_MASK]))
[8, 24, 10, 26]

bind(accel, callback)

Bind a global key combination to a callback.

Parameters:

• accel (str) – An accelerator as either a string to be parsed by Gtk.accelerator_parse() or a tuple as returned by it.)

• callback (Callable[[], None]) – The function to call when the key is pressed.

Return type:

bool

Returns:

A boolean indicating whether the provided keybinding was parsed successfully and didn’t provoke an error from XGrabKey.

cb_xerror(err, request)

Callback used to identify when attempts to bind keys fail.

Parameters:

• err (XError) – The error that was asynchronously returned.

• request (Any) – Unused. Just to match the required function signature.

cb_xevent(src, cond, handle=None)

GLib.io_add_watch() callback to dispatch X events to more specific handlers.

Parameters:

• src (GLib.IOChannel) – Not used. Just needed to satisfy GIOFunc signature.

• cond (GLib.IOCondition) – Not used. Just to needed to satisfy GIOFunc signature.

• handle (Optional[Display]) – A handle to the Xlib display object with pending events. A cached reference will be used if it is None.

Return type:

True

Returns:

Always returns True to prevent GLib from unsetting the watch.

handle_keypress(xevent)

Resolve Xlib.protocol.event.KeyPress events to the quicktile.commands.CommandRegistry commands associated with them and then call the commands.

Parameters:

xevent (KeyPress)

ignored_modifiers = ['Mod2Mask', 'LockMask']

Modifiers whose state should not affect whether a binding fires

keybind_failed = False

Used in concert with Xlib.display.Display.sync() to pass state from cb_xerror() to bind() so XGrabKey failure can be reported.

parse_accel(accel)

Convert an accelerator string into the form XGrabKey needs.

Parameters:

accel (str) – The accelerator string.

Return type:

Optional[Tuple[int, int]]

Returns:

(keycode, modifier_mask) or None on failure.

init(modmask, mappings, commands, winman)

Initialize the keybinder and bind the requested mappings

Parameters:

• modmask (Optional[str]) – A valid set of modifiers as accepted by Gtk.accelerator_parse(), none, an empty string, or None.

• mappings (Dict[str, str]) – A dict mapping accelerator strings to command names.

• commands (CommandRegistry) – The command registry used to map command names to functions.

• winman (WindowManager) – The interface commands should use to take action.

Return type:

Optional[KeyBinder]

Returns:

An instance of KeyBinder or None if winman didn’t already have an X connection and attempting to open a new one met with failure.