Online Preview of Autumn's API

This is an online copy of the documentation that's built into Autumn, so that you can see in more detail what kind of things Autumn can do for you before trying it out.

Functions for managing any open window.
Note that Windows always resolve to the same object and can thus be compared with strict object equality (===).
Getting windows
static focusedWindow(): Window | null;
Returns the window that currently has keyboard focus. Returns null sometimes, like if you minimize the focused window to the Dock.
static windowUnderMouse(): Window | null;
Returns the window currently under the mouse, if any.
static allWindows(): Window[];
Returns every window on all screens, ordered from frontmost to backmost.
static visibleWindows(): Window[];
The same as Window.allWindows().filter(win => win.isVisible())
windowsInDirection(direction: number): Window[];
Returns ordered list of windows in the given direction.
Note: This uses a ray-tracing algorithm to give a generally useful but inexact interpretation of windows in this direction.
direction: One of Window.Dir.{Up,Down,Left,Right}
otherWindows(onSameScreen: boolean = true): Window[];
Returns all windows except this one, optionally limiting results to this window's screen.
Window events
static onWindowOpened: (win: Window) => void;
Set a callback for when a new window opens.
static onWindowClosed: (win: Window) => void;
Set a callback for when any window closes.
Note: This is probably only useful for comparing closed windows to ones you have stored, since most of its methods may return null at this point.
onClosed: () => void;
Set a callback for when this window closes.
Note: This is probably only useful for comparing closed windows to ones you have stored or releasing some resources, since most of its methods may return null at this point.
onMoved: () => void;
Set a callback for when this window is moved.
onResized: () => void;
Set a callback for when this window is resized.
onMinimized: () => void;
Set a callback for when this window is minimized.
onUnminimized: () => void;
Set a callback for when this window is unminimized.
onTitleChanged: () => void;
Set a callback for when this window's title changes.
Window properties
id: number;
Unique identifier for this window.
Note: this is not strictly needed for comparison, since Windows can be compared with strict object equality (w1 === w2).
title(): string;
Returns the current title of the window.
app: App;
The app that the window belongs to.
screen(): Screen;
Returns the screen that this window is mostly on.
Moving windows
position(): Point;
Get the window's position, based on the top-left of the screen.
setPosition(position: PointLike): void;
Set the window's position, based on the top-left of the screen.
If the position being set contains NaN or Infinity, this is a no-op.
size(): Size;
Get the window's size.
setSize(size: SizeLike): void;
Set the window's size.
If the size being set contains NaN or Infinity, this is a no-op.
frame(): Rect;
Get the window's size and position.
setFrame(frame: RectLike): void;
Set the window's size and position.
If the frame being set contains NaN or Infinity, this is a no-op.
moveToPercentOfScreen(unit: RectLike): void;
Sets this window's position and size, where x, y, width and height are each between 0.0 and 1.0 of the window's current screen.
setCenterPoint(point: PointLike): void;
Move this window so that its center is at `point`.
Doesn't resize the window at all, even if that means it will be partly off-screen.
centerOnScreen(screen?: Screen = this.screen()): void;
Move this window to the center of the screen without resizing it.
screen: Defaults to the window's current screen.
Window actions
focus(): void;
Focus this window, focusing its app if necessary.
focusNext(direction: number): void;
Focuses the next window in the given direction, if any.
Note: This uses a ray-tracing algorithm to give a generally useful but inexact interpretation of windows in this direction.
direction: One of Window.Dir.{Up,Down,Left,Right}
close(): void;
Same as clicking the close button on the window. May prompt and leave the window open, if it has unsaved data.
setFullScreen(shouldBeFullScreen: boolean): void;
Toggles whether the window should be full screen.
minimize(): void;
Minimizes the window to the Dock.
unminimize(): void;
Unminimizes the window from the Dock.
maximize(): void;
Sets the window's frame to the maximum size on its current screen.
Note: this does not make the window full screen, use `setFullScreen` for that.
isNormalWindow(): boolean;
Returns whether the window is not a panel and not minized.
isFullScreen(): boolean;
Returns whether the window is full screen.
isMinimized(): boolean;
Returns whether the window is minimized to the Dock.
isVisible(): boolean;
Returns true if the app is not hidden and the window is not minimized.
Control running applications.
Note that Apps always resolve to the same object and can thus be compared with strict object equality (===).
Getting or creating apps
staticallApps
staticopen
Getting windows from apps
Getting or creating apps
static allApps(): App[];
Returns all currently running apps, where app.kind === 'dock'.
static allDaemons(): App[];
Returns all currently running apps, where kind !== 'dock'.
static focusedApp(): App;
Returns the app that currently has keyboard focus.
static open(name: string): boolean;
Opens the app with the given name, or makes it the current app if it's already running.
The name doesn't need the full path or .app extension, but both are allowed.
Returns true if the app opened, false if the app doesn't exist or can't be opened.
App events
static onAppLaunched: (app: App) => void;
Set a callback for when an app opens.
static onFocusedAppChanged: (app: App) => void;
Set a callback for when a new app becomes the focused app.
onTermination: () => void;
Set a callback for when an app quits.
onHidden: () => void;
Set a callback for when this app is hidden.
onUnhidden: () => void;
Set a callback for when this app is unhidden.
Getting windows from apps
mainWindow(): Window;
Returns the main window of the given app, or nil.
allWindows(): Window[];
Returns all open windows owned by the given app.
App properties
name: string;
The name of the app, e.g. "Safari" or "Finder".
bundleId: string | undefined;
The bundle identifier of the app, like "com.apple.finder".
Note: some processes don't have this, mainly some of Apple's own daemons.
pid: number;
The app's process identifier.
Note: this is not strictly needed for comparison, since Apps can be compared with strict object equality (a1 === a2).
kind: 'dock' | 'no-dock' | 'no-gui';
The string 'dock' means the app is in the dock, 'no-dock' isn't, and 'no-gui' means it can't even have GUI elements if it wanted to.
isRunning: boolean;
Returns whether the app is still running or has already quit.
isFocused: boolean;
Returns whether the app is the front-most app.
isHidden(): boolean;
Returns whether the app is currently hidden.
isUnresponsive(): boolean;
True if the app has the spinny circle of death.
App actions
activate(allWindows: boolean = false): boolean;
Tries to activate the app (make its key window focused) and returns whether it succeeded.
allWindows: Whether all windows are brought to the front.
hide(): boolean;
Hides the app (and all its windows).
unhide(): boolean;
Unhides the app (and all its windows) if it's hidden.
quit(): void;
Tries to terminate the app.
forceQuit(): void;
Terminates the app.
Note: this may cause loss of data!
Information about each screen per monitor.
Note that Screens always resolve to the same object and can thus be compared with strict object equality (===).
Getting screens
Getting windows
Screen properties
Dark mode
Getting screens
static allScreens(): Screen[];
Returns an array of every screen, representing attached monitors.
Note: This array starts with the screen that has the menu bar and Dock, or if you're using mirroring, the screen with the best resolution.
static currentScreen(): Screen;
Returns the screen that contains the currently active window.
nextScreen(): Screen;
Get the screen after `this` in the `allScreens()` array.
previousScreen(): Screen;
Get the screen before `this` in the `allScreens()` array.
Getting windows
allWindows(): Window[];
Returns Window.allWindows filtered where win.screen === this
visibleWindows(): Window[];
Returns Window.visibleWindows filtered where win.screen === this
Screen events
static onScreenConnected: (screen: Screen) => void;
Set a callback for when a screen is added.
static onScreenDisconnected: (screen: Screen) => void;
Set a callback for when a screen is removed.
static onScreensReconfigured: (screen: Screen) => void;
Set a callback for when a screen is reconfigured.
Screen properties
id: number;
Unique, persistent identifier for this screen.
Note: this is not strictly needed for comparison, since Screens can be compared with strict object equality (s1 === s2).
name: string;
The name of this screen.
fullFrame(): Rect;
Returns this screen's frame, including any space the Dock and menu bar might be taking up.
innerFrame(): Rect;
Returns this screen's frame, excluding any space the Dock and menu bar might be taking up.
Dark mode
static inDarkMode(): boolean;
static darkModeChanged: () => void;
Set a callback for when dark mode is turned on or off.
Grid-based window manager class.
Think of a GridWM as slicing your screen into a grid of this many equal rows and columns. It has the ability to align windows so they fit perfectly within one of the grid cells, and to move windows to adjacent or arbitrary cells on the grid.
To use this class, create a new instance via `new`, set rows and cols, and use its methods within your own hotkey callbacks. See `Hotkey.activate` and the sample code for reference.
Configuration
rows: number;
The number of rows (height) in this grid.
Defaults to 2
cols: number;
The number of columns (width) in this grid.
Defaults to 3
padding: number;
(Deprecated.) The number of pixels each grid cell is padded by, to add a little spacing between windows.
Defaults to 0
margin: number;
The number of pixels between grid cell, to add a little spacing between windows.
Defaults to 0
Aligning windows to the grid
align(win?: Window = Window.focusedWindow()): void;
Align this window to the grid.
alignAll(wins?: Window[] = Window.visibleWindows()): void;
Align all given windows to the grid. Defaults to all visible windows.
Moving windows
moveUp(win?: Window = Window.focusedWindow()): void;
moveDown(win?: Window = Window.focusedWindow()): void;
moveLeft(win?: Window = Window.focusedWindow()): void;
moveRight(win?: Window = Window.focusedWindow()): void;
Growing windows
growAbove(win?: Window = Window.focusedWindow()): void;
growBelow(win?: Window = Window.focusedWindow()): void;
growLeft(win?: Window = Window.focusedWindow()): void;
growRight(win?: Window = Window.focusedWindow()): void;
fillCurrentColumn(win?: Window = Window.focusedWindow()): void;
fillCurrentRow(win?: Window = Window.focusedWindow()): void;
Shrinking windows
shrinkFromAbove(win?: Window = Window.focusedWindow()): void;
shrinkFromBelow(win?: Window = Window.focusedWindow()): void;
shrinkFromLeft(win?: Window = Window.focusedWindow()): void;
shrinkFromRight(win?: Window = Window.focusedWindow()): void;
Moving to other screens
moveToNextScreen(win? Window = Window.focusedWindow()): void;
moveToPreviousScreen(win? Window = Window.focusedWindow()): void;
Advanced functionality
moveToCellGroup(cellGroup: RectLike, win?: Window, screen?: Screen): void;
A cell group is a Rect of the upper-left to bottom-right cells.
win: The window to move, defaults to Window.focusedWindow() if omitted.
screen: The screen to move the window to, defaults to win.screen() if omitted.
approximateCellGroup(win: Window): Rect;
Returns the Rect representing the cell group that the window currently fits best on.
fullScreenCellGroup(): Rect;
Returns a cell group that fits the full screen, based on the current rows and cols.
Create custom global keyboard shortcuts.
staticactivate
static activate(
mods: number,
key: KeyString,
callback: () => void
): number | null;
This installs and activates a global hotkey handler.
Mods are the numeric values inside `Hotkey.Mods` bitwise-or'd together.
Returns a unique ID that can be used to deactivate the hotkey later, or null if this hotkey already exists within Autumn.
Note: hotkeys are automatically deactivated when User Scripts are stopped and/or restarted, so you don't need to manually deactivate them.
static deactivate(uid: number);
Deactivate the hotkey with this unique ID. The callback function will be released at the next GC.
Note: hotkeys are automatically deactivated when User Scripts are stopped and/or restarted, so you don't need to manually deactivate them. But you can, if you want to.
Access information in the pasteboard.
static stringContents(): string;
The most recent string in the pasteboard, or nil.
static changeCount(): number;
The number of times the pasteboard has changed so far.
Show notifications in Notification Center.
staticpost
static post(options: {
title: string,
subtitle?: string,
body?: string,
onClick?: () => void
}): void;
Show a notification in Apple's built-in Notification Center.
Read and write files.
staticread
staticwrite
staticmkdir
staticls
static read(path: string): string | null;
Returns the contents of a file as a UTF8 string or nil if anything went wrong.
You can use ~ to represent $HOME.
static write(path: string, contents: string): boolean;
Writes the string to the given path, overriding anything that may be there already. Assumes data is UTF8. Returns whether it succeeded.
You can use ~ to represent $HOME.
static mkdir(path: string): boolean;
Same as `mkdir -p path`. Returns whether it succeeded.
You can use ~ to represent $HOME.
static ls(path: string): string[] | null;
Returns an array of filenames inside the directory at path, or null if anything went wrong (e.g. path doesn't exist or is a file).
You can use ~ to represent $HOME.
Access the internet.
staticget
staticgetSync
static get(url: string): Promise<string>;
Gets the contents of the given url, and returns a promise that resolves to it as a UTF8 string, throwing if anything goes wrong.
Note: only HTTPS-based URLs are allowed at this time.
static getSync(url: string): string | null;
Gets the contents of the given url, and returns it as a UTF8 string, or null if anything goes wrong.
Note: only HTTPS-based URLs are allowed at this time.
Run command line utilities.
staticrun
staticrunSync
static run(cmd: string): Promise<{
code: number,
stdout: string | null,
stderr: string | null
}>;
Runs the given command, and returns a promise that resolves to its exit code and stdout/stderr as UTF8 strings if possible & available.
Tip: instead of using the promise directly, try using it in an async function like so:
(async function() { const result = await Shell.run('echo hello world'); console.log(result) })()
static runSync(cmd: string): {
code: number,
stdout: string | null,
stderr: string | null
};
Runs the given command, and returns its exit code and stdout/stderr as UTF8 strings if possible & available.
Note: this will halt Autumn until the shell command finishes, which may result in noticeable lag. If it may hang or take a while to complete, consider using the promise-based method above.
Handle USB connect/disconnect events.
static onConnected: (info: {
name:string,
vendor:string,
serial:string,
uid?:number
}) => void;
Set a function that will be called when a USB device is connected.
The 'uid' info field is unique and persistent even across reboots.
static onDisconnected: (info: {
name:string,
vendor:string,
serial:string,
uid?:number
}) => void;
Set a function that will be called when a USB device is disconnected.
The 'uid' info field is unique and persistent even across reboots.
Wifi network info and event handlers.
static networkName(): string | null;
The name of the network you're currently connected to, if any.
static onNetworkPowerChanged: () => void;
Set a callback for when your wifi turns on or off.
static onNetworkChanged: () => void;
Set a callback for when your wifi network changes.
For sending and receiving keyboard events.
static onModsChanged: ({
Command: boolean,
Control: boolean,
Option: boolean,
Shift: boolean,
Fn: boolean,
}) => void;
Set a callback for when any keyboard modifiers are pressed or released.
static onLayoutChanged: () => void;
Set the callback for when the keyboard layout changes (i.e. from Qwerty to Colemak)
Control the mouse.
staticposition
staticmove
staticonMoved
static position(): Point;
Get the current position of the mouse cursor.
static move(position: PointLike): void;
Set the current position of the mouse cursor.
static onMoved: (p: Point) => void;
Set a callback for when the mouse is moved.
React to your Mac's power states.
Power events
staticonWake
staticonSleep
Get power info
Idle & sleep
Power events
static onWake: () => void;
Set a callback for when your computer wakes from sleep.
Note: this doesn't get called when starting up.
static onSleep: () => void;
Set a callback for when your computer falls asleep.
Note: this doesn't get called when shutting down.
Get power info
static getBatteryInfo(): {
isCharging: boolean,
maxCapacity: number,
currentCapacity: number,
percent: number
};
Get information about the current battery life.
Idle & sleep
static userIdleTime(): number;
Returns the number of seconds since last user activity (keyboard, mouse, trackpad, etc).
static preventSleep(): () => void;
Prevents the computer from going into idle sleep until the returned function is called.
Control the brightness of your screen.
staticgetLevel
staticsetLevel
static getLevel(): number;
Returns the current brightness, between 0.0 and 1.0
static setLevel(brightness: number): void;
Sets the current brightness, between 0.0 and 1.0
Persist data between launches.
length: number;
Returns the number of key/value pairs currently present in the list associated with the object.
clear(): void;
Empties the list associated with the object of all key/value pairs, if there are any.
getItem(key: string): JSONValue | null;
value = storage[key]
removeItem(key: string): void;
delete storage[key]
setItem(key: string, value: JSONValue): void;
storage[key] = value
For logging and inspecting data.
log(...args: any[]): void;
Add values into the console.
clear(): void;
Resets all the logs in the console.
Global utility functions.
Modularizing your scripts
alert(msg: any, duration: number = 2): void;
Show msg for `duration` seconds in the middle of the screen.
Modularizing your scripts
require(path: string): any;
Load a file at the relative or absolute path. Tilde (~) represents $HOME.
Returns any value set by module.exports in that file, if any.
Scheduling functions
setTimeout(
fn: () => void,
delay: number
): number;
Run the function after [delay] milliseconds. Returns a unique ID suitable for clearTimeout.
setInterval(
fn: () => void,
delay: number
): number;
Run the function ever [delay] milliseconds. Returns a unique ID suitable for clearInterval.
clearTimeout(id: number): void;
Cancel the scheduled function.
clearInterval(id: number): void;
Cancel the recurring function.
Functionality specific to Autumn.app.
static showWindow(): void;
Show this window, and make Autumn the focused app.
static reloadUserScripts(): void;
This also resets the JavaScript VM and removes all callbacks.
static stop(): void;
Stop all callbacks and scripts, reset the JavaScript VM, and remove all callbacks.
The same as pressing the Stop button in the main window.
static setStatusMenuItems(items: Array<{
title: string,
onClick?: () => void
}>): void;
Adds menu items to the status item icon's menu that's visible when you hide the Dock icon in Preferences.
Each item requires at least a title, but usually also have an onClick handler.
To create a separator, pass "-" (dash) as the title and omit onClick.
{ x, y, width, height }
You don't usually need to use this class since all methods take a RectLike instead of a Rect, but it can be convenient if you need its methods.
static empty(): Rect;
Returns a rect with all zero fields.
static from(rect: { x: number, y: number, width: number, height: number }): Rect;
x: number;
y: number;
width: number;
height: number;
equals(b: RectLike): boolean;
Derived attributes
leftX: number;
topY: number;
rightX: number;
bottomY: number;
centerX: number;
centerY: number;
centerPoint: Point;
Querying attributes
isEmpty: boolean;
isValid: boolean;
True if none of its numbers are NaN or Infinity.
intersects(other: RectLike): boolean;
contains(rect: RectLike): boolean;
containsPoint(point: PointLike): boolean;
Deriving new rects
union(other: RectLike): Rect;
intersection(other: RectLike): Rect;
inset(x: number, y?: number = x): Rect;
offset(x: number, y: number): Rect;
integralRect(): Rect
{ x, y }
You don't usually need to use this class since all methods take a PointLike instead of a Point, but it can be convenient if you need its methods.
static empty(): Point;
Returns a point with all zero fields.
static from(point: { x: number, y: number }): Point;
x: number;
y: number;
equals(other: PointLike): boolean;
isValid: boolean;
True if none of its numbers are NaN or Infinity.
offset(x: number, y: number): Point;
minus(other: PointLike): Point;
plus(other: PointLike): Point;
{ width, height }
You don't usually need to use this class since all methods take a SizeLike instead of a Size, but it can be convenient if you need its methods.
static empty(): Size;
Returns a size with all zero fields.
static from(size: { width: number, height: number }): Size;
width: number;
height: number;
equals(other: SizeLike): boolean;
isValid: boolean;
True if none of its numbers are NaN or Infinity.
resizedBy(w: number, h: number): Size;
Interface version of Rect
This is an interface, so any JavaScript object containing these keys is conformant, most notably Rect.
x: number;
y: number;
width: number;
height: number;
Interface version of Point
This is an interface, so any JavaScript object containing these keys is conformant, most notably Point, Rect, and RectLike.
x: number;
y: number;
Interface version of Size
This is an interface, so any JavaScript object containing these keys is conformant, most notably Size, Rect, and RectLike.
width: number;
height: number;