« back to all changes in this revision
Viewing changes to spath_doc.tex
- browse files at revision 43
- compare with another revision
- download diff
- download tarball
- view history from revision 43
- Committer: Andrew Stacey (Thargelion)
- Date: 2011-06-05 20:34:05 UTC
- Revision ID: stacey@math.ntnu.no-20110605203405-aozimho6cnnyyx29
Started to split off soft path manipulation stuff in to a separate style file, also reimplementing the code a bit
- files added:
- .bzrignore
- files removed:
- .bzrignore
- files modified:
- ChangeLog
added
removed
spath_doc.tex
1
\immediate\write18{tex spath.dtx}
2
\documentclass{ltxdoc}
3
\usepackage[T1]{fontenc}
4
\usepackage{lmodern}
5
\usepackage{morefloats}
6
\usepackage{tikz}
7
\usepackage{spath}
8
\usepackage[numbered]{hypdoc}
9
\definecolor{lstbgcolor}{rgb}{0.9,0.9,0.9}
10
11
\usepackage{listings}
12
\lstloadlanguages{[LaTeX]TeX}
13
\lstset{breakatwhitespace=true,breaklines=true,language=TeX}
14
15
\usepackage{fancyvrb}
16
17
\newenvironment{example}
18
{\VerbatimEnvironment
19
\begin{VerbatimOut}{example.out}}
20
{\end{VerbatimOut}
21
\begin{center}
22
\setlength{\parindent}{0pt}
23
\fbox{\begin{minipage}{.9\linewidth}
24
\lstset{breakatwhitespace=true,breaklines=true,language=TeX,basicstyle=\small}
25
\lstinputlisting[]{example.out}
26
\end{minipage}}
27
28
\fbox{\begin{minipage}{.9\linewidth}
29
\input{example.out}
30
\end{minipage}}
31
\end{center}
32
}
33
34
\providecommand*{\url}{\texttt}
35
\GetFileInfo{spath.sty}
36
37
\title{The \textsf{spath} Package: Documentation}
38
\author{Andrew Stacey \\ \url{stacey@math.ntnu.no}}
39
\date{\fileversion~from \filedate}
40
41
\begin{document}
42
43
\maketitle
44
45
\section{Introduction}
46
47
The \texttt{spath} library is an object-oriented interface to the \emph{soft path} system of PGF.
48
It allows one to save, manipulate, and use \emph{soft paths} in a more general way than is currently easy with TikZ/PGF.
49
This library was developed for use with the \texttt{calligraphy} package since that required various path manipulations that would have been hard to do otherwise.
50
51
There are several steps in the TikZ/PGF system between writing \Verb+\draw (0,0) -- (1,0);+ and a line appearing in the document.
52
The command just given is a TikZ command.
53
The TikZ frontend translates that into PGF commands.
54
These are then processed into a \emph{soft path}.
55
The soft path can be manipulated further before being ``baked'' into a hard path which is then written out into the output file via an appropriate driver.
56
57
A soft path is a simple object.
58
It consists of a list of tokens of the form \Verb+\pgfsyssoftpath@<something>token{x pt}{y pt}+\footnote{Except for the \Verb+closepath+ token which omits the final \Verb+token+.}.
59
There are only a handful of possible \Verb+<something>+s.
60
It is therefore quite straightforward to manipulate these paths in an orderly fashion.
61
However, the PGF code does not provide a particular method for doing complicated manipulations on these paths.
62
This library introduces some such methods.
63
64
One thing to note at the outset is that this library makes no attempt to optimise the code and so if the soft path is very long, it will take a considerable time to do any of these manipulations.
65
The PGF soft path system does have some optimisations to handle this.
66
67
\section{Usage}
68
69
Using this library is relatively straightforward.
70
After loading TikZ/PGF, simply \Verb+\usepackage{spath}+ in the preamble.
71
A typical example of using the library is in the following example.
72
73
\begin{example}
74
\begin{tikzpicture}
75
\useasboundingbox (-1,1) rectangle (2,-2);
76
\path[save path=\tmppath] (-1,0) -- (0,0) .. controls +(1,0) and +(1,0) .. (1,1);
77
\pgfoonew \mypath=new spath(\tmppath)
78
\mypath.prepare()
79
\mypath.reverse path()
80
\mypath.use path with tikz(draw)
81
\mypath.translate path(,0cm,-2cm)
82
\mypath.at least three()
83
\mypath.split path by real length(\fpath,\mpath,1)
84
\begin{scope}[ultra thick]
85
\fpath.taper out()
86
\fpath.use path with tikz(fill)
87
\mpath.split path by real length(\mmpath,\epath,-1)
88
\epath.reverse path()
89
\epath.taper out()
90
\epath.use path with tikz(fill)
91
\mmpath.use path with tikz(draw)
92
\end{scope}
93
\end{tikzpicture}
94
\end{example}
95
96
In this example, we start by defining a path in the usual TikZian manner.
97
However, instead of doing something with the path, we save it.
98
This saves the raw path as a macro.
99
In order to use this library on that path, we have to convert it into an \Verb+spath+ object.
100
This is done with the next line, starting \Verb+\pgfoonew+ (note the spacing: there must be no space after the \Verb+=+).
101
This command declares \Verb+\mypath+ to be an instance of the \Verb+spath+ class and initialises it with the path stored in \Verb+\tmppath+.
102
(For scoping reasons, we can't define a PGF key to be given to the original \Verb+\path+ command to do this in one go.)
103
This can now be manipulated with the \Verb+spath+ methods.
104
We shall explain the actual methods later so shall not go into detail now.
105
106
\section{Attributes and Methods}
107
108
The \texttt{spath} library defines two classes: the \Verb+spath+ and \Verb+spath component+.
109
The \Verb+spath+ is a soft path, the \Verb+spath component+ is an array of \Verb+spath+ objects.
110
111
\subsection{The \texttt{spath} Object}
112
113
The following is a list of the attributes that an \Verb+spath+ object has.
114
The class operates on a lazy system: attributes are not automatically worked out so they will not have values initially.
115
However, as soon as you do something that needs one to have a value it will be computed.
116
117
\begin{itemize}
118
\item \Verb+path+
119
120
This holds the actual soft path.
121
122
\item \Verb+length+
123
124
This (when initialised) is the length of the soft path in number of soft path tokens.
125
126
\item \Verb+real length+
127
128
This is the number of actual drawing tokens in the soft path; that is, the number of \Verb+lineto+ and \Verb+curveto+ tokens.
129
130
(This ought to also count \Verb+rect+, but I don't know of a TikZ command that actually produces a \Verb+rect+.)
131
132
\item \Verb+number of components+
133
134
This is the number of components of the path when divided up by \Verb+moveto+s.
135
It is actually the number of \Verb+moveto+s so successive \Verb+moveto+s will each count.
136
137
\item \Verb+initial point+
138
139
This is the coordinates of the start of the path.
140
It is of the form \Verb+\pgfpoint{x coordinate}{y coordinate}+ so when executed will set \Verb+\pgf@x+ and \Verb+\pgf@y+ to the corresponding coordinates.
141
142
\item \Verb+final point+
143
144
This is the coordinates of the end of the path.
145
146
\item \Verb+first action+
147
148
This is the first drawing action on the path (that is, not the initial \Verb+moveto+).
149
150
\item \Verb+last action+
151
152
This is the last action on the path (which might be a \Verb+moveto+).
153
154
\item \Verb+prepared+
155
156
The attributes are not calculated initially, but are calculated as needed.
157
There is a method available for calculating them all in one fell swoop.
158
If this has been called, this attribute is set so that the path knows its attributes have all be computed and don't need to be computed again.
159
160
\item \Verb+taper line width+
161
162
When tapering a path, it is necessary to set both the current line width and a width to taper to.
163
This holds the latter.
164
165
\end{itemize}
166
167
The following is a list of the methods available for an \Verb+spath+ object with a brief explanation of what each does.
168
The contents of the parentheses are the arguments for the method.
169
170
\begin{itemize}
171
\item \Verb+spath(#1)+
172
173
This is the creator method, it is called automatically when the object is created.
174
The argument, if given, is a macro containing a soft path which is used to set the \Verb+path+ attribute.
175
176
\item \Verb+value(#1)+
177
178
This method inserts the value of the attribute passed to it into the token stream.
179
180
\item \Verb+set(#1,#2)+
181
182
This method sets the attribute passed to it as the first argument to the second argument.
183
184
\item \Verb+let(#1,#2)+
185
186
This method lets the attribute passed to it as the first argument to be the second argument.
187
The second argument ought to be a macro, therefore.
188
189
\item \Verb+get(#1,#2)+
190
191
This method assigns the second argument to the value of the attribute passed to it as the first argument.
192
The second argument ought to be a macro, therefore.
193
194
\item \Verb+show(#1)+
195
196
This method shows the value of the attribute in the logs.
197
It uses \Verb+\show+ internally.
198
199
\item \Verb+clone(#1)+
200
201
This method clones the \Verb+spath+ object into the macro passed as the argument.
202
203
\item \Verb+translate path(#1,#2,#3)+
204
205
This method translates the path by \Verb+#2+ in the x-direction and \Verb+#3+ in the y-direction.
206
If \Verb+#1+ is not empty, it should be a macro which is used to store the translated object (it will be an \Verb+spath+ object).
207
If \Verb+#1+ is empty, the current object is modified.
208
209
\item \Verb+length()+
210
211
This method inserts the length of the path in the token stream, computing it if it is not already known.
212
(It is this computation which makes it differ from the \Verb+value+ method.)
213
214
\item \Verb+real length()+
215
216
This method inserts the real length of the path in the token stream, computing it if it is not already known.
217
218
\item \Verb+number of components()+
219
220
This method inserts the number of components of the path in the token stream, computing it if it is not already known.
221
222
\item \Verb+initial point()+
223
224
This method inserts the number of components of the path in the token stream, computing it if it is not already known.
225
226
\item \Verb+final point()+
227
228
This method inserts the number of components of the path in the token stream, computing it if it is not already known.
229
230
\item \Verb+reverse path(#1)+
231
232
This method reverses the soft path.
233
If the argument is given, the reverse path is stored in it as a new \Verb+spath+ object.
234
If not, the current path is modified.
235
236
\item \Verb+prepare()+
237
238
This fills out all the attributes.
239
Finding the information for an attribute involves ``walking'' along the path.
240
Therefore, if we're going to need more than one, it makes sense to do them all in one go.
241
Calling this method ensures that they are all filled in and does so more efficiently than calling each individually.
242
243
\item \Verb+at least three()+
244
245
One of the things that the \texttt{calligraphy} package wants to be able to do is taper a path.
246
To do this nicely, the path should have at least three drawing pieces.
247
This ensures that this is so by splitting it if it does not.
248
If it has one piece, it is split into three at the .3 and .7 marks.
249
If it has two pieces, each is split in half.
250
251
\item \Verb+taper out()+
252
253
This is used to taper a path.
254
In fact, it replaces the first drawing component by a simularted tapered path (actually the outline of the tapered path is returned).
255
The rest of the path is thrown away, so this should be used after the path has been split.
256
257
\item \Verb+split path by length(#1,#2,#3)+
258
259
This splits a path according to the length.
260
The first argument will be an \Verb+spath+ object corresponding to the first part of the path, the second the rest, and the third says how many tokens should be in the first part of the path.
261
Both pieces are ``proper'' paths, so the second will be given an initial \Verb+moveto+.
262
263
\item \Verb+split path by real length(#1,#2,#3)+
264
265
This is the same as \Verb+split path by length+ except that it uses the \Verb+real length+ as the criterion of when to split.
266
267
\item \Verb+split path by component(#1,#2,#3)+
268
269
This is the same as \Verb+split path by length+ except that it uses the \Verb+number of components+ as the criterion of when to split.
270
271
\item \Verb+split(#1,#2,#3)+
272
273
This is the method that actually does the splitting.
274
It depends on certain macros being set which the previous three methods initialise.
275
It should therefore not be called directly.
276
Consider it a ``private'' method.
277
278
\item \Verb+reprocess path()+
279
280
This reprocesses the path.
281
Some TikZ/PGF settings have implications for how a path is constructed (such as the \Verb+rounded corners+ option).
282
If these have changed since the path was originally defined, it might be reasonable to redraw the path under the new conditions.
283
This does so.
284
285
\item \Verb+set as current path()+
286
287
This replaces the current path by the path stored in this object.
288
289
\item \Verb+get from current path()+
290
291
This replaces the path stored in this object by the current path.
292
293
\item \Verb+use path(#1)+
294
295
This uses the path.
296
The argument should be one of the PGF usage commands: \Verb+draw+, \Verb+fill+, \Verb+clip+, or \Verb+discard+.
297
298
\item \Verb+use path with tikz(#1)+
299
300
This uses the path but in a TikZian way.
301
The argument should be a list of TikZ styles to be set for the path.
302
Imagine this as \Verb+\path[<options>] <path>;+.
303
304
\item \Verb+concatenate(#1,#2)+
305
306
This concatenates the path in the current object with that from another.
307
If the first argument is given (which should be a macro), the result will a new \Verb+spath+ object stored in that macro.
308
If not, the object will be modified itself.
309
Since paths start with a \Verb+moveto+, the concatenation will not be a continuous path.
310
311
\item \Verb+concatenate with lineto(#1,#2)+
312
313
This concatenates the path as \Verb+concatenate+ does, except that the \Verb+moveto+ in the middle is replaced by a \Verb+lineto+.
314
315
\item \Verb+weld(#1,#2)+
316
317
This welds two paths together.
318
Welding is like concatenation except that the second path is translated so that its starting point is the final point of the first path (and the \Verb+moveto+ is removed).
319
320
\item \Verb+close()+
321
322
This closes the path.
323
\end{itemize}
324
325
\subsection{The \texttt{spath component} Object}
326
327
An \Verb+spath component+ object is an element in an array of \Verb+spath+ objects.
328
Each element contains an \Verb+spath+ object and pointers to the previous and successive components.
329
330
\begin{itemize}
331
\item \Verb+path+
332
333
This is the \Verb+spath+ object of the current element.
334
335
\item \Verb+next component+
336
337
This is the next \Verb+spath component+ object (if non-empty).
338
339
\item \Verb+previous component+
340
341
This is the previous \Verb+spath component+ object (if non-empty).
342
\end{itemize}
343
344
The methods for \Verb+spath component+s are as follows.
345
346
\begin{itemize}
347
\item \Verb+spath component(#1)+
348
349
This is the initialiser method.
350
The argument should be the previous component in the array.
351
352
\item \Verb+value(#1)+
353
354
This method, and the following ones, are exactly as in the \Verb+spath+ object.
355
356
\item \Verb+set(#1,#2)+
357
\item \Verb+let(#1,#2)+
358
\item \Verb+get(#1,#2)+
359
\item \Verb+show(#1)+
360
\item \Verb+set path(#1)+
361
362
This sets the \Verb+spath+ attribute of this object.
363
364
\item \Verb+apply to paths(#1,#2)+
365
366
This applies a method to all of the \Verb+spath+ objects in the array, starting with the current path and proceding to the next component, and so on.
367
The first argument is the method name, the second is any argument that is to be passed to that method.
368
369
\item \Verb+apply to previous paths(#1,#2)+
370
371
This applies a method to all of the \Verb+spath+ objects in the array, starting with the current path and proceding to the previous component, and so on.
372
\end{itemize}
373
374
There is an additional command for use when creating an array of \Verb+spath component+s.
375
This is \Verb+\spathsplit+.
376
It takes two arguments.
377
The first is a macro that will become the first component of an array of \Verb+spath component+s.
378
The second is a macro containing a soft path.
379
The soft path will be split into pieces according to its components (that is, at the \Verb+moveto+s) and stored in the array.
380
At the moment, the last component is (temporarily) available at the end of the split as the \Verb+\spath@this@component+ macro.
381
382
383
\end{document}
b'\\ No newline at end of file'
Loggerhead is a web-based interface for Breezy
Version: 2.0.1