Skencil's API | User Scripting |

## Common Tasks

Unless otherwise noted, all functions and classes mentioned here are directly accessible from the `Sketch` package. E.g. the `CreateRGBColor` function is accessible either with:

    import Sketch

    blue = Sketch.CreateRGBColor(0, 0, 1)

or

    from Sketch import CreateRGBColor

    blue = CreateRGBColor(0, 0, 1)

### Creating Objects

Creating new objects for a drawing, usually takes three steps:

1. Create the object. This is described in this section.
2. Set graphics properties like fill color or line width. This is described below.
3. Insert the object into the document

#### Primitives

##### Rectangles

`Rectangle(trafo)`

This function creates a rectangle object described by trafo. trafo is an affine transformation (represented by a a transformation object that transforms the unit square into the desired rectangle.

Transformation objects are created by the functions `Trafo`, `Scale`, `Rotation` and `Translation`.

In the most common case where you want to create a rectangle with a specific width and height at a specific position (x, y) (the position of the lower left corner of the rectangle) and edges parallel to the edges of the page, you could create the rectangle like this:

    Rectangle(Trafo(width, 0, 0, height, x, y))

or like this

    Rectangle(Translation(x, y)(Scale(width, height)))

##### Lines and Curves

All line and curve-objects in Skencil are instances of the `PolyBezier` class. Each `PolyBezier` object consists of one or more paths with each path consisting of one or more line or bézier segments.

To create a `PolyBezier` object you have to first create the paths and then the `PolyBezier` instance. A path is created by starting with an empty path returned by the `CreatePath` function and then appending line- and curve-segments to construct the path. How paths are constructed is covered in detail in the corresponding section in the developer's guide.

Once you have constructed your paths, you create the `PolyBezier` instance with:

`PolyBezier(path_tuple)`

The argument path_tuple must be a tuple of paths. If you have just one path `path`, you can use the expression `(path,)`.

For an example, see the sample script `create_star.py`.

##### Text

Skencil's text capabilities are still very simple. A text object consists of just one line of text in one font and size, hence the class is called `SimpleText`:

`SimpleText(trafo, text)`

Create a simple text object with the text string text. The position and orientation is given by trafo, a a transformation object.

For an example, see the sample scripts `create_text.py`.

#### Compound Objects

##### Groups

Creating a normal group is very simple. First, you have to construct a list of the objects to be contained in the group. Then you just call the constructor:

`Group(children)`

Create a group object with the objects in the list children as children. The children must not be contained in a document.

If you want to create a group of objects that are already contained in the document, the easiest way is to make sure those objects are selected and then to call the document method `GroupSelected`. Like all document methods this method takes care of undo itself.

#### Inserting the Object into the Document

You can insert an object into the document with this document method:

`Insert(object)`

  Insert the object object into the document. The object becomes the topmost object in the current layer. The selection is set to just this object.

### Manipulating Objects

Once you have created a graphics object or you have a reference to an object in the document, perhaps from the selection, you can manipulate them in various ways. All methods that modify an object in place return undo information which you have to pass to the document's `AddUndo` method if your script is an advanced script.

#### Transformations

Objects have two methods that allow you move and transform them.

`Translate(offset)`

Move the object by offset. offset must be a point object. For an example, see the sample scripts `abut_horizontal.py` and `abut_vertical.py`.

`Transform(trafo)`

Apply the affine transformation trafo to the object.

#### Changing Object Properties

Properties define how an object looks, i.e. they define the fill and line styles and fonts.

The fill is defined by a pattern object. There are several kinds of pattern types:

`EmptyPattern`

  The `EmptyPattern` is a predefined object that means the object is not filled.

`SolidPattern(color)`

  Return a solid pattern object for color color. The solid pattern fills the object uniformly.

  color has to be a color object which can be created with the following function:

  `CreateRGBColor(red, green, blue)`

  which returns a color object for the color given by the RGB components red, green, blue which are floats in the range 0 - 1.

  There are also some predefined color objects for some standard colors. They are attributes of the `StandardColors` object, e.g. `StandardColors.blue` is blue.

There are more pattern like gradients which I haven't documented yet.

To set the properties of an object, call this method

`SetProperties(keyword_arguments)`

  Set the properties described by the keyword arguments and return undo information. The accepted keyword arguments are

  fill_pattern

    The fill pattern. It can be of any pattern type.

  fill_transform

    A boolean (i.e. 0 or 1) that defines whether the pattern is transformed as well if the object is transformed.

  line_pattern

    The pattern for the outline. Must be either `EmptyPattern` or a `SolidPattern`. If it's `EmptyPattern`, no outline is drawn.

  line_width

    The line width as a float in pt.

  line_cap

    The cap style. One of `CapButt`, `CapRound` or `CapProjecting`. These constants are defined in `Sketch.const`

  line_join

    The join style. One of `JoinMiter`, `JoinRound` or `JoinBevel`. These constants are defined in `Sketch.const`

  line_dashes

    The dash-pattern as a tuple of floats. The items of the tuple define the dashes and gaps terms of the line-width. The number of items in the tuple should be even.

  line_arrow1
  line_arrow2

    The arrow heads. Arrow heads are objects you can create with the function `Arrow`.

  font

    The font for a text object. The value must be a font object which you can get with the function `GetFont(name)` where name is the PostScript-name of the font.

  font_size

    The size of the font in pt.

### Managing the Selection

In Skencil 0.6.x, the selection is managed by the document object. You can use these document methods to query and change the selection:

`HasSelection()`

  Return true if the selection is not empty.

`CountSelected()`

  Return the number of selected objects.

`SelectedObjects()`

  Return a list containing the currently selected objects.

`CurrentObject()`

  Return the currently selected object if exactly one object is selected, return None otherwise.

`SelectNone()`

  Make the selection empty.

`SelectObject(object[, mode])`

  If mode is `SelectSet`, make object the selected object, otherwise, if mode is `SelectAdd`, add object to the selection. mode defaults to `SelectSet`.

  object may be a single object or a list of objects.

`DeselectObject(object)`

  Remove object from the selection.

Skencil's API | User Scripting |