# hs.grid

Move/resize windows within a grid

The grid partitions your screens for the purposes of window management. The default layout of the grid is 3 columns by 3 rows. You can specify different grid layouts for different screens and/or screen resolutions.

Windows that are aligned with the grid have their location and size described as a cell. Each cell is an hs.geometry rect with these fields:

  • x - The column of the left edge of the window
  • y - The row of the top edge of the window
  • w - The number of columns the window occupies
  • h - The number of rows the window occupies

For a grid of 3x3:

  • a cell '0,0 1x1' will be in the upper-left corner
  • a cell '2,0 1x1' will be in the upper-right corner
  • and so on...

Additionally, a modal keyboard driven interface for interactive resizing is provided via hs.grid.show(); The grid will be overlaid on the focused or frontmost window's screen with keyboard hints. To resize/move the window, you can select the corner cells of the desired position. For a move-only, you can select a cell and confirm with 'return'. The selected cell will become the new upper-left of the window. You can also use the arrow keys to move the window onto adjacent screens, and the tab/shift-tab keys to cycle to the next/previous window. Once you selected a cell, you can use the arrow keys to navigate through the grid. In this case, the grid will highlight the selected cells. After highlighting enough cells, press enter to move/resize the window to the highlighted area.

# API Overview

Variables - Configurable values

  • HINTS
  • ui

Functions - API calls offered directly by the extension

  • adjustWindow
  • get
  • getCell
  • getGrid
  • getGridFrame
  • hide
  • maximizeWindow
  • pushWindowDown
  • pushWindowLeft
  • pushWindowRight
  • pushWindowUp
  • resizeWindowShorter
  • resizeWindowTaller
  • resizeWindowThinner
  • resizeWindowWider
  • set
  • setGrid
  • setMargins
  • show
  • snap
  • toggleShow

# API Documentation

# Variables

# HINTS

Signature hs.grid.HINTS
Type Variable
Description A bidimensional array (table of tables of strings) holding the keyboard hints (as per hs.keycodes.map) to be used for the interactive resizing interface.
Notes
  • hs.inspect(hs.grid.HINTS) from the console will show you how the table is built
  • hs.grid.show()
  • When displaying interactive grid, if gird dimensions (hs.grid.setGrid()) are greater than HINTS dimensions,
  • then Hammerspoon merges few cells such that interactive grid dimensions do not exceed HINTS dimensions.
  • This is done to make sure interactive grid cells do not run out of hints. The interactive grid ends up with
  • cells of varying height and width.
  • The actual grid is not affected. If you use API methods like hs.grid.pushWindowDown(), you will not face this
  • issue at all.
  • If you have a grid of higher dimensions and require an interactive gird that accurately models underlying grid
  • then set HINTS variable to a table that has same dimensions as your grid.
  • Following is an example of grid that has 16 columns
  • </li><li>hs.grid.setGrid('16x4')</li><li>hs.grid.HINTS={</li><li> {'f1', 'f2' , 'f3' , 'f4' , 'f5', 'f6', 'f7', 'f8', 'f9', 'f10', 'f11', 'f12', 'f13', 'f14', 'f15', 'f16'},</li><li> {'1' , 'f11', 'f15', 'f19', 'f3', '=' , ']' , '2' , '3' , '4' , '5' , '6' , '7' , '8' , '9' , '0' },</li><li> {'Q' , 'f12', 'f16', 'f20', 'f4', '-' , '[' , 'W' , 'E' , 'R' , 'T' , 'Y' , 'U' , 'I' , 'O' , 'P' },</li><li> {'A' , 'f13', 'f17', 'f1' , 'f5', 'f7', '\\', 'S' , 'D' , 'F' , 'G' , 'H' , 'J' , 'K' , 'L' , ',' },</li><li> {'X' , 'f14', 'f18', 'f2' , 'f6', 'f8', ';' , '/' , '.' , 'Z' , 'X' , 'C' , 'V' , 'B' , 'N' , 'M' }</li><li>}</li><li>
Source extensions/grid/grid.lua line 601

# ui

Signature hs.grid.ui
Type Variable
Description Allows customization of the modal resizing grid user interface
Notes None
Source extensions/grid/grid.lua line 650

# Functions

# adjustWindow

Signature hs.grid.adjustWindow(fn, window) -> hs.grid
Type Function
Description Calls a user specified function to adjust a window's cell
Parameters
  • fn - a function that accepts a cell object as its only argument. The function should modify it as needed and return nothing
  • window - an hs.window object to act on; if omitted, the focused or frontmost window will be used
Returns
  • the hs.grid module for method chaining
Notes None
Examples None
Source extensions/grid/grid.lua line 372

# get

Signature hs.grid.get(win) -> cell
Type Function
Description Gets the cell describing a window
Parameters
  • an hs.window object to get the cell of
Returns
  • a cell object (i.e. an hs.geometry rect), or nil if an error occurred
Notes None
Examples None
Source extensions/grid/grid.lua line 243

# getCell

Signature hs.grid.getCell(cell, screen) -> hs.geometry
Type Function
Description Gets the hs.geometry rect for a cell on a particular screen
Parameters
  • cell - a cell object, i.e. an hs.geometry rect or argument to construct one
  • screen - an hs.screen object or argument to hs.screen.find() where the cell is located
Returns
  • the hs.geometry rect for a cell on a particular screen or nil if the screen isn't found
Notes None
Examples None
Source extensions/grid/grid.lua line 266

# getGrid

Signature hs.grid.getGrid(screen) -> hs.geometry size
Type Function
Description Gets the defined grid size for a given screen or screen resolution
Parameters
  • screen - an hs.screen object, or a valid argument to hs.screen.find(), indicating the screen to get the grid of; if omitted or nil, gets the default grid, which is used when no specific grid is found for any given screen/resolution
Returns
  • an hs.geometry size object indicating the number of columns and rows in the grid
Notes
  • if a grid was not set for the specified screen or geometry, the default grid will be returned
  • Usage:
  • local mygrid = hs.grid.getGrid('1920x1080') -- gets the defined grid for all screens with a 1920x1080 resolution
  • local defgrid=hs.grid.getGrid() defgrid.w=defgrid.w+2 -- increases the number of columns in the default grid by 2
Examples None
Source extensions/grid/grid.lua line 117

# getGridFrame

Signature hs.grid.getGridFrame(screen) -> hs.geometry rect
Type Function
Description Gets the defined grid frame for a given screen or screen resolution.
Parameters
  • screen - an hs.screen object, or a valid argument to hs.screen.find(), indicating the screen to get the grid frame of
Returns
  • an hs.geometry rect object indicating the frame used by the grid for the given screen; if no custom frame
  • was given via hs.grid.setGrid(), returns the screen's frame
Notes None
Examples None
Source extensions/grid/grid.lua line 154

# hide

Signature hs.grid.hide()
Type Function
Description Hides the grid, if visible, and exits the modal resizing mode.
Parameters
  • None
Returns
  • None
Notes
  • Call this function if you need to make sure the modal is exited without waiting for the user to press esc.
  • If an exit callback was provided when invoking the modal interface, calling .hide() will call it
Examples None
Source extensions/grid/grid.lua line 207

# maximizeWindow

Signature hs.grid.maximizeWindow(window) -> hs.grid
Type Function
Description Moves and resizes a window to fill the entire grid
Parameters
  • window - an hs.window object to act on; if omitted, the focused or frontmost window will be used
Returns
  • the hs.grid module for method chaining
Notes None
Examples None
Source extensions/grid/grid.lua line 400

# pushWindowDown

Signature hs.grid.pushWindowDown(window) -> hs.grid
Type Function
Description Moves a window one grid cell down the screen, or onto the adjacent screen's grid when necessary
Parameters
  • window - an hs.window object to act on; if omitted, the focused or frontmost window will be used
Returns
  • the hs.grid module for method chaining
Notes None
Examples None
Source extensions/grid/grid.lua line 515

# pushWindowLeft

Signature hs.grid.pushWindowLeft(window) -> hs.grid
Type Function
Description Moves a window one grid cell to the left, or onto the adjacent screen's grid when necessary
Parameters
  • window - an hs.window object to act on; if omitted, the focused or frontmost window will be used
Returns
  • the hs.grid module for method chaining
Notes None
Examples None
Source extensions/grid/grid.lua line 430

# pushWindowRight

Signature hs.grid.pushWindowRight(window) -> hs.grid
Type Function
Description Moves a window one cell to the right, or onto the adjacent screen's grid when necessary
Parameters
  • window - an hs.window object to act on; if omitted, the focused or frontmost window will be used
Returns
  • the hs.grid module for method chaining
Notes None
Examples None
Source extensions/grid/grid.lua line 454

# pushWindowUp

Signature hs.grid.pushWindowUp(window) -> hs.grid
Type Function
Description Moves a window one grid cell up the screen, or onto the adjacent screen's grid when necessary
Parameters
  • window - an hs.window object to act on; if omitted, the focused or frontmost window will be used
Returns
  • the hs.grid module for method chaining
Notes None
Examples None
Source extensions/grid/grid.lua line 540

# resizeWindowShorter

Signature hs.grid.resizeWindowShorter(window) -> hs.grid
Type Function
Description Resizes a window so its bottom edge moves one grid cell higher
Parameters
  • window - an hs.window object to act on; if omitted, the focused or frontmost window will be used
Returns
  • the hs.grid module for method chaining
Notes None
Examples None
Source extensions/grid/grid.lua line 564

# resizeWindowTaller

Signature hs.grid.resizeWindowTaller(window) -> hs.grid
Type Function
Description Resizes a window so its bottom edge moves one grid cell lower
Parameters
  • window - an hs.window object to act on; if omitted, the focused or frontmost window will be used
Returns
  • the hs.grid module for method chaining
Notes
  • if the window hits the bottom edge of the screen and is asked to become taller, its top edge will shift further up
Examples None
Source extensions/grid/grid.lua line 577

# resizeWindowThinner

Signature hs.grid.resizeWindowThinner(window) -> hs.grid
Type Function
Description Resizes a window to be one cell thinner
Parameters
  • window - an hs.window object to act on; if omitted, the focused or frontmost window will be used
Returns
  • the hs.grid module for method chaining
Notes None
Examples None
Source extensions/grid/grid.lua line 502

# resizeWindowWider

Signature hs.grid.resizeWindowWider(window) -> hs.grid
Type Function
Description Resizes a window to be one cell wider
Parameters
  • window - an hs.window object to act on; if omitted, the focused or frontmost window will be used
Returns
  • the hs.grid module for method chaining
Notes
  • if the window hits the right edge of the screen and is asked to become wider, its left edge will shift further left
Examples None
Source extensions/grid/grid.lua line 479

# set

Signature hs.grid.set(win, cell, screen) -> hs.grid
Type Function
Description Sets the cell for a window on a particular screen
Parameters
  • win - an hs.window object representing the window to operate on
  • cell - a cell object, i.e. an hs.geometry rect or argument to construct one, to apply to the window
  • screen - (optional) an hs.screen object or argument to hs.screen.find() representing the screen to place the window on; if omitted the window's current screen will be used
Returns
  • the hs.grid module for method chaining
Notes None
Examples None
Source extensions/grid/grid.lua line 295

# setGrid

Signature hs.grid.setGrid(grid,screen,frame) -> hs.grid
Type Function
Description Sets the grid size for a given screen or screen resolution
Parameters
  • grid - an hs.geometry size, or argument to construct one, indicating the number of columns and rows for the grid
  • screen - an hs.screen object, or a valid argument to hs.screen.find(), indicating the screen(s) to apply the grid to; if omitted or nil, sets the default grid, which is used when no specific grid is found for any given screen/resolution
  • frame - an hs.geometry rect object indicating the frame that the grid will occupy for the given screen; if omitted or nil, the screen's :frame() will be used; use this argument if you want e.g. to leave a strip of the desktop unoccluded when using GeekTool or similar. The screen argument must be non-nil when setting a custom grid frame.
Returns
  • the hs.grid module for method chaining
Notes None
Examples
  • hs.grid.setGrid('5x3','Color LCD') -- sets the grid to 5x3 for any screen named "Color LCD"
  • hs.grid.setGrid('8x5','1920x1080') -- sets the grid to 8x5 for all screens with a 1920x1080 resolution
  • hs.grid.setGrid'4x4' -- sets the default grid to 4x4
Source extensions/grid/grid.lua line 48

# setMargins

Signature hs.grid.setMargins(margins) -> hs.grid
Type Function
Description Sets the margins between windows
Parameters
  • margins - an hs.geometry point or size, or argument to construct one, indicating the desired margins between windows in screen points
Returns
  • the hs.grid module for method chaining
Notes None
Examples None
Source extensions/grid/grid.lua line 98

# show

Signature hs.grid.show([exitedCallback][, multipleWindows])
Type Function
Description Shows the grid and starts the modal interactive resizing process for the focused or frontmost window.
Parameters
  • exitedCallback - (optional) a function that will be called after the user dismisses the modal interface
  • multipleWindows - (optional) if true, the resizing grid won't automatically go away after selecting the desired cells for the frontmost window; instead, it'll switch to the next window
Returns
  • None
Notes
  • In most cases this function should be invoked via hs.hotkey.bind with some keyboard shortcut.
  • In the modal interface, press the arrow keys to jump to adjacent screens; spacebar to maximize/unmaximize; esc to quit without any effect
  • Pressing tab or shift-tab in the modal interface will cycle to the next or previous window; if multipleWindows
  • is false or omitted, the first press will just enable the multiple windows behaviour
  • The keyboard hints assume a QWERTY layout; if you use a different layout, change hs.grid.HINTS accordingly
  • If grid dimensions are greater than 10x10 then you may have to change hs.grid.HINTS depending on your
  • requirements. See note in HINTS.
Examples None
Source extensions/grid/grid.lua line 187

# snap

Signature hs.grid.snap(win) -> hs.grid
Type Function
Description Snaps a window into alignment with the nearest grid lines
Parameters
  • win - an hs.window object to snap
Returns
  • the hs.grid module for method chaining
Notes None
Examples None
Source extensions/grid/grid.lua line 353

# toggleShow

Signature hs.grid.toggleShow([exitedCallback][, multipleWindows])
Type Function
Description Toggles the grid and modal resizing mode - see hs.grid.show() and hs.grid.hide()
Parameters
  • exitedCallback - (optional) a function that will be called after the user dismisses the modal interface
  • multipleWindows - (optional) if true, the resizing grid won't automatically go away after selecting the desired cells for the frontmost window; instead, it'll switch to the next window
Returns
  • None
Notes None
Examples None
Source extensions/grid/grid.lua line 221

© Copyright 2024 LateNite Films Pty Ltd. All rights reserved.