1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
|
<html>
<head>
<title>Skencil User's Guide: Common Tasks</title>
</head>
<body bgcolor=white text=black link=blue vlink=navy alink=red>
<TABLE WIDTH="100%">
<TR>
<TH ALIGN="left" WIDTH="33%"><img SRC="Images/arrow-left.png" WIDTH="16" HEIGHT="16" ALIGN="top" ALT="Prev"></TH>
<TH ALIGN="center" WIDTH="33%"><img SRC="Images/arrow-up.png" WIDTH="16" HEIGHT="16" ALIGN="top" ALT="Up"></TH>
<TH ALIGN="right" WIDTH="33%"><img SRC="Images/arrow-right.png" WIDTH="16" HEIGHT="16" ALIGN="top" ALT="Next"></TH>
</TR>
<TR>
<TD ALIGN="left"><A HREF="usersguide-9.html">Skencil's API
</A></TD>
<TD ALIGN="center"><A HREF="usersguide-5.html">User Scripting
</A></TD>
<TD ALIGN="right"></TD>
</TR>
</TABLE>
<HR NOSHADE>
<H2><FONT face="Helvetica,Arial"><A NAME="N1"></A>Common Tasks</font></H2>
<P>Unless otherwise noted, all functions and classes mentioned here are
directly accessible from the <CODE>Sketch</CODE> package. E.g. the <tt>CreateRGBColor</tt> function is accessible either with:
<table width="100%" cellpadding="10"><tr><td bgcolor="#FFFFD0">
<PRE>
import Sketch
blue = Sketch.CreateRGBColor(0, 0, 1)
</PRE>
</td></tr></table>
</P>
<P>or</P>
<P>
<table width="100%" cellpadding="10"><tr><td bgcolor="#FFFFD0">
<PRE>
from Sketch import CreateRGBColor
blue = CreateRGBColor(0, 0, 1)
</PRE>
</td></tr></table>
</P>
<H3><FONT face="Helvetica,Arial"><A NAME="N2"></A>Creating Objects</font></H3>
<P>Creating new objects for a drawing, usually takes three steps:</P>
<P>
<OL>
<LI>Create the object. This is described in this section.</LI>
<LI>Set graphics properties like fill color or line width.
This is described <A HREF="#N19">below</A>.</LI>
<LI>Insert the object into the document</LI>
</OL>
</P>
<H4><FONT face="Helvetica,Arial"><A NAME="N3"></A>Primitives</font></H4>
<H5><FONT face="Helvetica,Arial"><A NAME="N4"></A>Rectangles</font></H5>
<P><A NAME="N5"></A><tt>Rectangle(<i>trafo</i>)</tt></P>
<P>This function creates a rectangle object described by <i>trafo</i>.
<i>trafo</i> is an affine transformation (represented by a <A HREF="devguide-7.html">a transformation object</A> that transforms the
unit square into the desired rectangle.</P>
<P>Transformation objects are created by the functions <A HREF="devguide-7.html#N3"><tt>Trafo</tt></A>, <A HREF="devguide-7.html#N4"><tt>Scale</tt></A>, <A HREF="devguide-7.html#N6"><tt>Rotation</tt></A> and
<A HREF="devguide-7.html#N5"><tt>Translation</tt></A>. </P>
<P>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:</P>
<P>
<table width="100%" cellpadding="10"><tr><td bgcolor="#FFFFD0">
<PRE>
Rectangle(Trafo(width, 0, 0, height, x, y))
</PRE>
</td></tr></table>
</P>
<P>or like this</P>
<P>
<table width="100%" cellpadding="10"><tr><td bgcolor="#FFFFD0">
<PRE>
Rectangle(Translation(x, y)(Scale(width, height)))
</PRE>
</td></tr></table>
</P>
<H5><FONT face="Helvetica,Arial"><A NAME="N6"></A>Lines and Curves</font></H5>
<P>All line and curve-objects in Skencil are instances of the <tt>PolyBezier</tt> class. Each <tt>PolyBezier</tt> object consists of one
or more paths with each path consisting of one or more line or
bézier segments.</P>
<P>To create a <tt>PolyBezier</tt> object you have to first create the paths
and then the <tt>PolyBezier</tt> instance. A path is created by starting
with an empty path returned by the <A HREF="devguide-8.html#N3"><tt>CreatePath</tt></A> function
and then appending line- and curve-segments to construct the path. How
paths are constructed is covered in detail in the <A HREF="devguide-8.html">corresponding section in the developer's guide</A>.</P>
<P>Once you have constructed your paths, you create the <tt>PolyBezier</tt> instance with:</P>
<P><A NAME="N7"></A><tt>PolyBezier(<i>path_tuple</i>)</tt></P>
<P>The argument <i>path_tuple</i> must be a tuple of paths. If you have just
one path <CODE>path</CODE>, you can use the expression <CODE>(path,)</CODE>.</P>
<P>For an example, see the sample script <tt>create_star.py</tt>.</P>
<H5><FONT face="Helvetica,Arial"><A NAME="N8"></A>Text</font></H5>
<P>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
<tt>SimpleText</tt>:</P>
<P><A NAME="N9"></A><tt>SimpleText(<i>trafo</i>, <i>text</i>)</tt></P>
<P>Create a simple text object with the text string <i>text</i>. The
position and orientation is given by <i>trafo</i>, a <A HREF="devguide-7.html">a transformation object</A>.</P>
<P>For an example, see the sample scripts <tt>create_text.py</tt>.</P>
<H4><FONT face="Helvetica,Arial"><A NAME="N10"></A>Compound Objects</font></H4>
<H5><FONT face="Helvetica,Arial"><A NAME="N11"></A>Groups</font></H5>
<P>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:</P>
<P><A NAME="N12"></A><tt>Group(<i>children</i>)</tt></P>
<P>Create a group object with the objects in the list <i>children</i> as
children. The children must not be contained in a document.</P>
<P>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 <tt>GroupSelected</tt>.
Like all document methods this method takes care of undo itself.</P>
<H4><FONT face="Helvetica,Arial"><A NAME="N13"></A>Inserting the Object into the Document</font></H4>
<P>You can insert an object into the document with this document method:</P>
<P>
<DL>
<DT><B><A NAME="N14"></A><tt>Insert(<i>object</i>)</tt></B><DD>
<P>Insert the object <i>object</i> into the document. The object
becomes the topmost object in the current layer. The selection
is set to just this object.</P>
</DL>
</P>
<H3><FONT face="Helvetica,Arial"><A NAME="N15"></A>Manipulating Objects</font></H3>
<P>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 <tt>AddUndo</tt> method if your script is an <A HREF="usersguide-6.html#N4">advanced script</A>.</P>
<H4><FONT face="Helvetica,Arial"><A NAME="N16"></A>Transformations</font></H4>
<P>Objects have two methods that allow you move and transform them.</P>
<P><A NAME="N17"></A><tt>Translate(<i>offset</i>)</tt></P>
<P>Move the object by <i>offset</i>. <i>offset</i> must be a <A HREF="devguide-5.html">point object</A>. For an example, see the sample
scripts <tt>abut_horizontal.py</tt> and <tt>abut_vertical.py</tt>.</P>
<P><A NAME="N18"></A><tt>Transform(<i>trafo</i>)</tt></P>
<P>Apply the affine transformation <i>trafo</i> to the object.</P>
<H4><FONT face="Helvetica,Arial"><A NAME="N19"></A>Changing Object Properties
</font></H4>
<P>Properties define how an object looks, i.e. they define the fill and
line styles and fonts.</P>
<P>The fill is defined by a pattern object. There are several kinds of
pattern types:</P>
<P>
<DL>
<DT><B><CODE>EmptyPattern</CODE></B><DD>
<P>The <CODE>EmptyPattern</CODE> is a predefined object that means the
object is not filled.</P>
<DT><B><A NAME="N20"></A><tt>SolidPattern(<i>color</i>)</tt></B><DD>
<P>Return a solid pattern object for color <i>color</i>. The solid
pattern fills the object uniformly.</P>
<P><i>color</i> has to be a color object which can be created with
the following function:</P>
<P><A NAME="N21"></A><tt>CreateRGBColor(<i>red</i>, <i>green</i>,
<i>blue</i>)</tt></P>
<P>which returns a color object for the color given by the RGB
components <i>red</i>, <i>green</i>, <i>blue</i> which are floats
in the range 0 - 1.</P>
<P>There are also some predefined color objects for some standard
colors. They are attributes of the <CODE>StandardColors</CODE> object,
e.g. <CODE>StandardColors.blue</CODE> is blue.</P>
</DL>
</P>
<P>There are more pattern like gradients which I haven't documented yet.</P>
<P>To set the properties of an object, call this method</P>
<P>
<DL>
<DT><B><A NAME="N22"></A><tt>SetProperties(<i>keyword_arguments</i>)</tt></B><DD>
<P>Set the properties described by the keyword arguments and return
undo information. The accepted keyword arguments are</P>
<P>
<DL>
<DT><B>fill_pattern</B><DD>
<P>The fill pattern. It can be of any pattern type.</P>
<DT><B>fill_transform</B><DD>
<P>A boolean (i.e. 0 or 1) that defines whether the pattern
is transformed as well if the object is transformed.</P>
<DT><B>line_pattern</B><DD>
<P>The pattern for the outline. Must be either
<CODE>EmptyPattern</CODE> or a <tt>SolidPattern</tt>. If
it's <CODE>EmptyPattern</CODE>, no outline is drawn.</P>
<DT><B>line_width</B><DD>
<P>The line width as a float in pt.</P>
<DT><B>line_cap</B><DD>
<P>The cap style. One of <CODE>CapButt</CODE>, <CODE>CapRound</CODE> or
<CODE>CapProjecting</CODE>. These constants are defined in
<CODE>Sketch.const</CODE></P>
<DT><B>line_join</B><DD>
<P>The join style. One of <CODE>JoinMiter</CODE>, <CODE>JoinRound</CODE> or
<CODE>JoinBevel</CODE>. These constants are defined in
<CODE>Sketch.const</CODE></P>
<DT><B>line_dashes</B><DD>
<P>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.</P>
<DT><B>line_arrow1</B><DD>
<DT><B>line_arrow2</B><DD>
<P>The arrow heads. Arrow heads are objects you can create
with the function <tt>Arrow</tt>.</P>
<DT><B>font</B><DD>
<P>The font for a text object. The value must be a font
object which you can get with the function <A NAME="N23"></A><tt>GetFont(<i>name</i>)</tt> where <i>name</i> is
the PostScript-name of the font.</P>
<DT><B>font_size</B><DD>
<P>The size of the font in pt.</P>
</DL>
</P>
</DL>
</P>
<H3><FONT face="Helvetica,Arial"><A NAME="N24"></A>Managing the Selection</font></H3>
<P>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:</P>
<P>
<DL>
<DT><B><A NAME="N25"></A><tt>HasSelection()</tt></B><DD>
<P>Return true if the selection is not empty.</P>
<DT><B><A NAME="N26"></A><tt>CountSelected()</tt></B><DD>
<P>Return the number of selected objects.</P>
<DT><B><A NAME="N27"></A><tt>SelectedObjects()</tt></B><DD>
<P>Return a list containing the currently selected objects.</P>
<DT><B><A NAME="N28"></A><tt>CurrentObject()</tt></B><DD>
<P>Return the currently selected object if exactly one object is
selected, return None otherwise.</P>
<DT><B><A NAME="N29"></A><tt>SelectNone()</tt></B><DD>
<P>Make the selection empty.</P>
<DT><B><A NAME="N30"></A><tt>SelectObject(<i>object</i>[,
<i>mode</i>])</tt></B><DD>
<P>If <i>mode</i> is <CODE>SelectSet</CODE>, make <i>object</i> the selected
object, otherwise, if <i>mode</i> is <CODE>SelectAdd</CODE>, add
<i>object</i> to the selection. <i>mode</i> defaults to
<CODE>SelectSet</CODE>.</P>
<P><i>object</i> may be a single object or a list of objects.</P>
<DT><B><A NAME="N31"></A><tt>DeselectObject(<i>object</i>)</tt></B><DD>
<P>Remove <i>object</i> from the selection.</P>
</DL>
</P>
<HR NOSHADE>
<TABLE WIDTH="100%">
<TR>
<TD ALIGN="left"><A HREF="usersguide-9.html">Skencil's API
</A></TD>
<TD ALIGN="center"><A HREF="usersguide-5.html">User Scripting
</A></TD>
<TD ALIGN="right"></TD>
</TR>
<TR>
<TH ALIGN="left" WIDTH="33%"><img SRC="Images/arrow-left.png" WIDTH="16" HEIGHT="16" ALIGN="top" ALT="Prev"></TH>
<TH ALIGN="center" WIDTH="33%"><img SRC="Images/arrow-up.png" WIDTH="16" HEIGHT="16" ALIGN="top" ALT="Up"></TH>
<TH ALIGN="right" WIDTH="33%"><img SRC="Images/arrow-right.png" WIDTH="16" HEIGHT="16" ALIGN="top" ALT="Next"></TH>
</TR>
</TABLE>
</body>
</html>
|
