Prev
Up
Next
usersguide-9.html
Skencil's API
usersguide-5.html
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:
Create the object. This is described in this section.
Set graphics properties like fill color or line width.
This is described
#N19
below
.
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
devguide-7.html
a transformation object
that transforms the
unit square into the desired rectangle.
Transformation objects are created by the functions
devguide-7.html#N3
Trafo
,
devguide-7.html#N4
Scale
,
devguide-7.html#N6
Rotation
and
devguide-7.html#N5
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
devguide-8.html#N3
CreatePath
function
and then appending line- and curve-segments to construct the path. How
paths are constructed is covered in detail in the
devguide-8.html
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
devguide-7.html
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
usersguide-6.html#N4
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
devguide-5.html
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.
usersguide-9.html
Skencil's API
usersguide-5.html
User Scripting
Prev
Up
Next
