Keybindings

YASB supports global keyboard shortcuts (hotkeys) to trigger widget actions. Keybindings are configured per-widget in the widget's options section. This feature uses native Windows low-level keyboard hooks and requires no third-party dependencies.

Overview

Per-widget instance: Keybindings are tied to the specific widget name in your config (e.g., clock vs clock_2)
Multiple keybindings: A single widget can have multiple keybindings for different actions
Screen-aware: Hotkeys trigger the widget on the currently focused screen
Zero overhead: If no keybindings are defined, no hotkey listener is started

Configuration

Add a keybindings list to any widget's options. Each keybinding requires:

keys: The key combination (e.g., "win+c", "ctrl+shift+f1")
action: The callback action to trigger (e.g., "toggle_calendar", "toggle_label")

Basic Example

clock:
  type: "yasb.clock.ClockWidget"
  options:
    label: "{%H:%M}"
    keybindings:

      - keys: "win+c"
        action: "toggle_calendar"

      - keys: "ctrl+shift+t"
        action: "toggle_label"

Multiple Widgets Example

clock:
  type: "yasb.clock.ClockWidget"
  options:
    keybindings:

      - keys: "win+c"
        action: "toggle_calendar"

volume:
  type: "yasb.volume.VolumeWidget"
  options:
    keybindings:

      - keys: "win+v"
        action: "toggle_menu"

Supported Keys

Modifier Keys

Key Name	Description
`win`, `windows`, `super`, `meta`	Either Windows key (left or right)
`lwin`, `leftwin`, `left_win`	Left Windows key only
`rwin`, `rightwin`, `right_win`	Right Windows key only
`alt`	Either Alt key (left or right)
`lalt`, `leftalt`, `left_alt`	Left Alt key only
`ralt`, `rightalt`, `right_alt`	Right Alt key only
`ctrl`, `control`	Either Control key (left or right)
`lctrl`, `leftctrl`, `left_ctrl`	Left Control key only
`rctrl`, `rightctrl`, `right_ctrl`	Right Control key only
`shift`	Shift key

Function Keys

Key Name	Description
`f1` - `f24`	Function keys F1 through F24

Letter and Number Keys

Key Name	Description
`a` - `z`	Letter keys (case-insensitive)
`0` - `9`	Number keys

Special Keys

Key Name	Aliases	Description
`space`		Spacebar
`tab`		Tab key
`enter`, `return`		Enter/Return key
`esc`, `escape`		Escape key
`backspace`		Backspace key
`delete`, `del`		Delete key
`insert`, `ins`		Insert key
`home`		Home key
`end`		End key
`pageup`, `pgup`		Page Up key
`pagedown`, `pgdn`		Page Down key
`pause`		Pause key
`capslock`, `caps`		Caps Lock key
`numlock`		Num Lock key
`scrolllock`		Scroll Lock key
`printscreen`, `prtsc`		Print Screen key

Arrow Keys

Key Name	Description
`left`	Left arrow
`up`	Up arrow
`right`	Right arrow
`down`	Down arrow

Numpad Keys

Key Name	Description
`numpad0` - `numpad9`	Numpad number keys
`multiply`	Numpad *
`add`	Numpad +
`subtract`	Numpad -
`decimal`	Numpad .
`divide`	Numpad /

Punctuation and Symbol Keys

Key Name	Description
`semicolon`	; key
`equal`, `equals`	= key
`comma`	, key
`minus`	- key
`period`	. key
`slash`	/ key
`backquote`, `grave`	` key
`bracketleft`	[ key
`bracketright`	] key
`backslash`	\ key
`quote`	' key

Win Key Specificity

YASB supports distinguishing between the left and right Windows keys:

Configuration	Behavior
`"win+c"`	Triggered by either left or right Win key + C
`"lwin+c"`	Triggered only by left Win key + C
`"rwin+c"`	Triggered only by right Win key + C

Example: Different Actions for Left/Right Win

clock:
  type: "yasb.clock.ClockWidget"
  options:
    keybindings:

      - keys: "lwin+c"
        action: "toggle_calendar"

      - keys: "rwin+c"
        action: "toggle_label"

Alt/Ctrl Key Specificity

Similarly, you can distinguish between left and right Alt or Ctrl keys:

Configuration	Behavior
`"alt+x"`	Triggered by either left or right Alt key + X
`"lalt+x"`	Triggered only by left Alt key + X
`"ralt+x"`	Triggered only by right Alt key + X
`"ctrl+x"`	Triggered by either left or right Ctrl key + X
`"lctrl+x"`	Triggered only by left Ctrl key + X
`"rctrl+x"`	Triggered only by right Ctrl key + X

Example: Left Alt vs Right Alt

volume:
  type: "yasb.volume.VolumeWidget"
  options:
    keybindings:

      - keys: "lalt+v"
        action: "toggle_menu"

      - keys: "ralt+v"
        action: "toggle_mute"

Extra Modifier Rejection

YASB uses exact modifier matching. If you register alt+x, pressing ctrl+alt+x will not trigger it because Ctrl is an extra modifier that wasn't specified.

Registered	User Presses	Result
`alt+x`	Alt + X	Triggers
`alt+x`	Ctrl + Alt + X	Blocked (extra Ctrl)
`ctrl+alt+x`	Ctrl + Alt + X	Triggers
`ctrl+alt+x`	Ctrl + Alt + Shift + X	Blocked (extra Shift)

This prevents accidental triggers when using similar hotkeys in other applications.

Limitations

No Multi-Key Combos

YASB only supports modifier + single key combinations. You cannot bind multiple non-modifier keys together:

Configuration	Valid
`"alt+a"`	Yes
`"ctrl+shift+f1"`	Yes
`"a+b"`	No - two non-modifier keys
`"ctrl+a+b"`	No - two non-modifier keys

Modifier-Only Hotkeys Not Supported

You cannot use a modifier key alone as a hotkey:

Configuration	Valid
`"ctrl"`	No - no main key
`"alt+shift"`	No - no main key
`"win+a"`	Yes

Press Order Matters

Hotkeys are triggered when the main key is pressed while modifiers are held. This means:

Hold Alt, then press X → Triggers alt+x
Hold X, then press Alt → Does NOT trigger alt+x

This is standard behavior for all hotkey systems (Windows RegisterHotKey, AutoHotkey, etc.).

Available Actions

Each widget has its own set of available callback actions. Common actions include:

Action	Description
`toggle_label`	Toggle between primary and alternate label
`toggle_menu`	Show/hide the widget's menu
`update_label`	Force refresh the widget label
`do_nothing`	No action (useful for disabling)

Refer to individual widget documentation for widget-specific actions. For example, the Clock widget supports:

toggle_calendar - Show/hide calendar popup
toggle_label - Toggle between label formats
next_timezone - Cycle to next timezone
context_menu - Show context menu

Screen Targeting

When a hotkey is triggered, YASB determines which screen's widget should respond based on:

The currently focused window's screen
If no window is focused, falls back to the primary screen

This means pressing win+c will toggle the calendar on the monitor where you're currently working.

Conflict Handling

If the same key combination is assigned to multiple widgets, YASB will:

Log a warning message indicating the conflict
Use the last defined keybinding (later widgets override earlier ones)

WARNING: Hotkey conflict: 'win+c' is already assigned to 'yasb.clock.ClockWidget', 
overriding with 'yasb.volume.VolumeWidget'

To avoid conflicts, use unique key combinations for each widget action.

Troubleshooting

Hotkey Not Working

Check the logs: Enable debug logging to see if the hotkey is being registered
Verify key names: Ensure you're using supported key names from the tables above
Check for conflicts: Another application might be using the same hotkey
Elevated apps: If an elevated (admin) application has focus, hotkeys may not be captured due to Windows UIPI security. This is normal - hotkeys will work again once a non-elevated window has focus

Hotkey Conflicts with Windows

Some key combinations are reserved by Windows and may not work:

win+l (Lock screen)
ctrl+alt+del (Security options)

Consider using alternative combinations or disabling the Windows shortcuts via Group Policy if needed.

Keybinding Not in Config

If you don't define any keybindings in your widget options, the hotkey listener won't start at all. When keybindings are configured, the listener uses a low-level keyboard hook which has negligible overhead.