docs » hs.window.layout

When "active mode" windowlayouts apply a rule, they will pause briefly for this amount of time in seconds, to allow windows to "settle" in their new configuration without triggering other rules (or the same rule), which could result in a cascade (or worse, a loop) or rules being applied. Defaults to 1; increase this if you experience unwanted repeated triggering of rules due to sluggish performance.

The number of seconds to wait, after a screen configuration change has been detected, before resuming any active windowlayouts that are allowed in the new configuration; defaults to 10, to give sufficient time to OSX to do its own housekeeping

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

Pauses all active windowlayout instances

Parameters:

• None

Returns:

• None

Resumes all active windowlayout instances

Parameters:

• None

Returns:

• None

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

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

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

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

Parameters:

• None

Returns:

• the hs.window.layout object

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

Determines the screen configuration that permits applying this windowlayout

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

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

Usage:

local laptop_layout,desk_layout=... -- define your layouts
-- just the laptop screen:
laptop_layout:setScreenConfiguration{['Color LCD']='0,0',dell=false,['3840x2160']=false}:start()
-- attached to a 4k primary + a Dell on the right:
desk_layout:setScreenConfiguration{['3840x2160']='0,0',['dell']='1,0',['Color LCD']='-1,0'}:start()
-- as above, but in clamshell mode (laptop lid closed):
clamshell_layout:setScreenConfiguration{['3840x2160']='0,0',['dell']='1,0',['Color LCD']=false}:start()

Puts a windowlayout instance in "active mode"

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

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

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

Parameters:

• None

Returns:

• the hs.window.layout object