S c r i p t s

Sketch's API

If you want to write scripts for Sketch you have to know how to access the objects in the document and how to manipulate them. This section gives a brief introduction to the structure of Sketch's modules and objects from script author's point of view.

A more detailed description of Sketch's internals can be found in the Developer's Guide.

Module Structure

Sketch's code is organized in a hierarchy of packages. The top-level package that contains all of Sketch's core components is Sketch. It directly contains references to most of Sketch's graphics classes and functions.

Conventions

Sketch's objects have methods that are meant for public use and methods for internal purposes. Naturally, a script is expected to only use the public interface. Since Python has no builtin distinction between public and private/protected methods we have to rely on conventions.

Sketch uses a naming convention for this. Methods with capitalized names, e.g. "SetRadius", are public methods and Methods with lowercase name, e.g. "set_radius", are protected.

Undo Handling

As pointed out above, advanced scripts have to deal with undo information. This isn't difficult, but you have to know which methods return undo information and what you have to do with it.

You only have to deal with undo info if you modify an object that is part of a document. These objects include instances of classes derived from GraphicsObject (class hierarchy) and the objects that define the properties of a graphics object, like patterns.

All methods that modify such an object return an undo info object. What this object looks like is irrelevant here, all you need to know for now is that you have to pass it immediately on to the document method AddUndo.

A typical example:

context.document.AddUndo(object.Translate(offset))

The Translate method translates an object by offset, a point object that stands for a 2D-vector.

There are some exceptions to the rule that methods that modify the document return undo info.

Firstly, the document methods that modify the selection, that is, that modify which objects are selected not the selected objects themselves, don't return undo info because changing the selection is not considered changing the document.

Secondly, public document methods that modify the selected objects themselves already take care of undo info themselves. The reason for this is that they are called directly as a result of a menu command, button or key-press event.

For more information about undo information in Sketch, have a look at the corresponding section in the Developer's Guide.

Further Information

The example scripts in the Script directory contain extensive comments on what's going on.

The Developer's Guide covers Sketch's internals in more detail. Although it's incomplete it already contains a lot of information about the structure of Sketch's sources, the class hierarchy and some of the base classes, coordinate systems, plugins and more.

And, of course: Use The Source, Luke!

P r e v i o u s p a g e S u m m a r y N e x t p a g e