docs » hs.window.switcher

Window-based cmd-tab replacement

Usage:

-- set up your windowfilter
switcher = hs.window.switcher.new() -- default windowfilter: only visible windows, all Spaces
switcher_space = hs.window.switcher.new(hs.window.filter.new():setCurrentSpace(true):setDefaultFilter{}) -- include minimized/hidden windows, current Space only
switcher_browsers = hs.window.switcher.new{'Safari','Google Chrome'} -- specialized switcher for your dozens of browser windows :)

-- bind to hotkeys; WARNING: at least one modifier key is required!
hs.hotkey.bind('alt','tab','Next window',function()switcher:next()end)
hs.hotkey.bind('alt-shift','tab','Prev window',function()switcher:previous()end)

-- alternatively, call .nextWindow() or .previousWindow() directly (same as hs.window.switcher.new():next())
hs.hotkey.bind('alt','tab','Next window',hs.window.switcher.nextWindow)
-- you can also bind to `repeatFn` for faster traversing
hs.hotkey.bind('alt-shift','tab','Prev window',hs.window.switcher.previousWindow,nil,hs.window.switcher.previousWindow)

API Overview

API Documentation

Variables

ui
Signature hs.window.switcher.ui
Type Variable
Description

Allows customization of the switcher behaviour and user interface
Source extensions/window/window_switcher.lua line 53

Functions

nextWindow
Signature hs.window.switcher.nextWindow()
Type Function
Description

Shows the switcher (if not yet visible) and selects the next window
Parameters
  • None
Returns
  • None
Notes
  • the switcher will be dismissed (and the selected window focused) when all modifier keys are released
Source extensions/window/window_switcher.lua line 318
previousWindow
Signature hs.window.switcher.previousWindow()
Type Function
Description

Shows the switcher (if not yet visible) and selects the previous window
Parameters
  • None
Returns
  • None
Notes
  • the switcher will be dismissed (and the selected window focused) when all modifier keys are released
Source extensions/window/window_switcher.lua line 331

Constructors

new
Signature hs.window.switcher.new([windowfilter[, uiPrefs][, logname, [loglevel]]]) -> hs.window.switcher object
Type Constructor
Description

Creates a new switcher instance; it can use a windowfilter to determine which windows to show
Parameters
  • windowfilter - (optional) if omitted or nil, use the default windowfilter; otherwise it must be a windowfilter instance or constructor table
  • uiPrefs - (optional) a table to override UI preferences for this instance; its keys and values must follow the conventions described in hs.window.switcher.ui; this parameter allows you to have multiple switcher instances with different behaviour (for example, with and without thumbnails and/or titles) using different hotkeys
  • logname - (optional) name of the hs.logger instance for the new switcher; if omitted, the class logger will be used
  • loglevel - (optional) log level for the hs.logger instance for the new switcher
Returns
  • the new instance
Source extensions/window/window_switcher.lua line 393

Methods

next
Signature hs.window.switcher:next()
Type Method
Description

Shows the switcher instance (if not yet visible) and selects the next window
Parameters
  • None
Returns
  • None
Notes
  • the switcher will be dismissed (and the selected window focused) when all modifier keys are released
Source extensions/window/window_switcher.lua line 285
previous
Signature hs.window.switcher:previous()
Type Method
Description

Shows the switcher instance (if not yet visible) and selects the previous window
Parameters
  • None
Returns
  • None
Notes
  • the switcher will be dismissed (and the selected window focused) when all modifier keys are released
Source extensions/window/window_switcher.lua line 298