docs » hs.window.layout

WARNING: EXPERIMENTAL MODULE. DO NOT USE IN PRODUCTION. This module is for testing purposes only. It can undergo breaking API changes or go away entirely at any point and without notice. (Should you encounter any issues, please feel free to report them on https://github.com/Hammerspoon/hammerspoon/issues or #hammerspoon on irc.libera.chat)

Window management

Windowlayouts work by selecting certain windows via windowfilters and arranging them onscreen according to specific rules.

A layout is composed of a list of rules and, optionally, a screen arrangement definition. Rules within a layout are evaluated in order; once a window is acted upon by a rule, subsequent rules will not affect it further. A rule needs a windowfilter, producing a dynamic list of windows (the "window pool") to which the rule is applied, and a list of commands, evaluated in order. A command acts on one or more of the windows, and is composed of:

You should place higher-priority rules (with highly specialized windowfilters) first, and "fallback" rules (with more generic windowfilters) last; similarly, within a rule, you should have commands for the more "important" (i.e. relevant to your current workflow) windows first (move, maximize...) and after that deal with less prominent windows, if any remain, e.g. by placing them out of the way (minimize). unhide and hide, if used, should usually go into their own rules (with a windowfilter that allows invisible windows for unhide) that come before other rules that deal with actual window placement - unlike the other actions, they don't "consume" windows making them unavailable for subsequent rules, as they act on applications.

In order to avoid dealing with deeply nested maps, you can define a layout in your scripts via a list, where each element (or row) denotes a rule; in turn every rule can be a simplified list of two elements:

Some command string examples:

and tiles the remaining windows onto the right side, keeping the most recently focused on top and to the left

and minimizes any other windows

Each layout can work in "passive" or "active" modes; passive layouts must be triggered manually (via hs.hotkey.bind(), hs.menubar, etc.) while active layouts continuously keep their rules enforced (see hs.window.layout:start() for more information); in general you should avoid having multiple active layouts targeting the same windows, as the results will be unpredictable (if such a situation is detected, you'll see an error in the Hammerspoon console); you can have multiple active layouts, but be careful to maintain a clear "separation of concerns" between their respective windowfilters.

Each layout can have an associated screen configuration; if so, the layout will only be valid while the current screen arrangement satisfies it; see hs.window.layout:setScreenConfiguration() for more information.

API Overview

API Documentation

Variables

applyDelay
Signature hs.window.layout.applyDelay
Type Variable
Description

When "active mode" windowlayouts apply a rule, they will pause briefly for this amount of time in seconds, to allow windows

Source extensions/window/window_layout.lua line 598
screensChangedDelay
Signature hs.window.layout.screensChangedDelay
Type Variable
Description

The number of seconds to wait, after a screen configuration change has been detected, before

Source extensions/window/window_layout.lua line 736

Functions

applyLayout
Signature hs.window.layout.applyLayout(rules)
Type Function
Description

Applies a layout

Parameters
  • rules - see hs.window.layout.new()
Returns
  • None
Notes
  • this is a convenience wrapper for "passive mode" use that creates, applies, and deletes a windowlayout object; do not use shared windowfilters in rules, as they'll be deleted; you can just use constructor argument maps instead
Source extensions/window/window_layout.lua line 871
pauseAllInstances
Signature hs.window.layout.pauseAllInstances()
Type Function
Description

Pauses all active windowlayout instances

Parameters
  • None
Returns
  • None
Source extensions/window/window_layout.lua line 849
resumeAllInstances
Signature hs.window.layout.resumeAllInstances()
Type Function
Description

Resumes all active windowlayout instances

Parameters
  • None
Returns
  • None
Source extensions/window/window_layout.lua line 860

Constructors

new
Signature hs.window.layout.new(rules[,logname[,loglevel]]) -> hs.window.layout object
Type Constructor
Description

Creates a new hs.window.layout instance

Parameters
  • rules - a table containing the rules for this windowlayout (see the module description); additionally, if a special key screens is present, its value must be a valid screen configuration as per hs.window.layout:setScreenConfiguration()
  • logname - (optional) name of the hs.logger instance for the new windowlayout; if omitted, the class logger will be used
  • loglevel - (optional) log level for the hs.logger instance for the new windowlayout
Returns
  • a new windowlayout instance
Source extensions/window/window_layout.lua line 311

Methods

apply
Signature hs.window.layout:apply()
Type Method
Description

Applies the layout

Parameters
  • None
Returns
  • the hs.window.layout object
Notes
  • if a screen configuration is defined for this windowfilter, and currently not satisfied, this method will do nothing
Source extensions/window/window_layout.lua line 576
getRules
Signature hs.window.layout:getRules() -> table
Type Method
Description

Return a table with all the rules (and the screen configuration, if present) defined for this windowlayout

Parameters
  • None
Returns
  • a table containing the rules of this windowlayout; you can pass this table (optionally after performing valid manipulations) to hs.window.layout.new()
Source extensions/window/window_layout.lua line 342
pause
Signature hs.window.layout:pause() -> hs.window.layout object
Type Method
Description

Pauses an active windowlayout instance; while paused no automatic window management will occur

Parameters
  • None
Returns
  • the hs.window.layout object
Source extensions/window/window_layout.lua line 683
resume
Signature hs.window.layout:resume() -> hs.window.layout object
Type Method
Description

Resumes an active windowlayout instance after it was paused

Parameters
  • None
Returns
  • the hs.window.layout object
Notes
  • if a screen configuration is defined for this windowfilter, and currently not satisfied, this method will do nothing
Source extensions/window/window_layout.lua line 641
setScreenConfiguration
Signature hs.window.layout:setScreenConfiguration(screens) -> hs.window.layout object
Type Method
Description

Determines the screen configuration that permits applying this windowlayout

Parameters
  • screens - a map, where each key must be a valid "hint" for hs.screen.find(), and the corresponding value can be:
    • true - the screen must be currently present (attached and enabled)
    • false - the screen must be currently absent
    • an hs.geometry point (or constructor argument) - the screen must be present and in this specific position in the current arrangement (as per hs.screen:position())
Returns
  • the hs.window.layout object
Notes
  • If screens is nil, any previous screen configuration is removed, and this windowlayout will be always allowed
  • For "active" windowlayouts, call this method before calling hs.window.layout:start()
  • By using hs.geometry size objects as hints you can define separate layouts for the same physical screen at different resolutions
  • With this method you can define different windowlayouts for different screen configurations (as per System Preferences->Displays->Arrangement).
  • For example, suppose you define two "graphics design work" windowlayouts, one for "desk with dual monitors" and one for "laptop only mode":
    • "passive mode" use: you call :apply() on both on your chosen hotkey (via hs.hotkey:bind()), but only the appropriate layout for the current arrangement will be applied
    • "active mode" use: you just call :start() on both windowlayouts; as you switch between workplaces (by attaching or detaching external screens) the correct layout "kicks in" automatically - this is in effect a convenience wrapper that calls :pause() on the no longer relevant layout, and :resume() on the appropriate one, at every screen configuration change
Examples
Source extensions/window/window_layout.lua line 792
start
Signature hs.window.layout:start() -> hs.window.layout object
Type Method
Description

Puts a windowlayout instance in "active mode"

Parameters
  • None
Returns
  • the hs.window.layout object
Notes
  • If a screen configuration is defined for this windowfilter, and currently not satisfied, this windowfilter will be put in "active mode" but will remain paused until the screen configuration requirements are met
  • When in active mode, a windowlayout instance will constantly monitor the windowfilters for its rules, by subscribing to all the relevant events. As soon as any change is detected (e.g. when you drag a window, switch focus, open or close apps/windows, etc.) the relative rule will be automatically re-applied. In other words, the rules you defined will remain enforced all the time, instead of waiting for manual intervention via hs.window.layout:apply().
Source extensions/window/window_layout.lua line 620
stop
Signature hs.window.layout:stop() -> hs.window.layout object
Type Method
Description

Stops a windowlayout instance (i.e. not in "active mode" anymore)

Parameters
  • None
Returns
  • the hs.window.layout object
Source extensions/window/window_layout.lua line 705