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()

API Overview

API Documentation

Variables

logger
Signature WindowSigils.logger
Type Variable
Description Logger object used within the Spoon. Can be accessed to set the default log level for the messages coming from the Spoon.
Source Source/WindowSigils.spoon/init.lua line 88

Methods

bindHotkeys
Signature WindowSigils:bindHotkeys(mapping)
Type Method
Description Binds hotkeys for WindowSigils
Parameters
  • mapping - A table containing hotkey objifier/key details for the following items:
    • enter - Enter the sigil mode
Returns
Source Source/WindowSigils.spoon/init.lua line 99
bindModeKey
Signature WindowSigils:bindModeKey(mods, key, action)
Type Method
Description Bind an extra action to be triggered by a key in the sigil mode.
Parameters
  • mods - The key modifiers
  • key - The key
  • action - A function, called with no parameters.
Returns
Source Source/WindowSigils.spoon/init.lua line 149
bindSigilAction
Signature WindowSigils:bindSigilAction(mods, action)
Type Method
Description Bind an action to be triggered in the sigil mode when a window's sigil key is pressed.
Parameters
  • mods - The modifiers which must be held to trigger this action.
  • action - A function which takes a window object and performs this action.
Returns
Source Source/WindowSigils.spoon/init.lua line 175
configure
Signature WindowSigils:configure(configuration)
Type Method
Description Configures the spoon.
Parameters
  • configuration - :
    • hotkeys
    • mode_keys - a table of key specs (e.g. {{'shift'}, 'n'}) to functions. The keys are mapped inside the sigil mode and the key is no longer used as a window sigil.
    • sigil_actions - a table of mod specs (e.g. {'alt'}) to functions. When the sigil is used in the sigil mode with the specified modifier pressed, the function is invoked with a window object.
Returns
Source Source/WindowSigils.spoon/init.lua line 120
orderedWindows
Signature WindowSigils:orderedWindows()
Type Method
Description A list of windows, in the order sigils are assigned.
Parameters
  • None
Returns
Source Source/WindowSigils.spoon/init.lua line 279
refresh
Signature WindowSigils:refresh()
Type Method
Description Rerender all window sigils.
Parameters
  • None
Returns
Source Source/WindowSigils.spoon/init.lua line 411
start
Signature WindowSigils:start()
Type Method
Description Starts rendering the sigils and handling hotkeys
Parameters
  • None
Returns
Source Source/WindowSigils.spoon/init.lua line 200
stop
Signature WindowSigils:stop()
Type Method
Description Stops rendering the sigils and handling hotkeys
Parameters
  • None
Returns
Source Source/WindowSigils.spoon/init.lua line 237
window
Signature WindowSigils:window(sigil)
Type Method
Description Find the window with the given index or sigil.
Parameters
  • sigil - If a number, the index of the window; if a string, the sigil of the window. Can also be 'North', 'East', 'South', or 'West' to find a window related to the currently focused window.
Returns
Source Source/WindowSigils.spoon/init.lua line 302