Operations

This page describes Slate operations.

The Operation Object
Free Form Operations
move
resize
push
nudge
throw
corner
shell
hide
show
toggle
focus
chain
sequence
layout
snapshot
delete-snapshot
activate-snapshot
hint
grid
relaunch
undo
switch

The Operation Object

Using the method slate.operation will return an Operation object. This object can be used as a reference in other operations or APIs.

Basic Example

var hide = slate.operation("hide", { "app" : "all" });
slate.bind("pad2:ctrl", hide);

Will bind pad2+ctrl to the hide operation.

Functions

`run`

Run the operation. If the operation is performed on a window, it will be performed on the currently focused window.

var hide = slate.operation("hide", { "app" : "all" });
slate.bind("pad1:ctrl", function() { slate.log("hello"); hide.run(); });

Will bind pad1+ctrl to display "hello" to the OS X debug log and then run the hide operation.

`dup`

Duplicate the operation overriding the given parameters (keeping the parameters that are not given the same as the operation).

var cornerTopLeft = slate.operation("corner", {
  "direction" : "top-left",
  "width" : "screenSizeX/2",
  "height" : "screenSizeY/2"
});
var cornerTopRight = cornerTopLeft.dup({ "direction" : "top-right" });
slate.bind("1:ctrl", cornerTopLeft);
slate.bind("2:ctrl", cornerTopRight);

Will bind 1+ctrl to move the currently focused window into the top-left corner and resize it to a quarter of the screen. This will also bind 2+ctrl to move the currently focused window into the top-right corner and resize it to a quarter of the screen.

Free Form Operations

Run a JavaScript Function

This is not technically an operation, but you can bind a JavaScript function to a keystroke. The function will have one parameter: the currently focused window object.

slate.bind(keystroke, function(windowObject) {
  // do something with windowObject
});

windowObject - the currently focused window object.

Available Configs

Global configs only. No Operation specific configs available.

`move`

Move/Resize the window any which way

var move = slate.operation("move", {
  "x" : topLeftX,
  "y" : topLeftY,
  "width" : width,
  "height" : height,
  "screen" : screen
});

topLeftX - top left x coordinate of the window's desired position. can be a String Expression, a Number or a function that returns one of them.
topLeftY - top left y coordinate of the window's desired position. can be a String Expression, a Number or a function that returns one of them.
width - width of the window's desired position. can be a String Expression, a Number or a function that returns one of them.
height - height of the window's desired position. can be a String Expression, a Number or a function that returns one of them.
screen - (optional) the reference to the screen of the window's desired position. If this is not specified, it will default to the screen the window is currently on. Can be a String reference, screen object, or a function that returns a String reference. Check this page for more information about screen objects and screen references.

Example

var move = slate.operation("move", {
  "x" : screenOriginX,
  "y" : screenOriginY,
  "width" : 100,
  "height" : 100,
  "screen" : "1"
});
slate.bind("pad1:ctrl", move);

Will bind the keystroke ctrl+numpad1 to moving the window to the screen at index 1 with top-left coordinate screenOriginX,screenOriginY and size 100,100

Note: Remember to offset with screenOriginX in your topLeftX and screenOriginY in your topLeftY when using the screen option (or when using multiple screens in general) or your move operation will offset from the default origin (0,0) which is the origin of screen 0.

Available Configs

Global configs only. No Operation specific configs available.

`resize`

Resize the window

var resize = slate.operation("resize", {
  "width" : width,
  "height" : height,
  "anchor" : anchor
});

width - amount to resize width either as a percent or a hard value (e.g. "+10%" or "-100"). can be a String or a function that returns a String.
height - amount to resize height either as a percent or a hard value (e.g. "+10%" or "-100"). can be a String or a function that returns a String.
anchor - (optional) which corner to anchor on. can be a String with one of "top-left", "top-right", "bottom-left", "bottom-right" or a function that returns on of them. default is "top-left".

Example

var resize = slate.operation("resize", {
  "width" : "+10%",
  "height" : "+0"
});
slate.bind("right:ctrl", resize);

Will bind the keystroke ctrl+rightarrow to increase the width the current window by 10% of the current screen size.

Note: ctrl+rightarrow is used by default in Mac OS X by spaces. Be sure to turn these bindings off if you want to use them in Slate.

Available Configs

Global configs and:

resizePercentOf

`push`

Push the window to the edge of the screen

var push = slate.operation("push", {
  "direction" : direction,
  "style" : style,
  "screen" : screen
});

direction - The direction to push the window. can be a String with one of "top", "up", "bottom", "down", "left", "right" or a function that returns one of them.
style - (optional) How to push the window. can be a String with one of "none", "center", "bar", "bar-resize:expression" or a function that returns one of them. default is "none".
screen - (optional) the reference to the screen of the window's desired position. If this is not specified, it will default to the screen the window is currently on. Can be a String reference, screen object, or a function that returns a String reference. Check this page for more information about screen objects and screen references.

Example

var push = slate.operation("push", {
  "direction" : "up",
  "style" : "bar-resize:screenSizeY/2"
});
slate.bind("up:alt,ctrl", push);

Will bind the keystroke alt-ctrl-uparrow to push the window so that it is aligned with the top of the screen and is resized to form a bar with the height screenSizeY/2

Available Configs

Global configs only. No Operation specific configs available.

`nudge`

Nudge the window in any direction

var nudge = slate.operation("nudge", {
  "x" : x,
  "y" : y
});

x - amount to nudge x either as a percent or a hard value (e.g. "+10%" or "-100"). can be a String or a function that returns a String.
y - amount to nudge y either as a percent or a hard value (e.g. "+10%" or "-100"). can be a String or a function that returns a String.

Example

var nudge = slate.operation("nudge", {
  "x" : "-100",
  "y" : "+0"
});
slate.bind("left:ctrl,shift", nudge);

Will bind the keystroke ctrl-shift-leftarrow to nudge the window 100 pixels to the left

Available Configs

Global configs and:

nudgePercentOf

`throw`

Throw the window to any screen's origin

var throw = slate.operation("throw", {
  "x" : topLeftX,
  "y" : topLeftY,
  "width" : width,
  "height" : height,
  "screen" : screen
});

screen - the reference to the screen of the window's desired position. Can be a String reference, screen object, or a function that returns a String reference. Check this page for more information about screen objects and screen references.
topLeftX - (optional) top left x coordinate of the window's desired position. can be a String Expression, a Number or a function that returns one of them. defaults to "screenOriginX".
topLeftY - (optional) top left y coordinate of the window's desired position. can be a String Expression, a Number or a function that returns one of them. defaults to "screenOriginY".
width - (optional) width of the window's desired position. can be a String Expression, a Number or a function that returns one of them. defaults to "windowSizeX".
height - (optional) height of the window's desired position. can be a String Expression, a Number or a function that returns one of them. defaults to "windowSizeY".

Example

var throw = slate.operation("throw", {
  "screen" : "1",
  "width" : "screenSizeX",
  "height" : "screenSizeY"
});
slate.bind("pad1:alt,ctrl", throw);

Will bind the keystroke alt-ctrl-numpad1 to throw the window to the 2nd screen and resize it to fit that screen

Available Configs

Global configs only. No Operation specific configs available.

`corner`

Move/Resize the window into a corner

var corner = slate.operation("corner" {
  "direction" : direction,
  "width" : width,
  "height" : height,
  "screen" : screen
});

direction - the direction of the corner to move the window to. can be a String with one of "top-left", "top-right", "bottom-left", "bottom-right".
width - (optional) width of the window's desired position. can be a String Expression, a Number or a function that returns one of them. defaults to "windowSizeX".
height - (optional) height of the window's desired position. can be a String Expression, a Number or a function that returns one of them. defaults to "windowSizeY".
screen - (optional) the reference to the screen of the window's desired position. If this is not specified, it will default to the screen the window is currently on. Can be a String reference, screen object, or a function that returns a String reference. Check this page for more information about screen objects and screen references.

Example

var corner = slate.operation("corner", {
  "direction" : "top-left",
  "width" : "screenSizeX/2",
  "height" : "screenSizeY/2"
});
slate.bind("1:ctrl", corner);

Will bind the keystroke ctrl-1 to move the window to the top-left corner and resize it to 1/4 of the screen.

Available Configs

Global configs only. No Operation specific configs available.

`shell`

Execute a shell command

var shell = slate.operation("shell", {
  "command" : command,
  "wait" : waitForExit,
  "path" : workingDirectory
});

command - the shell command to run. must be a String or a function that returns a String. e.g. "/bin/echo hi".
waitForExit - (optional) if true, block slate until the shell command exits. must be undefined, a Boolean or a function that returns a Boolean.
workingDirectory - (optional) the inital working directory to use when starting the command. must be undefined, a String or a function that returns a String. e.g. "~/code".

Example

var shell = slate.operation("shell", {
  "command" : "/opt/local/bin/mvim",
  "wait" : true,
  "path" : "~/code"
});
slate.bind("1:ctrl", shell);

Will bind the keystroke ctrl-1 to run the command /opt/local/bin/mvim with the current working directory of ~/code. Slate will also block until the command is done. Note that you may not use the tilda home directory shortcut within the command itself, it is only allowed within the path.

Available Configs

Global configs only. No Operation specific configs available.

`hide`

Hide one or more applications

var hide = slate.operation("hide", {
  "app" : applications
});

applications - the list of applications to hide. can be a String with a single application name, an Array with multiple application name Strings or a Function that returns one of them. You may also specify "current", "all", or "all-but:'APP_NAME'" for the application name. "current" will apply to the currently focused application, "all" will apply to all open applications and "all-but:'APP_NAME'" will apply to all open applications except APP_NAME. Note that when trying to hide "all" it will not work as intended because OS X will not allow every visible app to be hidden. Hiding "all" will hide all apps but OS X will auto-show one of the apps that were hidden.

Example

var hide = slate.operation("hide", {
  "app" : ["iTerm", "Google Chrome"]
});
slate.bind("1:ctrl", hide);

Will bind the keystroke ctrl-1 to hide iTerm and Google Chrome.

Available Configs

Global configs only. No Operation specific configs available.

`show`

Show one or more applications

var show = slate.operation("show", {
  "app" : applications
});

applications - the list of applications to show. can be a String with a single application name, an Array with multiple application name Strings or a Function that returns one of them. You may also specify "current", "all", or "all-but:'APP_NAME'" for the application name. "current" will apply to the currently focused application, "all" will apply to all open applications and "all-but:'APP_NAME'" will apply to all open applications except APP_NAME.

Example

var show = slate.operation("show", {
  "app" : ["iTerm", "Google Chrome"]
});
slate.bind("1:ctrl", show);

Will bind the keystroke ctrl-1 to show (unhide) iTerm and Google Chrome.

Available Configs

Global configs only. No Operation specific configs available.

`toggle`

Toggle one or more applications

var toggle = slate.operation("toggle", {
  "app" : applications
});

applications - the list of applications to show. can be a String with a single application name, an Array with multiple application name Strings or a Function that returns one of them. You may also specify "current", "all", or "all-but:'APP_NAME'" for the application name. "current" will apply to the currently focused application, "all" will apply to all open applications and "all-but:'APP_NAME'" will apply to all open applications except APP_NAME. Note that when trying to toggle "all" it will may not work as intended because OS X will not allow every visible app to be hidden. If at any point during the toggling all apps become hidden, OS X will auto-show one of the apps that were hidden.

Example

var toggle = slate.operation("toggle", {
  "app" : ["iTerm", "Google Chrome"]
});
slate.bind("1:ctrl", toggle);

Will bind the keystroke ctrl-1 to toggle iTerm and Google Chrome. Toggle meaning if the individual application is currently hidden it will be shown and if it is currently shown it will be hidden.

Note: If you specify current in this toggle operation it will not toggle properly because after the current application is hidden, it is no longer the current application anymore.

Available Configs

Global configs only. No Operation specific configs available.

`focus`

Focus a window in a direction or from an application

var focus = slate.operation("focus", {
  // only one of these is required. if both are specified it will use app.
  "direction" : direction,
  "app" : app
});

direction - the direction to focus. can be a String with one of "right", "left", "up", "above", "down", "below", "behind" or a function that returns one of them.
app - an app name. can be a String or a function that returns a String.

Examples

var focus = slate.operation("focus", {
  "direction" : "above"
});
slate.bind("1:ctrl", focus);

Will bind the keystroke ctrl-1 to focus the window Slate finds to be above the currently focused window (from any application). Minimized and hidden windows are ignored. Also, "up" and "above" are the same. "down" and "below" are also the same.

var focus = slate.operation("focus", {
  "app" : "iTerm"
});
slate.bind("1:ctrl", focus);

Will bind the keystroke ctrl-1 to focus the main window of the application iTerm. The main window is the last focused window of that application.

Available Configs

Global configs and:

`chain`

Chain multiple operations to one binding

var chain = slate.operation("chain", {
  "operations" : operations
});

operations - an Array containing a list of Operations (except hint, grid, and switch) or functions

Example

var pushUp = slate.operation("push", { "direction" : "up" });
var pushRight = slate.operation("push", { "direction" : "right" });
var pushDown = slate.operation("push", { "direction" : "down" });
var pushLeft = slate.operation("push", { "direction" : "left" });
var chain = slate.operation("chain", {
  "operations" : [
    pushUp,
    function(windowObject) { windowObject.doOperation(pushRight); },
    pushDown,
    pushLeft
  ]
});
slate.bind("1:ctrl", chain);

Will bind the keystroke ctrl-1 to push up on the first press, then push right on the second press, then push down on the third press, the push left on the fourth press and rotate back to pushing up on the fifth press (etc).

Available Configs

Global configs only. No Operation specific configs available.

`sequence`

Activate a sequence of operations in one binding

var sequence = slate.operation("sequence", {
  "operations" : operations
});

operations - an Array of Arrays containing a list of Operations (except hint, grid, and switch) or functions. The operations within each subarray will be performed on the window focused at the time of the execution of the first operation within that subarray.

Example

var focusRight = slate.operation("focus", { "direction" : "right" });
var pushRight = slate.operation("push", { "direction" : "right" });
var pushLeft = slate.operation("push", { "direction" : "left" });
var sequence = slate.operation("sequence", {
  "operations" : [
    [ function(windowObject) { windowObject.doOperation(focusRight); }, pushLeft ],
    [ pushRight ]
  ]
});
slate.bind("1:ctrl", sequence);

Will bind the keystroke ctrl-1 to first focus the window to the right, then push the previously focused window to the left, then push the newly focused window to the right.

Available Configs

Global configs only. No Operation specific configs available.

`layout`

Activate a layout

var layout = slate.operation("layout", {
  "name" : name
});

name - the name of the layout to activate (set using the slate.layout function). must be a String or a function that returns a String.

Example

var layout = slate.operation("layout", {
  "name" : "myLayout"
});
slate.bind("1:ctrl", layout);

Will bind the keystroke ctrl-l to activate the layout called myLayout.

Available Configs

Global configs and:

layoutFocusOnActivate

`snapshot`

Create a snapshot of your current window locations

var snapshot = slate.operation("snapshot", {
  "name" : name,
  "save" : saveToDisk,
  "stack" : isStack
});

name - the name of the snapshot to create (used in delete-snapshot and activate-snapshot). can be a String or a function that returns a String.
saveToDisk - (optional) if true, saves the snapshot to disk so Slate will load it when it starts up next. can be undefined, a Boolean or a function that returns a Boolean.
isStack - (optional) if true, treats this snapshot as stack so you can use this binding multiple times to push snapshots on the stack. if false or undefined only one snapshot will be stored, overwriting any previous snapshot that existed for this name. can be undefined, a Boolean or a function that returns a Boolean.

Example

var snapshot = slate.operation("snapshot", {
  "name" : "theName",
  "save" : true,
  "stack" : true
});
slate.bind("1:ctrl", snapshot);

Will bind the keystroke ctrl-1 to create a snapshot called "theName", save that snapshot to disk, and treat it as a stack so you can hit the keystroke multiple times to push snapshots onto the stack.

Note: There is a menu option to take a snapshot of the current screen configuration.

Available Configs

Global configs and:

snapshotMaxStackSize

`delete-snapshot`

Delete a snapshot

var deleteSnapshot = slate.operation("delete-snapshot", {
  "name" : name,
  "all" : all
});

name - the name of the snapshot to delete (same as the name in the snapshot operation)
all - (optional) if true and the snapshot is a stack (if it isn't a stack, this option is useless), this will delete all snapshots in the stack. if undefined or false, only delete the top snapshot of the stack. can be undefined, a Boolean or a function that returns a Boolean.

Example

var deleteSnapshot = slate.operation("delete-snapshot", {
  "name" : "theName",
  "all" : true,
});
slate.bind("1:ctrl", deleteSnapshot);

Will bind the keystroke ctrl-1 to delete the snapshot called theName if it exists. This will delete all instances of theName meaning if you have pushed multiple snapshots on the stack, it will completely clear them all.

Available Configs

Global configs only. No Operation specific configs available.

`activate-snapshot`

Activate a snapshot

var activateSnapshot = slate.operation("activate-snapshot", {
  "name" : name,
  "delete" : delete
});

name - the name of the snapshot to activate (same as the name in the snapshot operation)
delete - (optional) if true this will delete the snapshot after activating it (if the snapshot is a stack, it will pop the top snapshot off and keep the rest). if undefined or false the snapshot will be activated but not deleted. can be undefined, a Boolean or a function that returns a Boolean.

Example

var activateSnapshot = slate.operation("activate-snapshot", {
  "name" : "theName",
  "delete" : true,
});
slate.bind("1:ctrl", activateSnapshot);

Will bind the keystroke ctrl-1 to activate the snapshot called theName if it exists. This will also delete the snapshot (or pop it off the stack if the snapshot is a stack).

Note: There is a menu option to activate the snapshot that you may have created using the menu option.

Available Configs

Global configs and:

snapshotTitleMatch

`hint`

Show Window Hints (similar to Link Hints in Vimium except for Windows)

var hint = slate.operation("hint", {
  "characters" : characters
});

characters - (optional) a string of characters to be used for the hints. each hint consists of one character. if there are more windows than characters then some windows will not get hints. this string can contain any of the single character Allowed Keys. Letters may be upper case or lower case, but both will be bound to the lowercase letter for the hint. Using upper or lower case only changes how they are displayed. The default string of characters is "ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789". can be undefined, a String, or a function that returns a String.

Example

var hint = slate.operation("hint", {
  "characters" : "QWERTYUIOP"
});
slate.bind("1:ctrl", hint);

Will bind the keystroke ctrl-1 to show Window Hints using the letters Q, W, E, R, T, Y, U, I, O, and P. This will show an overlay in the top-left corner of every window on screen containing one of those letters. While the overlays are showing, if one of those letters is pressed, the corresponding window will be focused. If there are more than 10 windows, some windows will not get hints. Pressing ESC or waiting 3 seconds will dismiss the hints.

Available Configs

Global configs and:

`grid`

Show a Grid to one-off resize and move windows

var grid = slate.operation("grid", {
  "grids" : grids
  "padding" : padding
});

grids - a hash with the key as a screen reference (String reference only, no objects) and the value as a hash that looks like { "width" : widthOfGrid, "height" : heightOfGrid } where widthOfGrid and heightOfGrid are the width and the height of the grid (number of cells, not absolute size).
padding - (optional) the padding between cells. defaults to 2. can be an undefined, an Integer, or a function that returns an Integer.

Example

var grid = slate.operation("grid", {
  "grids" : {
    "1680x1050" : {
      "width" : 16
      "height" : 9
    },
    "1050x1680" : {
      "width" : 9
      "height" : 16
    }
  },
  "padding" : 5
});
slate.bind("1:ctrl", grid);

Will bind the keystroke ctrl-1 to show Grids on each screen. The default width and height are 12. This will set the padding between the cells to be 5. Also, this will change the width and height of the grid on the monitor with the resolution 1680x1050 to 16 and 9 respectively. For the monitor with the resolution 1050x1680, it will set the width to 9 and height to 16. If you have multiple monitors, the Grid that is on the same screen as your mouse pointer will be focused. If you want to use a grid on a different monitor you must click it first and then click+drag.

Available Configs

Global configs and:

`relaunch`

Relaunch Slate

var relaunch = slate.operation("relaunch");

Example

var relaunch = slate.operation("relaunch");
slate.bind("1:ctrl", relaunch);

Will bind the keystroke ctrl-1 to relaunch Slate. This will also reload the .slate and .slate.js files from scratch.

Available Configs

Global configs only. No Operation specific configs available.

`undo`

Undo an Operation

var undo = slate.operation("undo");

Example

var undo = slate.operation("undo");
slate.bind("1:ctrl", undo);

Will bind the keystroke ctrl-1 to undo the last binding that was triggered. By default you can undo up to the last 10 commands. This can be changed using the undoMaxStackSize config. Also, you can only undo movement-based operations. Focus-related operations will not undo.

Global configs and:

`switch`

BETA - A Better Application Switcher

var switcher = slate.operation("switch");

Example

var switcher = slate.operation("switch");
slate.bind("tab:cmd", switcher);

Will disable the default Mac OS X Application switcher and bind the keystroke cmd-tab to a better application switcher. Currently binding the switcher to cmd-tab is a bit buggy because of limitations on OS X's ability to detect cmd-tab keypresses (read: Apple doesn't want you to do that). Binding the switcher to another key combination will work fine.

If you bind any binding to cmd-tab or cmd-shift-tab, Slate will completely disable the default Mac OS X Application switcher!

Global configs and: