docs » WindowSigils

Assign every window and empty rectangle a sigil for quick access.

A letter or digit is rendered in the titlebar of every window (or empty space), and actions can be bound inside the sigil mode and triggered with different modifiers.

For example, with no modifiers, a sigil key can focus the window. If the 'enter' action is bound to control-w, then 'control-w c' will focus the window with sigil 'c'. The action is a function which accepts a window, or in the case of an empty space, a window-like object which reponds to 'id', 'frame', and 'setFrame'.

The keys 'h', 'j', 'k', and 'l' are reserved for the window west, south, north, and east of the currently focused window in standard Vi-like fashion, and so are not assigned as sigils.

By default, two keys (other than the sigils) are bound in the mode: escape leaves the mode without doing anything, and '.' sends the sigil key to the focused window. This allows sending 'control-w' to the underlying window by typing 'control-w .'.

Download: https://github.com/Hammerspoon/Spoons/raw/master/Spoons/WindowSigils.spoon.zip

Usage example:

local function ignore_notification()
  -- ...
end
local function paste_as_keystrokes()
  hs.eventtap.keyStrokes(hs.pasteboard.readString())
end
local function rerun_last_command()
  hs.execute("kitty @ --to unix:/Users/jfelice/.run/kitty send-text --match=title:kak_repl_window '\x10\x0d'", true)
end

local function focus_window(window)
  window:focus()
  if hs.window.focusedWindow() ~= window then
    -- Some cases with apps having windows on multiple monitors require
    -- us to try again (?)
    window:focus()
  end
end

local function swap_window(window)
  local focused_frame = hs.window.focusedWindow():frame()
  local selected_frame = window:frame()
  hs.window.focusedWindow():setFrame(selected_frame, 0)
  window:setFrame(focused_frame, 0)
end

local function stack_window(window)
  local frame = window:frame()
  hs.window.focusedWindow():setFrame(frame, 0)
end

sigils = hs.loadSpoon("WindowSigils")
sigils:configure({
  hotkeys = {
    enter = {{"control"}, "W"}
  },
  mode_keys = {
    [{{'shift'}, 'i'}] = ignore_notification,
    [{{}, 'v'}]        = paste_as_keystrokes,
    [{{}, ','}]        = rerun_last_command,
  },
  sigil_actions = {
    [{}]       = focus_window,
    [{'ctrl'}] = stack_window,
    [{'alt'}]  = swap_window,
  }
})
sigils:start()