Home Reference Source
import {Application} from './api/Application.js'
public class | source

Application

Extends:

WrappedObject → Application

Gives you access to Sketch, and provides access to:

  • the document model and the layer tree
  • metadata abound sketch itself
  • utilities for interacting with the user
  • access to the running plugin, it's resources and settings

Static Method Summary

Static Public Methods
public static

tests(): dictionary

Return a list of tests to run for this class.

Constructor Summary

Public Constructor
public

constructor(context: *): *

Construct a new Application object.

Member Summary

Public Members
public
public
public
public

Group: *

public

Image: *

public

Page: *

public
public
public

Shape: *

public

Style: *

public

Text: *

public get

The version of this API.

public get

build: *: *

The exact build of Sketch that is running.

public get

context: *: *

The context that the API was created in.

public get

Returns the full version of Sketch that is running

public get

The selected document.

public get

version: *: *

The version of Sketch that is running.

Method Summary

Public Methods
public

alert(title: string, message: string)

Show an alert with a custom title and message.

public

assert(condition: *)

Assert that a given condition is true.

public

getSelectionFromUser(msg: *, items: *, selectedItemIndex: *): *

Shows an input sheet which displays a popup with a series of options, from which the user is asked to choose.

public

getStringFromUser(msg: *, initial: *): *

Shows a simple input sheet which displays a message, and asks for a single string input.

public

log(message: string)

Output a message to the log console.

public

message(message: string)

Show a small, temporary, message to the user.

public

Create a new document and bring it to the front.

public

resourceNamed(name: *): *

Return a file URL pointing to a named resource in the plugin's Resources/ folder.

public

Run all of our internal unit tests.

public

setSettingForKey(key: *, value: *)

Set the value of a global setting for a given key.

public

settingForKey(key: *): *

Return the value of a global setting for a given key.

public

wrapObject(sketchObject: object, inDocument: Document): WrappedObject

Return a wrapped version of a Sketch object.

public

wrapperMappings(): dictionary

Return a lookup table of known mappings between Sketch model classes and our JS API wrapper classes.

Inherited Summary

From class WrappedObject
public static

tests(): dictionary

Return a list of tests to run for this class.

public get

id: string: *

Returns the object ID of the wrapped Sketch model object.

public get

Returns the wrapped Sketch object.

Static Public Methods

public static tests(): dictionary source

Return a list of tests to run for this class.

We could do some fancy introspection here to derive the tests from the class, but for now we're opting for the simple approach.

Return:

dictionary

A dictionary containing the tests to run. Each key is the name of a test, each value is a function which takes a Tester instance.

Public Constructors

public constructor(context: *): * source

Construct a new Application object. An instance of this class will be passed back to you when you initialise the API, so you generally shouldn't need to make new ones.

Params:

NameTypeAttributeDescription
context *

The context dictionary passed to the script when it was invoked.

Return:

*

A new Application object.

Public Members

public Application: * source

public Artboard: * source

public Document: * source

public Group: * source

public Image: * source

public Page: * source

public Rectangle: * source

public Selection: * source

public Shape: * source

public Style: * source

public Text: * source

public get api_version: *: string source

The version of this API.

Return:

*

A version string.

public get build: *: * source

The exact build of Sketch that is running.

Return:

*

The build number as a string, eg "15352".

public get context: *: * source

The context that the API was created in. This is the traditional context argument that is passed to all plugin scripts when they are run.

In general you should use the API to access Sketch rather than interacting with the context directly.

Return:

*

A context dictionary.

public get full_version: string: * source

Returns the full version of Sketch that is running

Return:

string

Version and build number as a string, eg "3.6 (15352)".

public get selectedDocument: *: * source

The selected document.

If the user invoked the script explicitly (for example by selecting a menu item), this will be the document that they were working in at the time - ie the frontmost one. If the script was invoked as an action handler, this will be the document that the action occurred in.

Return:

*

A Document object.

public get version: *: * source

The version of Sketch that is running.

Return:

*

The version as a string, eg "3.6".

Public Methods

public alert(title: string, message: string) source

Show an alert with a custom title and message.

Params:

NameTypeAttributeDescription
title string

The title of the alert.

message string

The text of the message.

The alert is modal, so it will stay around until the user dismisses it by pressing the OK button.

public assert(condition: *) source

Assert that a given condition is true. If the condition is false, throws an exception.

Params:

NameTypeAttributeDescription
condition *

An expression that is expected to evaluate to true if everything is ok.

public getSelectionFromUser(msg: *, items: *, selectedItemIndex: *): * source

Shows an input sheet which displays a popup with a series of options, from which the user is asked to choose.

Params:

NameTypeAttributeDescription
msg *

The prompt message to show.

items *

A list of option items.

selectedItemIndex *

The index of the item to select initially.

Return:

*

An array with two items: [responseCode, selection].

The result consists of a response code and a selection. The code will be one of NSAlertFirstButtonReturn or NSAlertSecondButtonReturn. The selection will be the integer index of the selected item.

public getStringFromUser(msg: *, initial: *): * source

Shows a simple input sheet which displays a message, and asks for a single string input.

Params:

NameTypeAttributeDescription
msg *

The prompt message to show.

initial *

The initial value of the input string.

Return:

*

The string that the user input.

public log(message: string) source

Output a message to the log console.

Params:

NameTypeAttributeDescription
message string

The message to output.

public message(message: string) source

Show a small, temporary, message to the user. The message appears at the bottom of the selected document, and is visible for a short period of time. It should consist of a single line of text.

Params:

NameTypeAttributeDescription
message string

The message to show.

public newDocument(): * source

Create a new document and bring it to the front.

Return:

*

The new document.

public resourceNamed(name: *): * source

Return a file URL pointing to a named resource in the plugin's Resources/ folder.

Params:

NameTypeAttributeDescription
name *

The resource file name, including any file extension.

Return:

*

The resource location, in the form "file://path/to/resource".

public runUnitTests(): * source

Run all of our internal unit tests. Returns a dictionary indicating how many tests ran, passed, failed, and crashed, and a list of more detailed information for each failure.

At some point we may switch to using Mocha or some other test framework, but for now we want to be able to invoke the tests from the Sketch side or from a plugin command, so it's simpler to use a simple test framework of our own devising.

Return:

*

public setSettingForKey(key: *, value: *) source

Set the value of a global setting for a given key.

Params:

NameTypeAttributeDescription
key *

The setting to set.

value *

The value to set it to.

This is equivalent to writing a setting for the currently running version of Sketch using the defaults command line tool, eg: defaults write com.bohemiancoding.sketch3 <key> <value>

public settingForKey(key: *): * source

Return the value of a global setting for a given key.

Params:

NameTypeAttributeDescription
key *

The setting to look up.

Return:

*

The setting value.

This is equivalent to reading a setting for the currently running version of Sketch using the defaults command line tool, eg: defaults read com.bohemiancoding.sketch3 <key>

public wrapObject(sketchObject: object, inDocument: Document): WrappedObject source

Return a wrapped version of a Sketch object. We don't know about all Sketch object types, but for some we will return a special subclass. The fallback position is just to return an instance of WrappedObject.

Params:

NameTypeAttributeDescription
sketchObject object

The underlying sketch object that we're wrapping.

inDocument Document

The wrapped document that this object is part of.

Return:

WrappedObject

A javascript object (subclass of WrappedObject), which represents the Sketch object we were given.

public wrapperMappings(): dictionary source

Return a lookup table of known mappings between Sketch model classes and our JS API wrapper classes.

Return:

dictionary

A dictionary with keys for the Sketch Model classes, and values for the corresponding API wrapper classes.

See something wrong or incomplete? Improve this page.