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
|
<html>
<head>
<title>Skencil User's Guide: Skencil's API
</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-8.html">The Script Registry
</A></TD>
<TD ALIGN="center"><A HREF="usersguide-5.html">User Scripting
</A></TD>
<TD ALIGN="right"><A HREF="usersguide-10.html">Common Tasks</A></TD>
</TR>
</TABLE>
<HR NOSHADE>
<H2><FONT face="Helvetica,Arial"><A NAME="N1"></A>Skencil's API
</font></H2>
<P>If you want to write scripts for Skencil 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 Skencil's modules and
objects from script author's point of view.</P>
<P>A more detailed description of Skencil's internals can be found in the
<A HREF="devguide.html">Developer's Guide</A>.</P>
<H3><FONT face="Helvetica,Arial"><A NAME="N2"></A>Module Structure</font></H3>
<P>Skencil's code is organized in a hierarchy of packages. The top-level
package that contains all of Skencil's core components is <CODE>Sketch</CODE>.
It directly contains references to most of Skencil's graphics classes and
functions.</P>
<H3><FONT face="Helvetica,Arial"><A NAME="N3"></A>Conventions</font></H3>
<P>Skencil'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. </P>
<P>Skencil uses a naming convention for this. Methods with capitalized
names, e.g. "<CODE>SetRadius</CODE>", are public methods and Methods with
lowercase name, e.g. "<CODE>set_radius</CODE>", are protected.</P>
<H3><FONT face="Helvetica,Arial"><A NAME="N4"></A>Undo Handling</font></H3>
<P>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.</P>
<P>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 <A HREF="devguide-11.html#N2"><tt>GraphicsObject</tt></A> (<A HREF="devguide-10.html">class hierarchy</A>) and the objects that
define the properties of a graphics object, like patterns.</P>
<P>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
<tt>AddUndo</tt>.</P>
<P>A typical example:
<table width="100%" cellpadding="10"><tr><td bgcolor="#FFFFD0">
<PRE>
context.document.AddUndo(object.Translate(offset))
</PRE>
</td></tr></table>
</P>
<P>The <A HREF="devguide-11.html#N8"><tt>Translate</tt></A> method translates
an object by <CODE>offset</CODE>, a <A HREF="devguide-5.html">point
object</A> that stands for a 2D-vector.</P>
<P>There are some exceptions to the rule that methods that modify the
document return undo info. </P>
<P>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.</P>
<P>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.</P>
<P>For more information about undo information in Skencil, have a look at
the <A HREF="devguide-19.html">corresponding section</A> in the
Developer's Guide.</P>
<H3><FONT face="Helvetica,Arial"><A NAME="N5"></A>Further Information</font></H3>
<P>The example scripts in the <tt>Script</tt> directory contain extensive
comments on what's going on.</P>
<P>The <A HREF="devguide.html">Developer's Guide</A> covers Skencil's
internals in more detail. Although it's incomplete it already contains a
lot of information about the structure of Skencil's sources, the class
hierarchy and some of the base classes, coordinate systems, plugins and
more.</P>
<P>And, of course: Use The Source, Luke!</P>
<HR NOSHADE>
<TABLE WIDTH="100%">
<TR>
<TD ALIGN="left"><A HREF="usersguide-8.html">The Script Registry
</A></TD>
<TD ALIGN="center"><A HREF="usersguide-5.html">User Scripting
</A></TD>
<TD ALIGN="right"><A HREF="usersguide-10.html">Common Tasks</A></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>
|
