Skip to content

JavaScript Configs

Jump to bottom Edit New page
kassens edited this page Mar 12, 2013 · 60 revisions

This page documents the JavaScript config feature of Slate. This feature is available in Slate version 1.0.19 and above. It is advised that you update to the latest Slate as some of the APIs may have changed since 1.0.19.

Many thanks to mgax for the initial code.

Appetizer

Normally, the way Slate is configured, a truly dynamic operation is impossible.

For example, lets say I'm a nutjob and I wanted the keystroke ctrl+1 to:

  • if the window's title is "OMG I WANT TO BE FULLSCREEN" then fullscreen the window regardless of the application.
  • push the window to the right if the application of the current window is iTerm
  • push the window to the left if the application is Google Chrome
  • push the window to the top if the application is anything else

And again, I want the keystroke ctrl+1 to handle all of this. In the typical Slate config, this is impossible.

Enter JavaScript Configs:

// Create Operations
var pushRight = slate.operation("push", {
  "direction" : "right",
  "style" : "bar-resize:screenSizeX/3"
});
var pushLeft = slate.operation("push", {
  "direction" : "left",
  "style" : "bar-resize:screenSizeX/3"
});
var pushTop = slate.operation("push", {
  "direction" : "top",
  "style" : "bar-resize:screenSizeY/2"
});
var fullscreen = slate.operation("move", {
  "x" : "screenOriginX",
  "y" : "screenOriginY",
  "width" : "screenSizeX",
  "height" : "screenSizeY"
});
// Bind A Crazy Function to 1+ctrl
slate.bind("1:ctrl", function(win) {
  // here win is a reference to the currently focused window
  if (win.title() === "OMG I WANT TO BE FULLSCREEN") {
    win.doOperation(fullscreen);
    return;
  }
  var appName = win.app().name();
  if (appName === "iTerm") {
    win.doOperation(pushRight);
  } else if (appName === "Google Chrome") {
    win.doOperation(pushLeft);
  } else {
    win.doOperation(pushTop);
  }
});

Definitely verbose, but they can do much more than normal configs. Yum.

Main Course

Disclaimer: I have only done basic smoke screen testing on this so far. It is definitely possible that some things don't work as expected. If that is the case please create an issue and I'll take a look.

To use JavaScript configs, create the file .slate.js in your home directory. You can use .slate.js alongside your .slate file if you like and Slate will load both (.slate first, then .slate.js). You can also use only the .slate.js if you want. All JavaScript configs should go into the .slate.js file.

In the .slate.js file you will have access to the following global objects:

In .slate.js, if an exception is thrown, Slate will stop executing and show an alert.

The slate JavaScript Object

The slate object serves two purposes: configuring Slate and accessing information about the your environment and windows.

The slate object is aliased to S. For example, instead of calling slate.log("hi"); you can simply call S.log("hi");. Most of the config APIs are aliased as well. See their sections below for their aliases.

slate Config APIs

slate.config

Set a Slate global config.

Alias: S.config or S.cfg

slate.config(name, value);
  • name is the name of the Slate config. Must be a String.
  • value is the value of the Slate config. Depending on the config it can be a String, Number, Boolean, Array, or even a Function that returns one of them.

Here is a list of possible configs.

slate.configAll

Batch set Slate global configs.

Alias: S.configAll or S.cfga

slate.configAll({
  name : value,
  name : value,
  ...
});
  • name and value are the same as slate.config.

Here is a list of possible configs.

slate.operation

Create a Slate operation.

Alias: S.operation or S.op

var object = slate.operation(name, params);
  • object - the created operation. can be used to reference this operation in other APIs.
  • name - the operation name. must be a String. e.g. "move".
  • params - the operation's parameters. must be a Hash. more information on the parameters that operations take can be found here.

Here is list of possible operations.

slate.operationFromString

Create a Slate operation using the original Slate config style.

Alias: S.operationFromString or S.opstr

var object = slate.operationFromString(operationString);
  • object - the created operation. can be used to reference this operation in other APIs.
  • operationString - the original-style Slate config for the operation. must be a String. e.g. "push right".

Here is the original-style config reference.

slate.bind

Bind a keystroke to an action.

Alias: S.bind or S.bnd

slate.bind(keystroke, action, repeat);
  • keystroke - the keystroke used to activate this binding. must be a String. more information about how to set keystrokes can be found here. e.g. "1:ctrl".
  • action - the action to perform when this binding is activated. must be an Operation object or a JavaScript function.
  • repeat - whether to repeat this binding if the keystroke is held. if undefined, the config repeatOnHoldOps will be used to determine if this operation should be repeated. must be undefined or a Boolean.

Here is an explanation of how keystrokes work.

slate.bindAll

Batch bind keystrokes to actions.

Alias: S.bindAll or S.bnda

slate.bindAll({
  keystroke : action, // this will cause repeat to be undefined
  keystroke : [action, repeat], // or you can just specify repeat like this
  ...
});
  • keystroke, action and repeat are the same as in slate.bind.

Here is an explanation of how keystrokes work.

slate.layout

Create a Slate layout.

Alias: S.layout or S.lay

var name = slate.layout(name, {
  app : params,
  app : params,
  ...
});
  • name - the name of the layout. must be a string. used as a reference in other slate APIs.
  • app - the name of the app. must be a string. e.g. "iTerm".
  • params - the layout parameters. for more information on layout parameters, check this out.

Here is an in depth explanation of layouts.

slate.default

Set a default action to be performed when a particular screen configuration is seen.

Alias: S.default or S.def

slate.default(screenConfig, action);
  • screenConfig - the configuration of screens that will default to action. can be an integer (number of screens e.g. 3) or an Array of Strings (list of resolutions e.g. ["1920x1080","1680x1050","2560x1440"]).
  • action - the action to perform when the screenConfig is seen. must be a layout name, snapshot name, Operation object or JavaScript function.

Here is an in depth explanation of defaults.

slate.source

Load another Slate configuration file.

Alias: S.source or S.src

var success = slate.source(filepath);
  • success - true if the file was sourced, false if not (an error occurred).
  • filepath - the complete path to the file to source. can have "~/" as a prefix. must be a string.

slate.on

Listen to an event.

slate.on(event, callback);
  • event - the name of the event to listen for.
  • callback - the function to execute when the event occurs.

Here is an in depth explanation of events.

slate Info APIs

slate.shell

Execute a shell command and get the result.

Alias: S.shell or S.sh

var output = slate.shell(commandAndArgs, waitForExit, path);
  • output - the output of the command (on stdout). will be nil if waitForExit is false or undefined.
  • commandAndArgs - the command and args to run. your .bashrc or .bash_profile will not be sourced before running the command so all binaries need to be referenced by their full path. must be a string. e.g. "/usr/echo hello".
  • waitForExit - if true, Slate will wait for the command to exit and return the output from stdout. must be undefined or a Boolean.
  • path - the working directory to use. must be undefined or a string. e.g. "~/".

slate.window

Get the currently focused window.

Alias: S.window

var windowObject = slate.window();
  • windowObject - the currently focused window.

Here is a description of the JavaScript window object.

slate.windowUnderPoint

Get the window under the point specified.

Alias: S.windowUnderPoint or S.wup

var windowObject = slate.windowUnderPoint({
  "x" : xCoord,
  "y" : yCoord
});
  • xCoord - the x coordinate to check. can be an Integer or an Expression. e.g. 1337 or "screenOriginX+screenSizeX/2".
  • yCoord - the y coordinate to check. can be an Integer or an Expression. e.g. 1337 or "screenOriginY+screenSizeY/2".

Here is a description of the JavaScript window object. Here is a description of Expressions.

slate.app

Get the currently focused app.

Alias: S.app

var appObject = slate.app();
  • appObject - the currently focused app.

Here is a description of the JavaScript application object.

slate.eachApp

Cycle through each app.

Alias: S.eachApp or S.eapp

slate.eachApp(function(appObject) {
  // do something with the appObject. this function will run once per running application.
});
  • appObject - the current app in the loop.

Here is a description of the JavaScript application object.

slate.screen

Get the currently focused screen.

Alias: S.screen

var screenObject = slate.screen();
  • screenObject - the currently focused screen.

Here is a description of the JavaScript screen object.

slate.screenCount

Get the total number of screens.

Alias: S.screenCount or S.screenc

var count = slate.screenCount();
  • count - the total number of screens. will be an integer.

slate.screenForRef

Get the screen object for the reference.

Alias: S.screenForRef or S.screenr

var screenObject = slate.screenForRef(reference);
  • screenObject - the screen object for the reference.
  • reference - the screen reference. must be a string containing either the id or the resolution. e.g. "0" or "1920x1080".

Here is a description of the JavaScript screen object.

slate.screenUnderPoint

Get the screen under the point specified.

Alias: S.screenUnderPoint or S.sup

var screenObject = slate.screenUnderPoint({
  "x" : xCoord,
  "y" : yCoord
});
  • xCoord - the x coordinate to check. can be an Integer or an Expression. e.g. 1337 or "screenOriginX+screenSizeX/2".
  • yCoord - the y coordinate to check. can be an Integer or an Expression. e.g. 1337 or "screenOriginY+screenSizeY/2".

Here is a description of the JavaScript screen object. Here is a description of Expressions.

slate.isPointOffScreen

Check whether the given point is off screen or not.

Alias: S.isPointOffScreen or S.pntoff

var result = slate.isPointOffScreen({
  "x" : xCoord,
  "y" : yCoord
});
  • result - true if the point is off screen, false otherwise.
  • xCoord - the x coordinate to check. can be an Integer or an Expression. e.g. 1337 or "screenOriginX+screenSizeX/2".
  • yCoord - the y coordinate to check. can be an Integer or an Expression. e.g. 1337 or "screenOriginY+screenSizeY/2".

Here is a description of Expressions.

slate.isRectOffScreen

Check whether the given rectangle is off screen or not.

Alias: S.isRectOffScreen or S.rectoff

var result = slate.isRectOffScreen({
  "x" : xCoord,
  "y" : yCoord,
  "width" : width,
  "height" : height
});
  • result - true if the rectangle is off screen, false otherwise.
  • xCoord - the x coordinate of the top-left point of the rectangle to check. can be an Integer or an Expression. e.g. 1337 or "screenOriginX+screenSizeX/2".
  • yCoord - the y coordinate of the top-left point of the rectangle to check. can be an Integer or an Expression. e.g. 1337 or "screenOriginY+screenSizeY/2".
  • width - the width of the rectangle to check. can be an Integer or an Expression. e.g. 1337 or "screenSizeX/2".
  • height - the height of the rectangle to check. can be an Integer or an Expression. e.g. 1337 or "screenSizeY/2".

Here is a description of Expressions.

slate.eachScreen

Cycle through each screen.

Alias: S.eachScreen or S.escreen

slate.eachScreen(function(screenObject) {
  // do something with the screenObject. this function will run once per screen.
});
  • screenObject - the current screen in the loop.

Here is a description of the JavaScript screen object.

slate.log

Log a message to the OS X debug console.

Alias: S.log

slate.log(message);
  • message - the message to log. must be a String.

Example JavaScript Config

Here is my own .slate.js.

Add a custom footer
Add a custom sidebar
Clone this wiki locally