docs » hs.grid

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.

• 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

hs.grid.setGrid('16x4')
hs.grid.HINTS={
    {'f1', 'f2' , 'f3' , 'f4' , 'f5', 'f6', 'f7', 'f8', 'f9', 'f10', 'f11', 'f12', 'f13', 'f14', 'f15', 'f16'},
    {'1' , 'f11', 'f15', 'f19', 'f3', '=' , ']' , '2' , '3' , '4'  , '5'  , '6'  , '7'  , '8'  , '9'  , '0'  },
    {'Q' , 'f12', 'f16', 'f20', 'f4', '-' , '[' , 'W' , 'E' , 'R'  , 'T'  , 'Y'  , 'U'  , 'I'  , 'O'  , 'P'  },
    {'A' , 'f13', 'f17', 'f1' , 'f5', 'f7', '\\', 'S' , 'D' , 'F'  , 'G'  , 'H'  , 'J'  , 'K'  , 'L'  , ','  },
    {'X' , 'f14', 'f18', 'f2' , 'f6', 'f8', ';' , '/' , '.' , 'Z'  , 'X'  , 'C'  , 'V'  , 'B'  , 'N'  , 'M'  }
}

Allows customization of the modal resizing grid user interface

Calls a user specified function to adjust a window's cell

• 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

• the hs.grid module for method chaining

Gets the cell describing a window

• an hs.window object to get the cell of

• a cell object (i.e. an hs.geometry rect), or nil if an error occurred

Gets the hs.geometry rect for a cell on a particular screen

• 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

• the hs.geometry rect for a cell on a particular screen or nil if the screen isn't found

Gets the defined grid size for a given screen or screen resolution

• 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

• an hs.geometry size object indicating the number of columns and rows in the grid

• 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

Gets the defined grid frame for a given screen or screen resolution.

• screen - an hs.screen object, or a valid argument to hs.screen.find(), indicating the screen to get the grid frame of

• 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

Hides the grid, if visible, and exits the modal resizing mode.

• None

• None

• 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

Moves and resizes a window to fill the entire grid

• window - an hs.window object to act on; if omitted, the focused or frontmost window will be used

• the hs.grid module for method chaining

Moves a window one grid cell down the screen, or onto the adjacent screen's grid when necessary

• window - an hs.window object to act on; if omitted, the focused or frontmost window will be used

• the hs.grid module for method chaining

Moves a window one grid cell to the left, or onto the adjacent screen's grid when necessary

• window - an hs.window object to act on; if omitted, the focused or frontmost window will be used

• the hs.grid module for method chaining

Moves a window one cell to the right, or onto the adjacent screen's grid when necessary

• window - an hs.window object to act on; if omitted, the focused or frontmost window will be used

• the hs.grid module for method chaining

Moves a window one grid cell up the screen, or onto the adjacent screen's grid when necessary

• window - an hs.window object to act on; if omitted, the focused or frontmost window will be used

• the hs.grid module for method chaining

Resizes a window so its bottom edge moves one grid cell higher

• window - an hs.window object to act on; if omitted, the focused or frontmost window will be used

• the hs.grid module for method chaining

Resizes a window so its bottom edge moves one grid cell lower

• window - an hs.window object to act on; if omitted, the focused or frontmost window will be used

• the hs.grid module for method chaining

• if the window hits the bottom edge of the screen and is asked to become taller, its top edge will shift further up

Resizes a window to be one cell thinner

• window - an hs.window object to act on; if omitted, the focused or frontmost window will be used

• the hs.grid module for method chaining

Resizes a window to be one cell wider

• window - an hs.window object to act on; if omitted, the focused or frontmost window will be used

• the hs.grid module for method chaining

• if the window hits the right edge of the screen and is asked to become wider, its left edge will shift further left

Sets the cell for a window on a particular screen

• 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

• the hs.grid module for method chaining

Sets the grid size for a given screen or screen resolution

• 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.

• the hs.grid module for method chaining

Sets the margins between windows

• margins - an hs.geometry point or size, or argument to construct one, indicating the desired margins between windows in screen points

• the hs.grid module for method chaining

Shows the grid and starts the modal interactive resizing process for the focused or frontmost window.

• 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

• None

• 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.

Snaps a window into alignment with the nearest grid lines

• win - an hs.window object to snap

• the hs.grid module for method chaining

Toggles the grid and modal resizing mode - see hs.grid.show() and hs.grid.hide()

• 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

• None