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
|
<html>
<head>
<title>Developer's Guide: Import Filters
</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="devguide-21.html">Plugin Configuration</A></TD>
<TD ALIGN="center"><A HREF="devguide-20.html">Plugins
</A></TD>
<TD ALIGN="right"><A HREF="devguide-23.html">Export Filters
</A></TD>
</TR>
</TABLE>
<HR NOSHADE>
<H2><FONT face="Helvetica,Arial"><A NAME="N1"></A>Import Filters
</font></H2>
<P>Sketch uses import filters to read vector drawings from files.</P>
<H3><FONT face="Helvetica,Arial"><A NAME="N2"></A>Configuration Variables
</font></H3>
<P>For import filter configuration, Sketch uses the following variables:
<DL>
<DT><B><CODE>type</CODE></B><DD>
<P>The type must be <CODE>Import</CODE>. This identifier is defined in the
globals() dictionary.</P>
<DT><B><A NAME="N3"></A>
<CODE>class_name</CODE></B><DD>
<P>A string containing the name of a Python class defined in the
module. See below for the interface this class has to provide.</P>
<DT><B> <A NAME="N4"></A>
<CODE>rx_magic</CODE></B><DD>
<P>A string containing a regular expression suitable for the re
module. This regular expression is matched against the first
line of the file. if it matches, the import mechanism assumes
that the filter understands the file's format and then procedes
to use that filter to load the file. So, if possible, this
regular expression should match those files the filter can
handle and only those.</P>
<P>While this method of identifying files is not really sufficient
to handle all file types, it works well enough for now. In the
future we will probably have to extend this mechanism.</P>
<DT><B><CODE>tk_file_type</CODE></B><DD>
<P>A tuple containing two elements. The first is the name of the
file format presented to the user in the file open dialog. The
second element is eithe a string or a tuple of strings. Each of
the strings defines a file name extension used for that
filename.</P>
<P>Examples:</P>
<P><CODE>#tk_file_type = ('Sketch Document', '.sk')</CODE></P>
<P><CODE>#tk_file_type = ('PostScript file', ('.ps', '.eps'))</CODE></P>
<DT><B> <A NAME="N5"></A>
<CODE>unload</CODE> (optional)</B><DD>
<P>A boolean. True means that the filter module should be unloaded
after use, false means that it shouldn't be unloaded. If the
module is unloaded it will be imported again the next time the
filter is needed. Infrequently used filters should set this to
true, frequently used filters (like the filter for Sketch's own
format) should set it to true.</P>
<P>If omitted, it defaults to false.</P>
<P>It's a good idea to set this variable to true at least while
developing a filter because that way the filter will be
automatically reloaded when the source file changes.</P>
<DT><B><CODE>format_name</CODE></B><DD>
<P>The name of the format as a string. This name is currently used
internally to find out whether a document was loaded from a file
in Sketch's format or from a different format (in the latter
case `Save' is treated like `Save As...', i.e. the user has to
provide a filename).</P>
<DT><B><CODE>standard_messages</CODE> (optional)</B><DD>
<P>A boolean indicating whether the messages in the plugin are
standard messages that are defined in Sketch's message catalogs.
For third-party plugins this should be omitted.</P>
</DL>
</P>
<H3><FONT face="Helvetica,Arial"><A NAME="N6"></A>The Class Interface</font></H3>
<H4><FONT face="Helvetica,Arial"><A NAME="N7"></A>External Interface</font></H4>
<P>The interface a loader class presents to the document loading mechanism
is quite simple. The loading mechanism works roughly as follows:</P>
<P>
<OL>
<LI>Read the first line of the file
</LI>
<LI>Match it in turn against all the regular expressions
defined for import filter plugins (defined by the <A HREF="#N4">rx_magic variable</A>).
</LI>
<LI>If a match is found, instantiate the plugin's class
(defined by the <A HREF="#N3">class_name variable</A>) with
three positional parameters <i>file</i>, <i>filename</i> and
<i>match</i>.
<i>file</i> is the open input file object, positioned just after
the first line.
<i>filename</i> is the name of the file.
<i>match</i> is the match-object returned from regular expression
match.
If possible, filters should read the input file sequentially and
not use seeks. Sketch automatically pipes gzipped files
through gzip and in that case the file object is actually a
pipe, so seeks would be impossible. If a filter needs to access
the first line it can do so by using <i>match</i>.string or by
defing suitable groups in the regular expression.
</LI>
<LI>Call the instance's Load() method (without arguments).
This method does the actual work and returns an instance of the
document class.
</LI>
<LI>Call the instance's Messages() method without arguments.
The return value is expected to be a list of strings with
messages that are usually presented to the user by the UI.
</LI>
<LI>If the <A HREF="#N5">unload configuration
variable</A> is true, unload the plugin's module.</LI>
</OL>
</P>
<H4><FONT face="Helvetica,Arial"><A NAME="N8"></A>Common Base Classes</font></H4>
<P>To make things easier, Sketch defines some base classes that plugins
can inherit, <tt>LoaderWithComposites</tt> and, derived from
that, <A HREF="#N10"><tt>GenericLoader</tt></A> and <tt>SimplifiedLoader</tt>, derived in turn from <tt>GenericLoader</tt>.</P>
<H5><FONT face="Helvetica,Arial"><A NAME="N9"></A><A NAME="N10"></A><tt>GenericLoader</tt></font></H5>
<P>The class <tt>GenericLoader</tt> provides a default implementation of the
constructor, a mechanism for warning and error messages and methods to
easily create standard objects like rectangles, ellipses and groups.</P>
<P><tt>GenericLoader</tt> defines these methods:</P>
<P>
<DL>
<DT><B><A NAME="N11"></A><tt>__init__(<i>file</i>, <i>filename</i>, <i>match</i>)</tt></B><DD>
<P>Assign the arguments to <CODE>self.file</CODE>, <CODE>self.filename</CODE> and
<CODE>self.match</CODE> respectively.</P>
<DT><B><A NAME="N12"></A><tt>document()</tt></B><DD>
<P>Start the construction of a document. This method must be called
before any other of the object creation methods are called.</P>
<DT><B><A NAME="N13"></A><tt>layer([<i>name</i>])</tt></B><DD>
<P>Start a new layer. This method must be called after calling
<A HREF="#N12"><tt>document</tt></A> and before any of the other object
creation methods. </P>
<P><i>name</i> is the name of the layer. If omitted, it defaults to
"Layer 1".</P>
<DT><B><A NAME="N14"></A><tt>begin_group()</tt></B><DD>
<P>Start a new group. Groups can be arbitrarily nested. Each call
to <tt>begin_group</tt> must have a corresponding call to <A HREF="#N15"><tt>end_group</tt></A>.</P>
<DT><B><A NAME="N15"></A><tt>end_group()</tt></B><DD>
<P>End the current group.</P>
<DT><B><A NAME="N16"></A><tt>rectangle(<i>m11</i>, <i>m21</i>,
<i>m12</i>, <i>m22</i>, <i>v1</i>, <i>v2</i>[, <i>radius1</i> = 0][,
<i>radius2</i> =
0])</tt></B><DD>
<P>Create a new rectangle object and append it to the current
compound object.</P>
<P>The first six positional parameters (<i>m11</i>, <i>m21</i>,
<i>m12</i>, <i>m22</i>, <i>v1</i>, <i>v2</i>) define a
transformation matrix that transforms the unit square (opposite
corners (0,0) and (1,1)) onto the rectangle.</P>
<P><i>radius1</i> and <i>radius2</i> define the rounded corners.</P>
<P>For more details see the documentation for the class <A HREF="devguide-18.html#N2"><tt>Rectangle</tt></A></P>
<DT><B><A NAME="N17"></A><tt>ellipse(<i>m11</i>, <i>m21</i>,
<i>m12</i>, <i>m22</i>, <i>v1</i>, <i>v2</i>[,
<i>start_angle</i> = 0.0][, <i>end_angle</i> = 0.0][,
<i>arc_type</i> = ArcPieSlice])</tt></B><DD>
<P>Create a new ellipse object and append it to the current
compound object.</P>
<P>The first six positional parameters (<i>m11</i>, <i>m21</i>,
<i>m12</i>, <i>m22</i>, <i>v1</i>, <i>v2</i>) define a
transformation matrix that transforms the unit circle (center
(0,0) and radius 1) onto the ellipse.</P>
<P><i>start_angle</i> and <i>end_angle</i>, if given, define the
start end end angles for pie slices, arc and chords.</P>
<P><i>arc_type</i> defines whether and how the arc of an incomplete
ellipse is closed. Valid values are <CODE>ArcArc</CODE>,
<CODE>ArcPieSlice</CODE> and <CODE>ArcChord</CODE>. These constants are defined
in <CODE>Sketch.const</CODE></P>
<P>For more details see the documentation for the class <tt>Ellipse</tt></P>
<DT><B><A NAME="N18"></A><tt>bezier(<i>paths</i>)</tt></B><DD>
<P>Create a new bézier object in the current compound object.</P>
<P><i>paths</i> must be a tuple of <A HREF="devguide-8.html">curve
objects</A>.</P>
</DL>
</P>
<HR NOSHADE>
<TABLE WIDTH="100%">
<TR>
<TD ALIGN="left"><A HREF="devguide-21.html">Plugin Configuration</A></TD>
<TD ALIGN="center"><A HREF="devguide-20.html">Plugins
</A></TD>
<TD ALIGN="right"><A HREF="devguide-23.html">Export Filters
</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>
|
