Debian Codegraph @

texmf-dist/doc/generic/pgf/pgfmanual-en-library-decorations.tex

raw
1 % Copyright 2019 by Mark Wibrow and Till Tantau
2 %
3 % This file may be distributed and/or modified
4 %
5 % 1. under the LaTeX Project Public License and/or
6 % 2. under the GNU Free Documentation License.
7 %
8 % See the file doc/generic/pgf/licenses/LICENSE for more details.
9
10
11 \section{Decoration Library}
12 \label{section-library-decorations}
13
14
15 \subsection{Overview and Common Options}
16
17 The decoration libraries define a number of (more or less useful) decorations
18 that can be applied to paths. The usage of decorations is not covered in the
19 present section, please consult Sections~\ref{section-tikz-decorations}, which
20 explains how decorations are used in \tikzname, and
21 \ref{section-base-decorations}, which explains how new decorations can be
22 defined.
23
24 The decorations are influenced by a number of parameters that can be set using
25 the |decoration| option. These parameters are typically shared between
26 different decorations. In the following, the general options are documented
27 (they are defined directly in the |decoration| module), special-purpose keys
28 are documented with the decoration that uses it.
29
30 Since you are encouraged to use these keys to make your own decorations
31 configurable, it is indicated for each key where the value is stored (so that
32 you can access it). Note that some values are stored in \TeX\ dimension
33 registers while others are stored in macros.
34
35 \begin{key}{/pgf/decoration/amplitude=\meta{dimension} (initially 2.5pt)}
36 This key determines the ``desired height'' (or amplitude) of decorations
37 for which this makes sense. For instance, the initial value of |2.5pt|
38 means that deforming decorations should deform a path by up to 2.5pt away
39 from the original path.
40
41 This key sets the \TeX-dimension |\pgfdecorationsegmentamplitude|.
42 \end{key}
43
44 \begin{key}{/pgf/decoration/meta-amplitude=\meta{dimension} (initially 2.5pt)}
45 This key determines the amplitude for a meta-decoration.
46
47 The key sets the \TeX-macro (!) |\pgfmetadecorationsegmentamplitude|.
48 \end{key}
49
50 \begin{key}{/pgf/decoration/segment length=\meta{dimension} (initially 10pt)}
51 Many decorations are made up of small segments. This key determines the
52 desired length of such segments.
53
54 This key sets the \TeX-dimension |\pgfdecorationsegmentlength|.
55 \end{key}
56
57 \begin{key}{/pgf/decoration/meta-segment length=\meta{dimension} (initially 1cm)}
58 This determined the length of the meta-segments from which a
59 meta-decoration is made up.
60
61 This key sets the \TeX-macro (!) |\pgfmetadecorationsegmentlength|.
62 \end{key}
63
64 \begin{key}{/pgf/decoration/angle=\meta{degree} (initially 45)}
65 The way some decorations look like depends on a configurable angle. For
66 instance, a |wave| decoration consists of arcs and the opening angle of
67 these arcs is given by the |angle|.
68
69 This key sets the \TeX-macro |\pgfdecorationsegmentangle|.
70 \end{key}
71
72 \begin{key}{/pgf/decoration/aspect=\meta{factor} (initially 0.5)}
73 For some decorations there is a natural aspect ratio. For instance,
74 for a |brace| decoration the aspect ratio determines where the brace
75 point will be.
76
77 This key sets the \TeX-macro |\pgfdecorationsegmentaspect|.
78 \end{key}
79
80 \begin{key}{/pgf/decoration/start radius=\meta{dimension} (initially 2.5pt)}
81 For some decorations there is a natural start radius (of some circle,
82 presumably).
83
84 This key stores the value directly inside the key.
85 \end{key}
86
87 \begin{key}{/pgf/decoration/end radius=\meta{dimension} (initially 2.5pt)}
88 For some decorations there is a natural end radius (of some circle,
89 presumably).
90
91 This key stores the value directly inside the key.
92 \end{key}
93
94 \begin{stylekey}{/pgf/decoration/radius=\meta{dimension}}
95 Sets the start and end radius simultaneously.
96 \end{stylekey}
97
98 \begin{key}{/pgf/decoration/path has corners=\meta{boolean} (initially false)}
99 This is a hint to the decoration code as to whether the path has corners or
100 not. If a path has a sharp corner, setting this option to |true| may result
101 in better rendering of the decoration because the joins of input segments
102 are approached ``more carefully'' than when this key is set to false.
103 However, if the path is, say, a smooth circle, setting this key to |true|
104 will usually look worse. Most decorations ignore this key, anyway.
105 Internally, it sets the \TeX-if |\ifpgfdecoratepathhascorners|.
106 \end{key}
107
108
109 \subsection{Handling ``Dimension too large'' errors}
110
111 In case you should run into a ``Dimension too large error'' when using the
112 |decorations| libraries, there is a pretty high chance that you can resolve
113 this by using the |fpu| library in combination with
114 |/pgf/fpu/install only={reciprocal}|. Please note that this key should only be
115 applied locally to avoid other errors (see also at the definition of this key
116 on page~\pageref{fpu-install-only}).
117 %
118 \begin{codeexample}[preamble={\usetikzlibrary{decorations.markings,fpu}}]
119 \begin{tikzpicture}
120 \begin{scope}[/pgf/fpu/install only={reciprocal}]
121 \draw[postaction=decorate,decoration={
122 markings,mark=at position 0.52 with {
123 \draw circle[radius=2pt];
124 }},
125 ] plot[smooth,variable=\x,domain=-1:1] (\x*\x*\x,\x*\x);
126 \end{scope}
127 \end{tikzpicture}
128 \end{codeexample}
129
130
131 \subsection{Path Morphing Decorations}
132
133 \begin{pgflibrary}{decorations.pathmorphing}
134 A \emph{path morphing decoration} ``morphs'' or ``deforms'' the
135 to-be-decorated path. This means that what used to be a straight line might
136 afterwards be a snaking curve and have bumps. However, a line is still a
137 line and path deforming decorations do not change the number of subpaths.
138 For instance, if the path used to consist of two circles and an open arc,
139 the path will, after the decoration process, still consist of two closed
140 subpaths and one open subpath.
141 \end{pgflibrary}
142
143
144 \subsubsection{Decorations Producing Straight Line Paths}
145
146 The following deformations use only straight lines in order to morph the paths.
147
148 \begin{decoration}{lineto}
149 This decoration replaces the path by straight lines. For each curve, the
150 path simply goes directly from the start point to the end point. In the
151 following example, the arc actually consist of two subcurves.
152
153 This decoration is actually always defined when the decoration module is
154 loaded, but it is documented here for consistency.
155 %
156 \begin{codeexample}[preamble={\usetikzlibrary{decorations}}]
157 \begin{tikzpicture}[decoration=lineto]
158 \draw [help lines] grid (3,2);
159 \draw [decorate,fill=yellow!80!black]
160 (0,0) -- (3,1) arc (0:180:1.5 and 1) -- cycle;
161 \end{tikzpicture}
162 \end{codeexample}
163 %
164 \end{decoration}
165
166 \begin{decoration}{straight zigzag}
167 This (meta-)decoration decorates the path by alternating between |curveto|
168 and |zigzag| decorations. It always finishes with the |curveto| decoration.
169 The following parameters influence the decoration:
170 %
171 \begin{itemize}
172 \item |amplitude| determines how much the zigzag line raises above and
173 falls below a straight line to the target point.
174 \item |segment length| determines the length of a complete ``up-down''
175 cycle.
176 \item |meta-segment length| determines the length of the |curveto| and the
177 |zigzag| decorations.
178 \end{itemize}
179 %
180 \begin{codeexample}[preamble={\usetikzlibrary{decorations.pathmorphing}}]
181 \begin{tikzpicture}[decoration={straight zigzag,meta-segment length=1.1cm}]
182 \draw [help lines] grid (3,2);
183 \draw [decorate,fill=yellow!80!black]
184 (0,0) -- (3,1) arc (0:180:1.5 and 1) -- cycle;
185 \end{tikzpicture}
186 \end{codeexample}
187 %
188 \end{decoration}
189
190 \begin{decoration}{random steps}
191 This decoration consists of straight line segments. The line segments head
192 towards the target, but each step is randomly shifted a little bit. The
193 following parameters influence the decorations:
194 %
195 \begin{itemize}
196 \item |segment length| determines the basic length of each step.
197 \item |amplitude| The end of each step is perturbed both in $x$- and in
198 $y$-direction by two values drawn uniformly from the interval
199 $[-d,d]$, where $d$ is the value of |amplitude|.
200 \end{itemize}
201 %
202 \begin{codeexample}[pre={\pgfmathsetseed{1}},preamble={\usetikzlibrary{decorations.pathmorphing}}]
203 \begin{tikzpicture}
204 [decoration={random steps,segment length=2mm}]
205 \draw [help lines] grid (3,2);
206 \draw [decorate,fill=yellow!80!black]
207 (0,0) -- (3,1) arc (0:180:1.5 and 1) -- cycle;
208 \end{tikzpicture}
209 \end{codeexample}
210 %
211 \end{decoration}
212
213 \begin{decoration}{saw}
214 This decoration looks like the blade of a saw. The following parameters
215 influence the decoration:
216 %
217 \begin{itemize}
218 \item |amplitude| determines how much each spike raises above the
219 straight line.
220 \item |segment length| determines the length each spike.
221 \end{itemize}
222 %
223 \begin{codeexample}[preamble={\usetikzlibrary{decorations.pathmorphing}}]
224 \begin{tikzpicture}[decoration=saw]
225 \draw [help lines] grid (3,2);
226 \draw [decorate,fill=yellow!80!black]
227 (0,0) -- (3,1) arc (0:180:1.5 and 1) -- cycle;
228 \end{tikzpicture}
229 \end{codeexample}
230 %
231 \end{decoration}
232
233 \begin{decoration}{zigzag}
234 This decoration looks like a zigzag line. The following parameters
235 influence the decoration:
236 %
237 \begin{itemize}
238 \item |amplitude| determines how much the zigzag line raises above and
239 falls below a straight line to the target point.
240 \item |segment length| determines the length of a complete ``up-down''
241 cycle.
242 \end{itemize}
243 %
244 \begin{codeexample}[preamble={\usetikzlibrary{decorations.pathmorphing}}]
245 \begin{tikzpicture}[decoration=zigzag]
246 \draw [help lines] grid (3,2);
247 \draw [decorate,fill=yellow!80!black]
248 (0,0) -- (3,1) arc (0:180:1.5 and 1) -- cycle;
249 \end{tikzpicture}
250 \end{codeexample}
251 %
252 \end{decoration}
253
254
255 \subsubsection{Decorations Producing Curved Line Paths}
256
257 \begin{decoration}{bent}
258 This decoration adds a slightly bent line from the start to the target. The
259 amplitude of the bend is given |amplitude| (an amplitude of zero gives a
260 straight line).
261 %
262 \begin{itemize}
263 \item |amplitude| determines the amplitude of the bend.
264 \item |aspect| determines how tight the bend is. A good value is around
265 |0.3|.
266 \end{itemize}
267 %
268 Note that this decoration makes only little sense for curves. You should
269 apply it only to straight lines.
270 %
271 \begin{codeexample}[preamble={\usetikzlibrary{decorations.pathmorphing}}]
272 \begin{tikzpicture}[decoration=bent]
273 \draw [help lines] grid (3,2);
274 \draw [decorate] (0,0) -- (3,1) -- (1.5,2) -- (0,1);
275 \end{tikzpicture}
276 \end{codeexample}
277 %
278 \begin{codeexample}[preamble={\usetikzlibrary{decorations.pathmorphing}}]
279 \begin{tikzpicture}[decoration={bent,aspect=.3}]
280 \draw [decorate,fill=yellow!80!black] (0,0) rectangle (3.5,2);
281 \node[circle,draw] (A) at (.5,.5) {A};
282 \node[circle,draw] (B) at (3,1.5) {B};
283 \draw[->,decorate] (A) -- (B);
284 \draw[->,decorate] (B) -- (A);
285 \end{tikzpicture}
286 \end{codeexample}
287 %
288 \end{decoration}
289
290 \begin{decoration}{bumps}
291 This decoration replaces the path by little half ellipses. The following
292 parameters influence it.
293 %
294 \begin{itemize}
295 \item |amplitude| determines the height of the half ellipse.
296 \item |segment length| determines the width of the half ellipse.
297 \end{itemize}
298 %
299 \begin{codeexample}[preamble={\usetikzlibrary{decorations.pathmorphing}}]
300 \begin{tikzpicture}[decoration=bumps]
301 \draw [help lines] grid (3,2);
302 \draw [decorate,fill=yellow!80!black]
303 (0,0) -- (3,1) arc (0:180:1.5 and 1) -- cycle;
304 \end{tikzpicture}
305 \end{codeexample}
306 %
307 \end{decoration}
308
309 \begin{decoration}{coil}
310 This decoration replaces the path by a coiled line. To understand how this
311 works, imagine a three-dimensional spring. The spring's axis points along
312 the path toward the target. Then, we ``view'' the spring from a certain
313 angle. If we look ``straight from the side'' we will see a perfect sine
314 curve, if we look ``more from the front'' we will see a coil. The following
315 parameters influence the decoration:
316 %
317 \begin{itemize}
318 \item |amplitude| determines how much the coil rises above the path and
319 falls below it. Thus, this is the radius of the coil.
320 \item |segment length| determines the distance between two consecutive
321 ``curls''. Thus, when the spring is see ``from the side'' this will
322 be the wave length of the sine curve.
323 \item |aspect| determines the ``viewing direction''. A value of |0|
324 means ``looking from the side'' and a value of |0.5|, which is the
325 default, means ``look more from the front''.
326 \end{itemize}
327 %
328 \begin{codeexample}[preamble={\usetikzlibrary{decorations.pathmorphing}}]
329 \begin{tikzpicture}[decoration=coil]
330 \draw [help lines] grid (3,2);
331 \draw [decorate,fill=yellow!80!black]
332 (0,0) -- (3,1) arc (0:180:1.5 and 1) -- cycle;
333 \end{tikzpicture}
334 \end{codeexample}
335 %
336 \begin{codeexample}[preamble={\usetikzlibrary{decorations.pathmorphing}}]
337 \begin{tikzpicture}
338 [decoration={coil,aspect=0.3,segment length=3mm,amplitude=3mm}]
339 \draw [help lines] grid (3,2);
340 \draw [decorate,fill=yellow!80!black]
341 (0,0) -- (3,1) arc (0:180:1.5 and 1) -- cycle;
342 \end{tikzpicture}
343 \end{codeexample}
344 %
345 \end{decoration}
346
347 \begin{decoration}{curveto}
348 This decoration simply yields a line following the original path. This
349 means that (ideally) it does not change the path and follows any curves in
350 the path (hence the name). In reality, due to the internals of how
351 decorations are implemented, this decoration actually replaces the path by
352 numerous small straight lines.
353
354 This decoration is mostly useful in conjunction with meta-decorations. It
355 is also actually defined in the decoration module and is always available.
356 %
357 \begin{codeexample}[preamble={\usetikzlibrary{decorations.pathmorphing}}]
358 \begin{tikzpicture}[decoration=curveto]
359 \draw [help lines] grid (3,2);
360 \draw [decorate,fill=yellow!80!black]
361 (0,0) -- (3,1) arc (0:180:1.5 and 1) -- cycle;
362 \end{tikzpicture}
363 \end{codeexample}
364 %
365 \end{decoration}
366
367 \begin{decoration}{snake}
368 This decoration replaces the path by a line that looks like a snake seen
369 from above. More precisely, the snake is a sine wave with a ``softened''
370 start and ending. The following parameters influence the snake:
371 %
372 \begin{itemize}
373 \item |amplitude| determines the sine wave's amplitude.
374 \item |segment length| determines the sine wave's wavelength.
375 \end{itemize}
376 %
377 \begin{codeexample}[preamble={\usetikzlibrary{decorations.pathmorphing}}]
378 \begin{tikzpicture}[decoration=snake]
379 \draw [help lines] grid (3,2);
380 \draw [decorate,fill=yellow!80!black]
381 (0,0) -- (3,1) arc (0:180:1.5 and 1) -- cycle;
382 \end{tikzpicture}
383 \end{codeexample}
384 %
385 \end{decoration}
386
387
388 \subsection{Path Replacing Decorations}
389
390 \begin{pgflibrary}{decorations.pathreplacing}
391 This library defines decorations that replace the to-be-decorated path by
392 another path. Unlike morphing decorations, the replaced path might be quite
393 different, for instance a straight line might be replaced by a set of
394 circles. Note that filling a path that has been replaced using one of the
395 decorations in this library typically does not fill the original area but,
396 rather, the smaller area of the newly-created path segments.
397 \end{pgflibrary}
398
399 \begin{decoration}{border}
400 This decoration adds straight lines to the path that are at a specific
401 angle to the line toward the target. The idea is to add these little lines
402 to indicate the ``border'' of an area. The following parameters influence
403 the decoration:
404 %
405 \begin{itemize}
406 \item |segment length| determines the distance between consecutive
407 ticks.
408 \item |amplitude| determines the length of the ticks.
409 \item |angle| determines the angle between the ticks and the line of
410 the path.
411 \end{itemize}
412 %
413 \begin{codeexample}[preamble={\usetikzlibrary{decorations.pathreplacing}}]
414 \begin{tikzpicture}[decoration=border]
415 \draw [help lines] grid (3,2);
416 \draw [postaction={decorate,draw,red}]
417 (0,0) -- (3,1) arc (0:180:1.5 and 1);
418 \end{tikzpicture}
419 \end{codeexample}
420 %
421 \end{decoration}
422
423 \begin{decoration}{brace}
424 This decoration replaces a straight line path by a long brace. The left and
425 right end of the brace will be exactly on the start and endpoint of the
426 decoration. The decoration really only makes sense for paths that are a
427 straight line.
428 %
429 \begin{itemize}
430 \item |amplitude| determines how much the brace rises above the path.
431 \item |aspect| determines the fraction of the total length where the
432 ``middle part'' of the brace will be.
433 \end{itemize}
434 %
435 \begin{codeexample}[preamble={\usetikzlibrary{decorations.pathreplacing}}]
436 \begin{tikzpicture}[decoration=brace]
437 \draw [help lines] grid (3,2);
438 \draw [decorate] (0,0) -- (3,1);
439 \end{tikzpicture}
440 \end{codeexample}
441 %
442 \end{decoration}
443
444 \begin{decoration}{expanding waves}
445 This decoration adds arcs to the path that get bigger along the line
446 towards the target. The following parameters influence the decoration:
447 %
448 \begin{itemize}
449 \item |segment length| determines the distance between consecutive
450 arcs.
451 \item |angle| determines the opening angle below and above the path.
452 Thus, the total opening angle is twice this angle.
453 \end{itemize}
454 %
455 \begin{codeexample}[preamble={\usetikzlibrary{decorations.pathreplacing}}]
456 \begin{tikzpicture}[decoration={expanding waves,angle=5}]
457 \draw [help lines] grid (3,2);
458 \draw [decorate] (0,0) -- (3,1) arc (0:180:1.5 and 1);
459 \end{tikzpicture}
460 \end{codeexample}
461 %
462 \end{decoration}
463
464 \begin{decoration}{moveto}
465 This decoration simply jumps to the end of the path using a move-to path
466 operation. It is mainly useful as |pre=moveto| or |post=moveto|
467 decorations.
468
469 This decoration is actually always defined when the decoration module is
470 loaded, but it is documented here for consistency.
471 \end{decoration}
472
473 \begin{decoration}{ticks}
474 This decoration replaces the path by straight lines that are orthogonal to
475 the path. The following parameters influence the decoration:
476 %
477 \begin{itemize}
478 \item |segment length| determines the distance between consecutive
479 ticks.
480 \item |amplitude| determines half the length of the ticks.
481 \end{itemize}
482 %
483 \begin{codeexample}[preamble={\usetikzlibrary{decorations.pathreplacing}}]
484 \begin{tikzpicture}[decoration=ticks]
485 \draw [help lines] grid (3,2);
486 \draw [decorate] (0,0) -- (3,1) arc (0:180:1.5 and 1);
487 \end{tikzpicture}
488 \end{codeexample}
489 %
490 \end{decoration}
491
492 \begin{decoration}{waves}
493 This decoration replaces the path by arcs that have a constant size. The
494 following parameters influence the decoration:
495 %
496 \begin{itemize}
497 \item |segment length| determines the distance between consecutive
498 arcs.
499 \item |angle| determines the opening angle below and above the path.
500 Thus, the total opening angle is twice this angle.
501 \item |radius| determines the radius of each arc.
502 \end{itemize}
503 %
504 \begin{codeexample}[preamble={\usetikzlibrary{decorations.pathreplacing}}]
505 \begin{tikzpicture}[decoration={waves,radius=4mm}]
506 \draw [help lines] grid (3,2);
507 \draw [decorate] (0,0) -- (3,1) arc (0:180:1.5 and 1);
508 \end{tikzpicture}
509 \end{codeexample}
510 %
511 \end{decoration}
512
513 \begin{decoration}{show path construction}
514 This decoration allows ``something different'' to be done for each
515 \emph{type} of input segment (i.e., moveto, lineto, curveto or closepath).
516 Typically, each segment will be replaced with another path, but this need
517 not necessarily be the case.
518 %
519 \begin{codeexample}[preamble={\usetikzlibrary{decorations.pathreplacing}}]
520 \begin{tikzpicture}[>=stealth, every node/.style={midway, sloped, font=\tiny},
521 decoration={show path construction,
522 moveto code={
523 \fill [red] (\tikzinputsegmentfirst) circle (2pt)
524 node [fill=none, below] {moveto};},
525 lineto code={
526 \draw [blue,->] (\tikzinputsegmentfirst) -- (\tikzinputsegmentlast)
527 node [above] {lineto};
528 },
529 curveto code={
530 \draw [green!75!black,->] (\tikzinputsegmentfirst) .. controls
531 (\tikzinputsegmentsupporta) and (\tikzinputsegmentsupportb)
532 ..(\tikzinputsegmentlast) node [above] {curveto};
533 },
534 closepath code={
535 \draw [orange,->] (\tikzinputsegmentfirst) -- (\tikzinputsegmentlast)
536 node [above] {closepath};}
537 }]
538 \draw [help lines] grid (3,2);
539 \path [decorate] (0,0) -- (3,1) arc (0:180:1.5 and 1) -- cycle;
540 \end{tikzpicture}
541 \end{codeexample}
542
543 The following keys can be used to specify the code to execute for each type
544 of input segment.
545
546 \begin{key}{/pgf/decoration/moveto code=\meta{code} (initially \char`\{\char`\})}
547 Set the code to be executed for every moveto input segment. It is
548 important to remember that the transformations applied by the
549 decoration automaton are turned \emph{off} when \meta{code} is
550 executed.
551 \end{key}
552
553 \begin{key}{/pgf/decoration/lineto code=\meta{code} (initially \char`\{\char`\})}
554 Set the code to be executed for every lineto input segment.
555 \end{key}
556
557 \begin{key}{/pgf/decoration/curveto code=\meta{code} (initially \char`\{\char`\})}
558 Set the code to be executed for every curveto input segment.
559 \end{key}
560
561 \begin{key}{/pgf/decoration/closepath code=\meta{code} (initially \char`\{\char`\})}
562 Set the code to be executed for every closepath input segment.
563 \end{key}
564
565 Within \meta{code} the first and last points on the current input segment
566 can be accessed using |\pgfpointdecoratedinputsegmentfirst| and
567 |\pgfpointdecoratedinputsegmentlast|. For curves, the control (support)
568 points can be accessed using |\pgfpointdecoratedinputsegmentsupporta| and
569 |\pgfpointdecoratedinputsegmentsupportb|.
570
571 In \tikzname, you can use the following macros inside a \tikzname{}
572 coordinate.
573
574 \begin{command}{\tikzinputsegmentfirst}
575 The first point on the current input segment path.
576 \end{command}
577
578 \begin{command}{\tikzinputsegmentlast}
579 The last point on the current input segment path.
580 \end{command}
581
582 \begin{command}{\tikzinputsegmentsupporta}
583 The first support on the curveto input segment path.
584 \end{command}
585
586 \begin{command}{\tikzinputsegmentsupportb}
587 The second support on the curveto input segment path.
588 \end{command}
589 %
590 {\ifpgfmanualexternalize\tikzexternaldisable\fi
591 \begin{codeexample}[preamble={\usetikzlibrary{decorations.pathreplacing,shapes.misc}}]
592 \tikzset{
593 show curve controls/.style={
594 decoration={
595 show path construction,
596 curveto code={
597 \draw [blue, dashed]
598 (\tikzinputsegmentfirst) -- (\tikzinputsegmentsupporta)
599 node [at end, cross out, draw, solid, red, inner sep=2pt]{};
600 \draw [blue, dashed]
601 (\tikzinputsegmentsupportb) -- (\tikzinputsegmentlast)
602 node [at start, cross out, draw, solid, red, inner sep=2pt]{};
603 }
604 },decorate
605 }
606 }
607
608 \begin{tikzpicture}
609 \draw [postaction=show curve controls, thick]
610 (0,2) .. controls (2.5,1.5) and (0.5,0.5) .. (3,0);
611 \end{tikzpicture}
612 \end{codeexample}
613 }%
614 %
615 \end{decoration}
616
617
618 \subsection{Marking Decorations}
619
620 \subsubsection{Overview}
621
622 A \emph{marking on a path} is any kind of graphic that is placed on a specific
623 position on a path. Markings are useful in rather diverse situations: you can
624 use them to, say, place little ``footsteps'' along a path as if someone where
625 walking along the path; to place arrow tips on the middle of a path to indicate
626 the ``direction'' in which something is flowing; or you can use them to place
627 informative information at certain positions of a path.
628
629 For historical reasons there are three different libraries for placing marks on
630 a path. They differ in what kind of markings can be added to a path. We start
631 with the most general and most useful of these libraries.
632
633
634 \subsection{Arbitrary Markings}
635
636 \begin{pgflibrary}{decorations.markings}
637 Markings are arbitrary ``marks'' that can be put on a path. Marks can be
638 arrow tips or nodes or even whole pictures.
639 \end{pgflibrary}
640
641 \begin{decoration}{markings}
642 A \emph{marking} can be thought of a ``little picture'' or more precisely
643 of ``some scope contents'' that is placed ``on'' a path at a certain
644 position. Suppose the marking should be a simple cross. We can produce this
645 with the following code:
646 %
647 \begin{codeexample}[code only]
648 \draw (-2pt,-2pt) -- (2pt,2pt);
649 \draw (2pt,-2pt) -- (-2pt,2pt);
650 \end{codeexample}
651 %
652 If we use this code as a marking at position |2cm| on a path, then the
653 following happens: \pgfname\ determines the position on the path that is
654 2cm along the path. Then it translates the coordinate system to this
655 position and rotates it such that the positive $x$-axis is tangent to the
656 path. Then a protective scope is created, inside which the above code is
657 executed -- resulting in a little cross on the path.
658
659 The |markings| decoration allows you to place one or more such markings on
660 a path. The decoration destroys the input path (except in certain cases,
661 detailed later), which means that it uses the path for determining
662 positions on the path, but after the decoration is done this path is gone.
663 You typically need to use a |postaction| to add markings.
664
665 Let us start with the above example in real code:
666 %
667 \begin{codeexample}[preamble={\usetikzlibrary{decorations.markings}}]
668 \begin{tikzpicture}[decoration={
669 markings,% switch on markings
670 mark=% actually add a mark
671 at position 2cm
672 with
673 {
674 \draw (-2pt,-2pt) -- (2pt,2pt);
675 \draw (2pt,-2pt) -- (-2pt,2pt);
676 }
677 }
678 ]
679 \draw [help lines] grid (3,2);
680 \draw [postaction={decorate}] (0,0) -- (3,1) arc (0:180:1.5 and 1);
681 \end{tikzpicture}
682 \end{codeexample}
683
684 We can also add the cross repeatedly:
685 %
686 \begin{codeexample}[preamble={\usetikzlibrary{decorations.markings}}]
687 \begin{tikzpicture}[decoration={
688 markings,% switch on markings
689 mark=% actually add a mark
690 between positions 0 and 1 step 5mm
691 with
692 {
693 \draw (-2pt,-2pt) -- (2pt,2pt);
694 \draw (2pt,-2pt) -- (-2pt,2pt);
695 }
696 }
697 ]
698 \draw [help lines] grid (3,2);
699 \draw [postaction={decorate}] (0,0) -- (3,1) arc (0:180:1.5 and 1);
700 \end{tikzpicture}
701 \end{codeexample}
702
703 The |mark| decoration option is used to specify a marking. It comes in two
704 versions:
705 %
706 \begin{key}{/pgf/decoration/mark=\texttt{at position }\meta{pos}\texttt{ with }\meta{code}}
707 The options specifies that when a |marking| decoration is applied,
708 there should be a marking at position \meta{pos} on the path whose code
709 is given by \meta{code}.
710
711 The \meta{pos} can have four different forms:
712 %
713 \begin{enumerate}
714 \item It can be a non-negative dimension like |0pt| or |2cm| or
715 |5cm/2|. In this case, it refers to the position along the path
716 that is this far displaced from the start.
717 \item It can be a negative dimension like |-1cm-2pt| or |-1sp|. In
718 this case, the position is taken from the end of the path.
719 Thus, |-1cm| is the position that is $-1$cm displaced from the
720 end of the path.
721 \item It can be a dimensionless non-negative number like |1/2| or
722 |0.333+2*0.1|. In this case, the \meta{pos} is interpreted as a
723 factor of the total path length. Thus, a \meta{pos} or |0.5|
724 refers to the middle of the path, |0.1| is near the start, and
725 so on.
726 \item It can be a dimensionless negative number like |-0.1|. Then,
727 again, the fraction of the path length counts ``from the end''.
728 \end{enumerate}
729
730 The \meta{pos} determines a position on the path. When the marking is
731 applied, the (high level) coordinate system will have been transformed
732 so that the origin lies at this position and the positive $x$-axis
733 points along the path. For this coordinate system, the \meta{code} is
734 executed. It can contain all sorts of graphic drawing commands,
735 including (even named) nodes.
736
737 If the position lies past the end of the path (for instance if
738 \meta{pos} is set to |1.2|), the marking will not be drawn.
739
740 It is possible to give the |mark| option several times, which causes
741 several markings to be applied. In this case, however, it is necessary
742 that the positions on the path are in increasing order. That is, it is
743 not allowed (and will result in chaos) to have a marking that lies
744 earlier on the path to follow a marking that is later on the path.
745 %
746 \begin{codeexample}[preamble={\usetikzlibrary{decorations.markings}}]
747 \begin{tikzpicture}[decoration={
748 markings,% switch on markings
749 mark=at position 1cm with \node[red]{1cm};,
750 mark=at position .5 with \node[green]{mid};,
751 mark=at position -1cm with {\node[blue,transform shape]{1cm from end};}}
752 ]
753 \draw [help lines] grid (3,2);
754 \draw [postaction={decorate}] (0,0) -- (3,1) arc (0:180:1.5 and 1);
755 \end{tikzpicture}
756 \end{codeexample}
757
758 Here is an example that shows how markings can be used to place text on
759 plots:
760 %
761 \begin{codeexample}[preamble={\usetikzlibrary{decorations.markings}}]
762 \begin{tikzpicture}[domain=0:4,label/.style={postaction={
763 decorate,
764 decoration={
765 markings,
766 mark=at position .75 with \node #1;}}}]
767 \draw[very thin,color=gray] (-0.1,-1.1) grid (3.9,3.9);
768
769 \draw[->] (-0.2,0) -- (4.2,0) node[right] {$x$};
770 \draw[->] (0,-1.2) -- (0,4.2) node[above] {$f(x)$};
771
772 \draw[red,label={[above left]{$f(x)=x$}}] plot (\x,\x);
773 \draw[blue,label={[below left]{$f(x)=\sin x$}}] plot (\x,{sin(\x r)});
774 \draw[orange,label={[right]{$f(x)= \frac{1}{20} \mathrm e^x$}}] plot (\x,{0.05*exp(\x)});
775 \end{tikzpicture}
776 \end{codeexample}
777
778 When the \meta{code} is being executed, two special keys will have been
779 set up, whose value may be of interest:
780 %
781 \begin{key}{/pgf/decoration/mark info/sequence number}
782 This key can only be read. Its value (which can be obtained using
783 the |\pgfkeysvalueof| command) is a ``sequence number'' of the
784 mark. The first mark that is added to a path has number |1|, the
785 second number |2|, and so on. This key is mainly useful in
786 conjunction with repeated markings (see below).
787 \end{key}
788 %
789 \begin{key}{/pgf/decoration/mark info/distance from start}
790 This key can only be read. Its value is the distance of the marking
791 from the start of the path in points. For instance, if the path
792 length is 100pt and the marking is in the middle of the path, the
793 value of this key would be |50.0pt|.
794 \end{key}
795 \end{key}
796
797 A second way to use the |mark| key is the following:
798 %
799 \begin{key}{/pgf/decoration/mark=\texttt{between positions }\meta{start pos}\texttt{ and }\meta{end pos}\texttt{ step }\meta{stepping}\texttt{ with }\meta{code}}
800 This works similarly to the |at position| version of this option, only
801 multiple marks are placed, starting at \meta{start pos} and then spaced
802 apart by \meta{stepping}. The \meta{start pos}, the \meta{end pos}, and
803 also the \meta{stepping} may all be specified in the same way as for
804 the |at position| version, that is, either using units or no units and
805 also using positive or negative values.
806
807 Let us start with a simple example in which we place ten crosses along
808 a path starting with the beginning of the path ($\meta{start pos} = 0$)
809 and ending at the end ($\meta{end pos} = 1$).
810 %
811 \begin{codeexample}[preamble={\usetikzlibrary{decorations.markings}}]
812 \begin{tikzpicture}[decoration={markings,
813 mark=between positions 0 and 1 step 0.1
814 with { \draw (-2pt,-2pt) -- (2pt,2pt);
815 \draw (2pt,-2pt) -- (-2pt,2pt); }} ]
816 \draw [help lines] grid (3,2);
817 \draw [postaction={decorate}] (0,0) -- (3,1) arc (0:180:1.5 and 1);
818 \end{tikzpicture}
819 \end{codeexample}
820
821 In the next example we place arrow shapes on the path instead of
822 crosses. Note the use of the |transform shape| option to ensure that
823 the nodes are actually rotated.
824 %
825 \begin{codeexample}[preamble={\usetikzlibrary{decorations.markings,shapes.arrows}}]
826 \begin{tikzpicture}[decoration={markings,
827 mark=between positions 0 and 1 step 1cm
828 with { \node [single arrow,fill=red,
829 single arrow head extend=3pt,transform shape] {};}}]
830 \draw [help lines] grid (3,2);
831 \draw [postaction={decorate}] (0,0) -- (3,1) arc (0:180:1.5 and 1);
832 \end{tikzpicture}
833 \end{codeexample}
834
835 Using the key |sequence number| we can also ``number'' the nodes and
836 even refer to them later on.
837 %
838 % FIXME: the automatic key highlighting fails here!
839 \begin{codeexample}[preamble={\usetikzlibrary{decorations.markings}}]
840 \begin{tikzpicture}[decoration={markings,
841 mark=between positions 0 and 1 step 1cm with {
842 \node [draw,
843 name=mark-\pgfkeysvalueof{/pgf/decoration/mark info/sequence number},
844 transform shape]
845 {\pgfkeysvalueof{/pgf/decoration/mark info/sequence number}};}}]
846 \draw [help lines] grid (3,2);
847 \draw [postaction={decorate}] (0,0) -- (3,1) arc (0:180:1.5 and 1);
848 \draw [red,->] (mark-3) -- (mark-7);
849 \end{tikzpicture}
850 \end{codeexample}
851
852 In the following example we use the distance info to place ``length
853 information'' on a path:
854 %
855 \begin{codeexample}[preamble={\usetikzlibrary{decorations.markings}}]
856 \begin{tikzpicture}[decoration={markings,
857 % Main marks
858 mark=between positions 0 and 1 step 40pt with
859 { \draw [help lines] (0,0) -- (0,0.5)
860 node[above,font=\tiny]{
861 \pgfkeysvalueof{/pgf/decoration/mark info/distance from start}}; },
862 mark=at position -0.1pt with
863 { \draw [help lines] (0,0) -- (0,0.5)
864 node[above,font=\tiny]{
865 \pgfkeysvalueof{/pgf/decoration/mark info/distance from start}}; }}]
866 \draw [help lines] grid (5,3);
867 \draw [postaction={decorate}] (0,0) .. controls (8,3) and (0,3) .. (5,0) ;
868 \end{tikzpicture}
869 \end{codeexample}
870 \end{key}
871
872 \begin{key}{/pgf/decoration/reset marks}
873 Since |mark| options accumulate, there needs to be a way to ``reset''
874 things, so that any |mark| options set in an enclosing scope do not
875 interfere. This option does exactly this. Note that when the
876 \meta{code} of a marking is executed, the markings are automatically
877 reset.
878 \end{key}
879
880 As mentioned earlier, the decoration usually destroys the path. However,
881 this is no longer the case when the following key is set:
882 %
883 \begin{key}{/pgf/decoration/mark connection node=\meta{node name} (initially empty)}
884 When this key is set to a non-empty \meta{node name} while the
885 decoration is being processed, the following happens: The marking code
886 should, among possibly other things, define a node named \meta{node
887 name}. Then, the output path of this decoration will contain a line-to
888 to ``one end'' of this node, followed by a moveto to the ``other end''
889 of the node. More precisely, the first end is given by the position on
890 the border of \meta{node name} that lies in the direction ``from which
891 the path heads toward the node'' while the other end lies on the border
892 ``where the path heads away from the node''. Furthermore, this option
893 causes the decoration to end with a line-to to the end instead of a
894 move-to.
895
896 The net effect of all this is that when you decorate a straight line
897 with one or more markings that contain just a node, the line will
898 effectively connect these nodes.
899
900 Here are two examples that show how this works:
901 %
902 \begin{codeexample}[preamble={\usetikzlibrary{decorations.markings}}]
903 \begin{tikzpicture}[decoration={markings,
904 mark connection node=my node,
905 mark=at position .5 with
906 {\node [draw,blue,transform shape] (my node) {my node};}}]
907 \draw [help lines] grid (3,2);
908 \draw decorate { (0,0) -- (3,2) };
909 \end{tikzpicture}
910 \end{codeexample}
911
912 \begin{codeexample}[preamble={\usetikzlibrary{decorations.markings}}]
913 \begin{tikzpicture}[decoration={markings,
914 mark connection node=my node,
915 mark=at position .25 with
916 {\node [draw,red] (my node) {my node};}}]
917 \draw [help lines] grid (3,2);
918 \draw decorate { (0,0) -- (3,2) };
919 \end{tikzpicture}
920 \end{codeexample}
921 \end{key}
922 \end{decoration}
923
924
925 \subsubsection{Arrow Tip Markings}
926
927 Frequent markings that are hard to create correctly are arrow tips. For them,
928 two special commands are available when the \meta{code} of a |mark| option is
929 executed. (They are only defined in this code):
930
931 \begin{command}{\arrow\opt{\oarg{options}}\marg{arrow end tip}}
932 This command simply draws the \meta{arrow end tip} at the origin, pointing
933 right. This is exactly what you need when you want to draw an arrow tip as
934 a marking.
935
936 The \meta{options} can only be given when \tikzname\ is used. In this case,
937 they are executed in a scope that contains the arrow tip.
938 %
939 \begin{codeexample}[preamble={\usetikzlibrary{decorations.markings}}]
940 \begin{tikzpicture}[decoration={
941 markings,% switch on markings
942 mark=at position 1cm with {\node[red]{1cm};},
943 mark=at position .75 with {\arrow[blue,line width=2mm]{>}},
944 mark=at position -1cm with {\arrowreversed[black]{stealth}}}
945 ]
946 \draw [help lines] grid (3,2);
947 \draw [postaction={decorate}] (0,0) -- (3,1) arc (0:180:1.5 and 1);
948 \end{tikzpicture}
949 \end{codeexample}
950
951 Here is a more useful example:
952 %
953 \begin{codeexample}[preamble={\usetikzlibrary{decorations.markings}}]
954 \begin{tikzpicture}[decoration={
955 markings,% switch on markings
956 mark=between positions 0 and .75 step 4mm with {\arrow{stealth}},
957 mark=between positions .75 and 1 step 4mm with {\arrowreversed{stealth}}}
958 ]
959 \draw [help lines] grid (3,2);
960 \draw [postaction={decorate}] (0,0) -- (3,1) arc (0:180:1.5 and 1);
961 \end{tikzpicture}
962 \end{codeexample}
963 %
964 \end{command}
965
966 \begin{command}{\arrowreversed\opt{\oarg{options}}\marg{arrow end tip}}
967 As above, only the arrow end tip is flipped and points in the other
968 direction.
969 \end{command}
970
971
972 \subsubsection{Footprint Markings}
973
974 \begin{pgflibrary}{decorations.footprints}
975 The decorations of this library can be used to decorate a path with little
976 footprints, as if someone had ``walked'' along the path.
977 \end{pgflibrary}
978
979 \begin{decoration}{footprints}
980 The footprint decoration adds little footprints around the path. They start
981 with the left foot.
982 %
983 \begin{codeexample}[preamble={\usetikzlibrary{decorations.footprints}}]
984 \begin{tikzpicture}[decoration={footprints,foot length=5pt,stride length=10pt}]
985 \draw [help lines] grid (3,3);
986 \fill [decorate] (0,0) -- (3,2) arc (0:180:1.5 and 1);
987 \end{tikzpicture}
988 \end{codeexample}
989 %
990 You can influence the way this decoration looks using the following
991 options:
992 %
993 \begin{key}{/pgf/decoration/foot length (initially 10pt)}
994 The length or size of the footprint itself. A larger value makes the
995 footprint larger, but does not change the stride length.
996 %
997 \begin{codeexample}[preamble={\usetikzlibrary{decorations.footprints}}]
998 \begin{tikzpicture}[decoration={footprints,foot length=20pt}]
999 \fill [decorate] (0,0) -- (3,0);
1000 \end{tikzpicture}
1001 \end{codeexample}
1002 \end{key}
1003 %
1004 \begin{key}{/pgf/decoration/stride length (initially 30pt)}
1005 The length of strides. This is the distance between the beginnings of
1006 left footprints along the path.
1007 %
1008 \begin{codeexample}[preamble={\usetikzlibrary{decorations.footprints}}]
1009 \begin{tikzpicture}[decoration={footprints,stride length=50pt}]
1010 \fill [decorate] (0,0) -- (3,0);
1011 \end{tikzpicture}
1012 \end{codeexample}
1013 \end{key}
1014 %
1015 \begin{key}{/pgf/decoration/foot sep (initially 4pt)}
1016 The separation in the middle between the footprints. The footprints are
1017 moved away from the path by half this amount.
1018 %
1019 \begin{codeexample}[preamble={\usetikzlibrary{decorations.footprints}}]
1020 \begin{tikzpicture}[decoration={footprints,foot sep=10pt}]
1021 \fill [decorate] (0,0) -- (3,0);
1022 \end{tikzpicture}
1023 \end{codeexample}
1024 \end{key}
1025 %
1026 \begin{key}{/pgf/decoration/foot angle (initially 10)}
1027 Footprints are rotated by this much.
1028 %
1029 \begin{codeexample}[preamble={\usetikzlibrary{decorations.footprints}}]
1030 \begin{tikzpicture}[decoration={footprints,foot angle=60}]
1031 \fill [decorate] (0,0) -- (3,0);
1032 \end{tikzpicture}
1033 \end{codeexample}
1034 \end{key}
1035 %
1036 \begin{key}{/pgf/decoration/foot of (initially human)}
1037 The species whose footprints are shown. Possible values are:
1038
1039 \def\render#1{
1040 \texttt{#1} &
1041 \tikz [baseline,decoration={footprints,foot of=#1}]
1042 \fill [decorate] (0,0) -- (6,0); \\[3em]
1043 }
1044 \begin{tabular}{ll}
1045 \emph{Species} & \emph{Result} \\[1em]
1046 \render{gnome}
1047 \render{human}
1048 \render{bird}
1049 \render{felis silvestris}
1050 \end{tabular}
1051 \end{key}
1052 \end{decoration}
1053
1054
1055 \subsubsection{Shape Background Markings}
1056
1057 The third library for adding markings uses the background paths of certain
1058 shapes. This library is included mostly for historical reasons, using the
1059 |markings| library is usually preferable.
1060
1061 \begin{pgflibrary}{decorations.shapes}
1062 This library defines decorations that use shapes or shape-like drawings to
1063 decorate a path. The following options are common options used by the
1064 decorations in this library:
1065
1066 \begin{key}{/pgf/decoration/shape width=\meta{dimension} (initially 2.5pt)}
1067 The desired width of the shapes. For decorations that support varying
1068 shape sizes, this key sets both the start and end width (which can be
1069 overwritten using options like |shape start width|).
1070 \end{key}
1071
1072 \begin{key}{/pgf/decoration/shape height=\meta{dimension} (initially 2.5pt)}
1073 Works like the previous key, only for the height.
1074 \end{key}
1075
1076 \begin{key}{/pgf/decoration/shape size=\meta{dimension}}
1077 Sets the desired width and height simultaneously.
1078 \end{key}
1079
1080 For the exact places and macros where these keys store the values, please
1081 consult the beginning of the code of the library.
1082 \end{pgflibrary}
1083
1084 \begin{decoration}{crosses}
1085 This decoration replaces the path by (diagonal) crosses. The following
1086 parameters influence the decoration:
1087 %
1088 \begin{itemize}
1089 \item |segment length| determines the distance between (the centers of)
1090 consecutive crosses.
1091 \item |shape height| determines the height of each cross.
1092 \item |shape width| determines the width of each cross.
1093 \end{itemize}
1094 %
1095 \begin{codeexample}[preamble={\usetikzlibrary{decorations.shapes}}]
1096 \begin{tikzpicture}[decoration=crosses]
1097 \draw [help lines] grid (3,2);
1098 \draw [decorate] (0,0) -- (3,1) arc (0:180:1.5 and 1);
1099 \end{tikzpicture}
1100 \end{codeexample}
1101 %
1102 \end{decoration}
1103
1104 \begin{decoration}{triangles}
1105 This decoration replaces the path by triangles that point along the path.
1106 The following parameters influence the decoration:
1107 %
1108 \begin{itemize}
1109 \item |segment length| determines the distance between consecutive
1110 triangles.
1111 \item |shape height| determines the height of the triangle side that is
1112 orthogonal to the path.
1113 \item |shape width| determines the width of the triangle.
1114 \end{itemize}
1115 %
1116 \begin{codeexample}[preamble={\usetikzlibrary{decorations.shapes}}]
1117 \begin{tikzpicture}[decoration=triangles]
1118 \draw [help lines] grid (3,2);
1119 \draw [decorate,fill=yellow!80!black] (0,0) -- (3,1) arc (0:180:1.5 and 1);
1120 \end{tikzpicture}
1121 \end{codeexample}
1122 %
1123 \end{decoration}
1124
1125 \begin{decoration}{shape backgrounds}
1126 This is a general decoration that replaces the to-be-decorated path by
1127 repeated copies of the background path of an arbitrary shape that has
1128 previously been defined using the |\pgfdeclareshape| command (that is, you
1129 can use any shape in the shape libraries).
1130
1131 Please note that the background path of the shapes is used, but \emph{no
1132 nodes are created}. This means that \emph{you cannot have text inside the
1133 shapes of this path, you cannot name them, or refer to them.} Finally, this
1134 decoration \emph{will not work with shapes that depend strongly on the
1135 size of the text box (like the arrow shapes).} If any of these restrictions
1136 pose a problem, use the |markings| library instead.
1137 %
1138 \begin{codeexample}[preamble={\usetikzlibrary{decorations.shapes,shapes.geometric}}]
1139 \begin{tikzpicture}[decoration={shape backgrounds,shape=star,shape size=5pt}]
1140 \draw [help lines] grid (3,2);
1141 \draw [decorate] (0,0) -- (3,1) arc (0:180:1.5 and 1);
1142 \end{tikzpicture}
1143 \end{codeexample}
1144
1145 \begin{codeexample}[preamble={\usetikzlibrary{decorations.shapes,shapes.geometric}}]
1146 \tikzset{paint/.style={ draw=#1!50!black, fill=#1!50 },
1147 decorate with/.style=
1148 {decorate,decoration={shape backgrounds,shape=#1,shape size=2mm}}}
1149 \begin{tikzpicture}
1150 \draw [decorate with=dart, paint=red] (0,1.5) -- (3,1.5);
1151 \draw [decorate with=diamond, paint=green] (0,1) -- (3,1);
1152 \draw [decorate with=rectangle, paint=blue] (0,0.5) -- (3,0.5);
1153 \draw [decorate with=circle, paint=yellow] (0,0) -- (3,0);
1154 \end{tikzpicture}
1155 \end{codeexample}
1156
1157 All shapes are positioned by the anchor that is specified via the |anchor|
1158 decoration option:
1159
1160 \begin{key}{/pgf/decoration/anchor=\meta{anchor} (initially center)}
1161 The anchor used to position the shape backgrounds.
1162 \end{key}
1163
1164 A shape background path is added at the start point of the path and, if the
1165 distance between the shapes is appropriate, at the end point of the path.
1166 %
1167 \begin{codeexample}[preamble={\usetikzlibrary{decorations.shapes,shapes.geometric}}]
1168 \begin{tikzpicture}[decoration={
1169 shape backgrounds,shape=regular polygon,shape size=4mm}]
1170 \draw [help lines] grid (3,2);
1171 \draw [thick] (0,0) -- (2,2) (1,0) -- (3,0);
1172 \draw [red, decorate, decoration={shape sep=.5cm}] (1,0) -- (3,0);
1173 \draw [blue, decorate, decoration={shape sep=.5cm}] (0,0) -- (2,2);
1174 \end{tikzpicture}
1175 \end{codeexample}
1176
1177 Keys for customizing specific shapes can be specified (e.g., |star points|,
1178 |cloud puffs|, |kite angles|, and so on). The size of the shape is
1179 ``enforced'' using transformations. This means that the shape is typeset
1180 with an empty text box and some default size values, resulting in an
1181 initial shape. This shape is then rescaled using coordinate transformations
1182 so that it has the desired size (which may vary as we travel along the
1183 to-be-decorated path). This means that settings involving angles and
1184 distances may not appear entirely accurate. More general options such as
1185 |inner sep| and |minimum size| will be ignored, but transformations can be
1186 applied to each segment as described below.
1187 %
1188 \begin{codeexample}[preamble={\usetikzlibrary{decorations.shapes,shapes.geometric}}]
1189 \tikzset{
1190 paint/.style={draw=#1!50!black, fill=#1!50},
1191 my star/.style={decorate,decoration={shape backgrounds,shape=star},
1192 star points=#1}
1193 }
1194 \begin{tikzpicture}[decoration={shape sep=.5cm, shape size=.5cm}]
1195 \draw [my star=9, paint=red] (0,1.5) -- (3,1.5);
1196 \draw [my star=5, paint=blue] (0,.75) -- (3,.75);
1197 \draw [my star=5, paint=yellow, shape border rotate=30] (0,0) -- (3,0);
1198 \end{tikzpicture}
1199 \end{codeexample}
1200
1201 There are various keys to control the drawing of the shape decoration.
1202
1203 \begin{key}{/pgf/decoration/shape=\meta{shape name} (initially circle)}
1204 The shape whose background path is used.
1205 \end{key}
1206
1207 \begin{key}{/pgf/decoration/shape sep=\meta{spacing} (initially {.25cm, between centers})}
1208 Set the spacing between the shapes on the decorations path. This can be
1209 just a distance on its own, but the additional keywords
1210 |between centers|, and |between borders| (which must be preceded by a
1211 comma), specify that the distance is between the center anchors of the
1212 shapes or between the edges of the \emph{boundaries} of the shape
1213 borders.
1214 %
1215 \begin{codeexample}[preamble={\usetikzlibrary{decorations.shapes,shapes.symbols}}]
1216 \begin{tikzpicture}[
1217 decoration={shape backgrounds,shape size=.5cm,shape=signal},
1218 signal from=west, signal to=east,
1219 paint/.style={decorate, draw=#1!50!black, fill=#1!50}]
1220 \draw [help lines] grid (3,2);
1221 \draw [paint=red, decoration={shape sep=.5cm}]
1222 (0,2) -- (3,2);
1223 \draw [paint=green, decoration={shape sep={1cm, between centers}}]
1224 (0,1) -- (3,1);
1225 \draw [paint=blue, decoration={shape sep={1cm, between borders}}]
1226 (0,0) -- (3,0);
1227 \end{tikzpicture}
1228 \end{codeexample}
1229 \end{key}
1230
1231 \begin{key}{/pgf/decoration/shape evenly spread=\meta{number}}
1232 This key overrides the |shape sep| key and forces the decoration to fit
1233 \meta{number} shapes evenly across the path. If \meta{number} is less
1234 than |1|, then no shapes will be used. If \meta{number} equals |1|,
1235 then one shape is put in the middle of the path. The additional
1236 keywords |by centers| (the default, if no keyword is specified) and
1237 |by borders| can be used (both preceded by a comma), to specify how the
1238 distance between shapes is determined. These keywords will only have a
1239 noticeable effect if the shapes sizes differ over time.
1240 %
1241 \begin{codeexample}[preamble={\usetikzlibrary{decorations.shapes}}]
1242 \tikzset{
1243 paint/.style={draw=#1!50!black, fill=#1!50},
1244 spreading/.style={
1245 decorate,decoration={shape backgrounds, shape=rectangle,
1246 shape start size=4mm,shape end size=1mm,shape evenly spread={#1}}}
1247 }
1248 \begin{tikzpicture}
1249 \fill [paint=green,spreading={5, by borders},
1250 decoration={shape scaled}] (0,2) -- (3,2);
1251 \fill [paint=blue,spreading={5, by centers},
1252 decoration={shape scaled}] (0,1.5) -- (3,1.5);
1253 \fill [paint=red, spreading=5] (0,1) -- (3,1);
1254 \fill [paint=orange, spreading=4] (0,.5) -- (3,.5);
1255 \fill [paint=gray, spreading=1] (0,0) -- (3,0);
1256 \end{tikzpicture}
1257 \end{codeexample}
1258 \end{key}
1259
1260 \begin{key}{/pgf/decoration/shape sloped=\opt{\meta{boolean}} (initially true)}
1261 By default, shapes are rotated to the slope of the decorations path. If
1262 \meta{boolean} is the value |false|, then this rotation is turned off.
1263 Internally this sets the \TeX-if |\ifpgfshapedecorationsloped|
1264 accordingly.
1265 %
1266 \begin{codeexample}[preamble={\usetikzlibrary{decorations.shapes,shapes.geometric}}]
1267 \tikzset{
1268 paint/.style={draw=#1!50!black, fill=#1!50}
1269 }
1270 \begin{tikzpicture}[decoration={
1271 shape width=.65cm, shape height=.45cm,
1272 shape=isosceles triangle, shape sep=.75cm,
1273 shape backgrounds}]
1274 \draw [help lines] grid (3,2);
1275 \draw [paint=red,decorate] (0,0) -- (2,2);
1276 \draw [paint=blue,decorate,decoration={shape sloped=false}]
1277 (1,0) -- (3,2);
1278 \end{tikzpicture}
1279 \end{codeexample}
1280 \end{key}
1281
1282 It is possible to scale the width and height of the shapes along the length
1283 of the decorations path. The shapes are scaled between the starting size
1284 and the ending size. The following keys customize the way the decoration
1285 shapes are scaled:
1286
1287 \begin{key}{/pgf/decoration/shape scaled=\meta{boolean} (initially false)}
1288 \begin{codeexample}[preamble={\usetikzlibrary{decorations.shapes}}]
1289 \tikzset{
1290 bigger/.style={decoration={shape start size=.125cm, shape end size=.5cm}},
1291 smaller/.style={decoration={shape start size=.5cm, shape end size=.125cm}},
1292 decoration={shape backgrounds,
1293 shape sep={.25cm, between borders},shape scaled}
1294 }
1295 \begin{tikzpicture}
1296 \draw [help lines] grid (3,2);
1297 \fill [decorate, bigger, red!50] (0,1) -- (3,2);
1298 \fill [decorate, smaller, blue!50] (0,0) -- (3,1);
1299 \end{tikzpicture}
1300 \end{codeexample}
1301
1302 If this key is set to false (which is the default), then only the start
1303 width and height are used. Note that the keys |shape width| and
1304 |shape height| set the start and end height simultaneously.
1305 \end{key}
1306
1307 \begin{key}{/pgf/decoration/shape start width=\meta{length} (initially 2.5pt)}
1308 The starting width of the shape.
1309 \end{key}%
1310
1311 \begin{key}{/pgf/decoration/shape start height=\meta{length} (initially 2.5pt)}
1312 The starting height of the shape.
1313 \end{key}%
1314
1315 \begin{stylekey}{/pgf/decoration/shape start size=\meta{length}}
1316 Sets both the start height and start width simultaneously.
1317 \end{stylekey}%
1318
1319 \begin{key}{/pgf/decoration/shape end width=\meta{length} (initially 2.5pt)}
1320 The recommended ending width of the shape. Note that this is the width
1321 that a shape will take only if it is drawn exactly at the end of the
1322 path.
1323 %
1324 \begin{codeexample}[preamble={\usetikzlibrary{decorations.shapes}}]
1325 \tikzset{
1326 bigger/.style={decoration={shape start size=.25cm, shape end size=1cm}},
1327 smaller/.style={decoration={shape start size=1cm, shape end size=.25cm}},
1328 decoration={shape backgrounds,
1329 shape sep={.25cm, between borders},shape scaled}
1330 }
1331 \begin{tikzpicture}
1332 \draw [help lines] grid (3,2);
1333 \fill [decorate,bigger,
1334 decoration={shape sep={.25cm, between borders}}, blue!50]
1335 (0,1.5) -- (3,1.5);
1336 \fill [decorate,smaller,
1337 decoration={shape sep={1cm, between centers}}, red!50]
1338 (0,.5) -- (3,.5);
1339 \draw [gray, dotted] (0,1.625) -- (3,2) (0,1.375) -- (3,1)
1340 (0,1) -- (3,.625) (0,0) -- (3,.375);
1341 \end{tikzpicture}
1342 \end{codeexample}
1343 \end{key}
1344
1345 \begin{key}{/pgf/decoration/shape end height=\meta{length}}
1346 The recommended ending height of the shape.
1347 \end{key}
1348
1349 \begin{stylekey}{/pgf/decoration/shape end size=\meta{length}}
1350 Set both the end height and end width simultaneously.
1351 \end{stylekey}
1352 \end{decoration}
1353
1354
1355 \subsection{Text Decorations}
1356
1357 \begin{pgflibrary}{decorations.text}
1358 The decoration in this library decorates the path with some text. This can
1359 be used to draw text that follows a curve.
1360 \end{pgflibrary}
1361
1362 \begin{decoration}{text along path}
1363 This decoration decorates the path with text. This drawing of the text is a
1364 ``side effect'' of the decoration. The to-be-decorated path is only used to
1365 determine where the characters should be put and it is thrown away after
1366 the decoration is done. This is why no line is shown in the following
1367 example.
1368 %
1369 \begin{codeexample}[preamble={\usetikzlibrary{decorations.text}}]
1370 \catcode`\|12
1371 \begin{tikzpicture}[decoration={text along path,
1372 text={Some long text along a ridiculously long curve that}}]
1373 \draw [help lines] grid (3,2);
1374 \draw [decorate] (0,0) -- (3,1) arc (0:180:1.5 and 1);
1375 \end{tikzpicture}
1376 \end{codeexample}
1377
1378 \pgfname{} ``does its best'' to typeset the text, however you should note
1379 the following points:
1380 %
1381 \begin{itemize}
1382 \item Each character in the text is typeset in a separate |\hbox|. This
1383 means that if you want fancy things like kerning or ligatures you
1384 will have to manually annotate the characters in the decoration
1385 text within a group, for example, |W{\kern-1ptA}TER|.
1386 \item Each character is positioned using the center of its baseline. To
1387 move the text vertically (relative to the path), the additional
1388 decoration key |raise| should be used (see
1389 Section~\ref{section-decorations-adjust} for details).
1390 \item No attempt is made to ensure characters do not overlap when the
1391 angle between segments is considerably less than 180$^\circ$ (this
1392 is tricky to do in \TeX{} without a huge processing overhead). In
1393 general this should not be too much of a problem, but, once again,
1394 kerning can be used in most cases to overcome any undesirable
1395 effects.
1396 \item It is only possible to typeset text in math mode under
1397 considerable restrictions. Math mode is entered and exited using
1398 any character of category code 3 (e.g., in plain \TeX{} this is |$|). %$
1399 Math subscripts and superscripts need to be contained within
1400 braces (e.g., |{^y_i}|) as do commands like |\times| or |\cdot|.
1401 However, even modestly complex mathematical typesetting is
1402 unlikely to be successful along a path (or even desirable).
1403 \item Some inaccuracies in positioning may be particularly apparent at
1404 input segment boundaries. This can (unfortunately) only be solved
1405 on a case-by-case basis by individually kerning the offending
1406 characters within a group.
1407 \end{itemize}
1408
1409 The following keys are used by the |text| decoration:
1410 %
1411 \begin{key}{/pgf/decoration/text=\meta{text} (initially \normalfont empty)}
1412 Sets the text to typeset along the curve. Consecutive spaces are
1413 ignored, so |\ | (or |\space| in \LaTeX) should be used to insert
1414 multiple spaces. It is possible to format the text using normal
1415 formatting commands, such as |\it|, |\bf| and |\color|, within
1416 customizable delimiters. Initially these delimiters are both
1417 {\tt\char`\|} (however, care will be needed regarding the category
1418 codes of delimiters -- see below).
1419 %
1420 {\catcode`\|12
1421 \begin{codeexample}[preamble={\usetikzlibrary{decorations.text}}]
1422 \catcode`\|12
1423 \begin{tikzpicture}
1424 \draw [help lines] grid (3,2);
1425 \path [decorate,decoration={text along path,
1426 text={a big |\color{green}|green|| juicy apple.}}]
1427 (0,0) .. controls (0,2) and (3,0) .. (3,2);
1428 \end{tikzpicture}
1429 \end{codeexample}
1430 }
1431 %
1432 By following the first delimiter with |+|, the formatting commands are
1433 added to any existing formatting.
1434 %
1435 {\catcode`\|12
1436 \begin{codeexample}[preamble={\usetikzlibrary{decorations.text}}]
1437 \begin{tikzpicture}
1438 \draw [help lines] grid (3,2);
1439 \path [decorate,decoration={text along path,
1440 text={a |\large|big |+\bf\color{red}|red|| juicy apple.}}]
1441 (0,0) .. controls (0,2) and (3,0) .. (3,2);
1442 \end{tikzpicture}
1443 \end{codeexample}
1444 }
1445
1446 Internally, the text is stored in the macro |\pgfdecorationtext|. Any
1447 characters that have not been typeset when the end of the path has been
1448 reached will be stored in |\pgfdecorationrestoftext|.
1449 \end{key}
1450
1451 {\catcode`\|12
1452 \begin{key}{/pgf/decoration/text format delimiters=\marg{before}\marg{after} (initially \char`\{|\char`\}\char`\{\char`\})}
1453 \catcode`\|13
1454
1455 Set the characters that the text decoration will use to parse
1456 formatting commands. If \meta{after} is empty, then \meta{before} will
1457 be used for both delimiters. In general you should stick to characters
1458 whose category codes are |11| or |12|. As |+| is used to indicate that
1459 the specified format commands are added to any existing ones, you
1460 should avoid using |+| as a delimiter.
1461 %
1462 \begin{codeexample}[preamble={\usetikzlibrary{decorations.text}}]
1463 \begin{tikzpicture}
1464 \draw [help lines] grid (3,2);
1465 \path [decorate, decoration={text along path,text format delimiters={[}{]},
1466 text={A big [\color{red}]red[] and [\color{green}]green[] apple.}}]
1467 (0,0) .. controls (0,2) and (3,0) .. (3,2);
1468 \end{tikzpicture}
1469 \end{codeexample}
1470 \end{key}
1471 }
1472
1473 \begin{key}{/pgf/decoration/text color=\meta{color} (initially black)}
1474 The color of the text.
1475 \end{key}
1476
1477 \begin{key}{/pgf/decoration/reverse path=\meta{boolean} (initially false)}
1478 This key reverses the path. This is especially useful for typesetting
1479 text along different sides of curves.
1480 %
1481 \begin{codeexample}[preamble={\usetikzlibrary{decorations.text}}]
1482 \begin{tikzpicture}
1483 \draw [help lines] grid (3,2);
1484 \draw [gray, ->]
1485 [postaction={decoration={text along path,
1486 text={a big juicy apple}, text color=red}, decorate}]
1487 [postaction={decoration={text along path,
1488 text={a big juicy apple}, text color=blue, reverse path}, decorate}]
1489 (3,0) .. controls (3,2) and (0,2) .. (0,0);
1490 \end{tikzpicture}
1491 \end{codeexample}
1492 %
1493 \end{key}
1494
1495 \begin{key}{/pgf/decoration/text align={\ttfamily\char`\{}\meta{alignment options}{\ttfamily\char`\}}}
1496 This changes the key path to |/pgf/decoration/text align| and executes
1497 \meta{alignment options}.
1498 \end{key}
1499
1500 \begin{key}{/pgf/decoration/text align/align=\meta{alignment} (initially left)}
1501 Aligns the text according to \meta{alignment}, which should be one of
1502 |left|, |right|, or |center|.
1503 %
1504 \begin{codeexample}[preamble={\usetikzlibrary{decorations.text}}]
1505 \begin{tikzpicture}
1506 \draw [help lines] grid (3,2);
1507 \draw [red, dashed]
1508 [postaction={decoration={text along path, text={a big juicy apple},
1509 text align={align=right}}, decorate}]
1510 (0,0) .. controls (0,2) and (3,2) .. (3,0);
1511 \end{tikzpicture}
1512 \end{codeexample}
1513 \end{key}
1514
1515 \begin{stylekey}{/pgf/decoration/text align/left}
1516 Aligns the text to the left end of the path.
1517 \end{stylekey}
1518
1519 \begin{stylekey}{/pgf/decoration/text align/right}
1520 Aligns the text to the right end of the path.
1521 \end{stylekey}
1522
1523 \begin{stylekey}{/pgf/decoration/text align/center}
1524 Aligns the text to the center of the path.
1525 \end{stylekey}
1526
1527 \begin{key}{/pgf/decoration/text align/left indent=\meta{length} (initially 0pt)}
1528 Specifies a distance which the automaton should move along before it
1529 starts typesetting the text.
1530 \end{key}
1531
1532 \begin{key}{/pgf/decoration/text align/right indent=\meta{length} (initially 0pt)}
1533 Specifies a distance before the end of the path, where the automaton
1534 should stop typesetting the text.
1535 \end{key}
1536
1537 \begin{key}{/pgf/decoration/text align/fit to path=\meta{boolean} (initially false)}
1538 This key makes the decoration automaton try to fit the text to the
1539 length of the path. The automaton shifts forward by a small amount
1540 between each character in order to fit the text to the path. If,
1541 however, the length of the text is longer than the length of the path
1542 (i.e., the automaton would have to shift \emph{backwards} between
1543 characters) this key will have no effect.
1544 %
1545 \begin{codeexample}[preamble={\usetikzlibrary{decorations.text}}]
1546 \begin{tikzpicture}
1547 \draw [help lines] grid (3,2);
1548 \draw [red, dashed]
1549 [postaction={decoration={text along path, text={a big juicy apple},
1550 text align=fit to path}, decorate}]
1551 (0,0) .. controls (0,2) and (3,2) .. (3,0);
1552 \end{tikzpicture}
1553 \end{codeexample}
1554 %
1555 \end{key}
1556
1557 \begin{key}{/pgf/decoration/text align/fit to path stretching spaces=\meta{boolean} (initially false)}
1558 This key works like the previous key except the automaton shifts
1559 forward only for space characters (including |\space|, but
1560 \emph{excluding} |\ |).
1561 %
1562 \begin{codeexample}[preamble={\usetikzlibrary{decorations.text}}]
1563 \begin{tikzpicture}
1564 \draw [help lines] grid (3,2);
1565 \draw [red, dashed]
1566 [postaction={decoration={text along path, text={a big juicy apple},
1567 text align={fit to path stretching spaces}}, decorate}]
1568 (0,0) .. controls (0,2) and (3,2) .. (3,0);
1569 \end{tikzpicture}
1570 \end{codeexample}
1571 \end{key}
1572 \end{decoration}
1573
1574 \begin{decoration}{text effects along path}
1575 This decoration is similar to the |text along path| decoration except that
1576 each character is inserted into the picture as a \tikzname\ node, and node
1577 options (such as |text|, |scale| and |opacity|) can be used to create `text
1578 effects'.
1579 %
1580 \begin{codeexample}[preamble={\usetikzlibrary{decorations.text,math}}]
1581 \bfseries\large
1582 \begin{tikzpicture}[decoration={text effects along path,
1583 text={text effects along path!}, text align=center,
1584 text effects/.cd,
1585 character count=\i, character total=\n,
1586 characters={evaluate={\c=\i/\n*100;}, text along path, text=red!\c!orange},
1587 character widths={text along path, xslant=0, yscale=1}}]
1588
1589 \path [postaction={decorate}, preaction={decorate,
1590 text effects={characters/.append={yscale=-1.5, opacity=0.5,
1591 text=gray, xslant=(\i/\n-0.5)*3}}}]
1592 (0,0) .. controls ++(2,1) and ++(-2,-1) .. (3,4);
1593 \end{tikzpicture}
1594 \end{codeexample}
1595
1596 There are some important differences between this decoration and the
1597 |text along path| decoration:
1598 %
1599 \begin{itemize}
1600 \item formatting (e.g., font and color) cannot be specified in the
1601 decoration text. They can only be specified using the keys
1602 described below.
1603 \item as a consequence of using the \tikzname\ node options, this
1604 decoration is only available in \tikzname.
1605 \item due to the number of computations involved, this is quite a slow
1606 decoration.
1607 \end{itemize}
1608
1609 The following keys are shared with the |text along path| decoration:
1610
1611 \begin{key}{/pgf/decoration/text=\marg{text}}
1612 Set the text this decoration will use. Braces can be used to group
1613 multiple characters together, or commands that should not be expanded
1614 until they are typeset, for example |gr{\"o}{\ss}eren|. You should
1615 \emph{not} use the formatting delimiters or math mode characters that
1616 the |text along path| decoration supports.
1617 \end{key}
1618
1619 \begin{key}{/pgf/decoration/text align=\meta{align}}
1620 This sets the alignment of the text along the path. The \meta{align}
1621 argument should be |left|, |right| or |center|. Spreading the text out,
1622 or stretching the spaces between words is \emph{not} supported.
1623 \end{key}
1624
1625 The decoration text can be thought of as consisting of \emph{characters}
1626 arranged in to sequences of \emph{letters} to make \emph{words} which are
1627 separated by a \emph{word separator}. This, however, does not mean that you
1628 are limited to using only natural language as the decoration text.
1629 %
1630 \begin{codeexample}[preamble={\usetikzlibrary{decorations.text}}]
1631 \begin{tikzpicture}[decoration={text effects along path,
1632 text={000-001-010-011-100-101-110-111},
1633 text effects/.cd,
1634 path from text,
1635 word separator=-,
1636 every letter/.style={shape=rectangle, fill=blue!20, draw=blue!40}}]
1637
1638 \path [decorate] (0,0);
1639 \end{tikzpicture}
1640 \end{codeexample}
1641
1642 In addition, it is possible to replace characters with \tikzname\ code:
1643 %
1644 \begin{codeexample}[preamble={\usetikzlibrary{decorations.text}}]
1645 \begin{tikzpicture}[decoration={text effects along path,
1646 text={000-001-010-011-100-101-110-111}, text align=center,
1647 text effects/.cd,
1648 word separator=-,
1649 replace characters=0 with {\fill [purple] circle [radius=2pt]; },
1650 replace characters=1 with {\fill [orange] circle [radius=2pt]; },
1651 replace characters=- with {\path circle [radius=2pt]; },
1652 every letter/.style={shape=rectangle, fill=blue!20, draw=blue!40}}]
1653
1654 \path [decorate] (0,0) .. controls ++(2,0) and ++(-2,0) .. (3,4);
1655 \end{tikzpicture}
1656 \end{codeexample}
1657
1658 There are many keys and styles that can be used to add effects to the
1659 decoration text. Many of these keys have the parent path
1660 |/pgf/decoration/text effects/|, but for convenience, these keys can be
1661 accessed using the following key:
1662
1663 \begin{key}{/tikz/text effects=\marg{options}}
1664 Execute every option in \marg{options} with the key path for each option
1665 temporarily set to |/pgf/decoration/text effects/|.
1666 \end{key}
1667
1668 The following keys can be used to customise the
1669 appearance of text in the |text effects along path|
1670 decoration.
1671
1672 \begin{stylekey}{/pgf/decoration/text effects/every character}
1673 Set the effects that will be applied to every character in the
1674 decoration text. The effects will typically be \tikzname\ node options.
1675 Initially, this style is empty so the decoration simply positions nodes
1676 at the appropriate position along the path. In order to make the text
1677 `follow the path' like the |text along path| decoration the following
1678 key can be added to the |every character| style.
1679 \end{stylekey}
1680
1681 \begin{stylekey}{/pgf/decoration/text effects/text along path}
1682 This style automatically sets the \tikzname\ keys |transform shape| (to
1683 make the character slope with the path), |anchor=baseline| (to make the
1684 baseline of the characters `sit' on the path) and |inner xsep=0pt| (to
1685 horizontally fit each node to the character it contains, reducing the
1686 spacing between characters).
1687 %
1688 \begin{codeexample}[preamble={\usetikzlibrary{decorations.text}}]
1689 \begin{tikzpicture}[decoration={text effects along path,
1690 text={text effects along path!}}]
1691
1692 \path [draw=red, dotted, postaction={decorate}]
1693 (0,0) .. controls ++(1,0) and ++(-1,0) .. (3,2);
1694 \path [draw=blue, dotted, yshift=1cm, postaction={decorate},
1695 text effects={text along path}]
1696 (0,0) .. controls ++(1,0) and ++(-1,0) .. (3,2);
1697 \end{tikzpicture}
1698 \end{codeexample}
1699 \end{stylekey}
1700
1701 \begin{key}{/pgf/decoration/text effects/characters=\marg{effects}}
1702 Shorthand for the |every character|.
1703 \end{key}
1704
1705 \begin{stylekey}{/pgf/decoration/text effects/character \meta{number}}
1706 Specify additional effects for the character \meta{number}.
1707 \end{stylekey}
1708
1709 \begin{stylekey}{/pgf/decoration/text effects/every letter}
1710 Specify additional effects for every letter (i.e., every character that
1711 isn't the word separator) in the decoration text.
1712 \end{stylekey}
1713
1714 \begin{stylekey}{/pgf/decoration/text effects/letter \meta{number}}
1715 Specify the effects for letter \meta{number} in \emph{every} word.
1716 \end{stylekey}
1717
1718
1719 \begin{stylekey}{/pgf/decoration/text effects/every first letter}
1720 Specify additional effects for the first letter in \emph{every} word.
1721 \end{stylekey}
1722
1723 \begin{stylekey}{/pgf/decoration/text effects/every last letter}
1724 Specify additional effects for the last letter in \emph{every} word.
1725 \end{stylekey}
1726
1727 \begin{stylekey}{/pgf/decoration/text effects/every word}
1728 Specify additional effects for every word in the decoration text.
1729 \end{stylekey}
1730
1731 \begin{stylekey}{/pgf/decoration/text effects/word \meta{number}}
1732 Specify additional effects for word \meta{number} in the decoration text.
1733 \end{stylekey}
1734
1735 \begin{stylekey}{/pgf/decoration/text effects/word \meta{m} letter \meta{n}}
1736 Specify additional effects for letter \meta{n} in word \meta{m} in the
1737 decoration text.
1738 \end{stylekey}
1739
1740 \begin{stylekey}{/pgf/decoration/text effects/every word separator}
1741 Specify additional effects for every character that is a word separator.
1742 \end{stylekey}
1743
1744 \begin{key}{/pgf/decoration/text effects/word separator=\meta{character} (initially space)}
1745 Specify the character that is to be used as the word separator. This
1746 \emph{must} be a single character such as |a| or |-| or the special value
1747 |space| (which should be used to indicate that spaces should be used as the
1748 separator).
1749 \end{key}
1750
1751 By default, the width for each character is calculated according to the
1752 bounding box of the node in which it is contained. However, if the node is
1753 rotated or slanted, or has a substantial |inner sep|, this bounding box
1754 will be quite big. The following key enables different effects to be
1755 applied to the node that is used to calculate the width.
1756
1757 \begin{stylekey}{/pgf/decoration/text effects/every character width}
1758 This style is applied to the (invisible) nodes used for calculating the
1759 width of a character node.
1760 \end{stylekey}
1761
1762 \begin{key}{/pgf/decoration/text effects/character widths=\marg{effects}}
1763 Shorthand for the |every character width| style.
1764 %
1765 \begin{codeexample}[preamble={\usetikzlibrary{decorations.text}}]
1766 \begin{tikzpicture}[decoration={text effects along path,
1767 text={text effects along path!}, text align=center,
1768 text effects/.cd,
1769 character count=\i,
1770 characters={xslant=0.5, text along path, name=c-\i}}]
1771
1772 \path [decorate] (0,0) -- (3,2);
1773 \path [decorate,
1774 text effects={character widths={inner xsep=0pt, xslant=0}}]
1775 (0,1) -- (3,3);
1776 \end{tikzpicture}
1777 \end{codeexample}
1778 \end{key}
1779
1780 It is possible to parameterize effects, perhaps for doing calculations, or
1781 labelling nodes based on the number of the character in the decoration
1782 text. To access the number of the character, and the total number of
1783 characters the following keys can be used. However, these keys should
1784 \emph{not} be used inside the style keys given above.
1785
1786 \begin{key}{/pgf/decoration/text effects/character count=\meta{macro}}
1787 Store the number of the character being typeset in \meta{macro}.
1788 %
1789 \begin{codeexample}[preamble={\usetikzlibrary{decorations.text}}]
1790 \begin{tikzpicture}[decoration={text effects along path,
1791 text={text effects along path!},
1792 text effects/.cd,
1793 path from text,
1794 character count=\i, every word separator/.style={fill=red!30},
1795 characters={text along path, shape=circle, fill=gray!50}}]
1796
1797 \path [decorate, text effects={characters/.append={label=above:\footnotesize\i}}] (0,0);
1798 \end{tikzpicture}
1799 \end{codeexample}
1800 \end{key}
1801
1802 \begin{key}{/pgf/decoration/text effects/character total=\meta{macro}}
1803 Store the total number of the characters in the decoration text in
1804 \meta{macro}. This key can be used with the |character count| key to
1805 produce some quite pleasing effects:
1806 %
1807 \begin{codeexample}[preamble={\usetikzlibrary{decorations.text,math}}]
1808 \begin{tikzpicture}[decoration={text effects along path,
1809 text={text effects along path!},
1810 text effects/.cd,
1811 character count=\i, character total=\n,
1812 characters={text along path, evaluate={\c=\i/\n*100;},
1813 text=orange!\c!blue, scale=\i/\n+0.5}}]
1814
1815 \path [decorate]
1816 (0,0) .. controls ++(1,0) and ++(-1,0) .. (3,2);
1817 \end{tikzpicture}
1818 \end{codeexample}
1819 \end{key}
1820
1821 \begin{key}{/pgf/decoration/text effects/letter count=\meta{macro}}
1822 Store the number of letter being typeset (i.e., the position of the
1823 character in the word) in \meta{macro}. Numbering starts at |1| and the
1824 character acting as a word separator is numbered |0|.
1825 %
1826 \begin{codeexample}[preamble={\usetikzlibrary{decorations.text}}]
1827 \begin{tikzpicture}[decoration={text effects along path,
1828 text={text effects along path!},
1829 text effects/.cd,
1830 path from text, letter count=\i, every word separator/.style={fill=red!30},
1831 characters={text along path, shape=circle, fill=gray!50}}]
1832
1833 \path [decorate, text effects={characters/.append={label=above:\footnotesize\i}}] (0,0);
1834 \end{tikzpicture}
1835 \end{codeexample}
1836 \end{key}
1837
1838 \begin{key}{/pgf/decoration/text/effetcs/letter total=\meta{macro}}
1839 Store the number of letters in the current word in \meta{macro}. When
1840 the character is the word separator, this value is |0|.
1841 \end{key}
1842
1843 \begin{key}{/pgf/decoration/text effects/word count=\meta{macro}}
1844 Store the number of words in the decoration text in \meta{macro}.
1845 Numbering starts at |1|. When the character is the word separator,
1846 \meta{macro} takes the number of the previous word. If the decoration
1847 text starts with a word separator \meta{macro} will be |0|.
1848 %
1849 \begin{codeexample}[preamble={\usetikzlibrary{decorations.text}}]
1850 \begin{tikzpicture}[decoration={text effects along path,
1851 text={text effects along path!},
1852 text effects/.cd,
1853 path from text, word count=\i, every word separator/.style={fill=red!30},
1854 characters={text along path, shape=circle, fill=gray!50}}]
1855
1856 \path [decorate, text effects={characters/.append={label=above:\footnotesize\i}}] (0,0);
1857 \end{tikzpicture}
1858 \end{codeexample}
1859 %
1860 \end{key}
1861
1862 \begin{key}{/pgf/decoration/text effects/word total=\meta{macro}}
1863 Store the total number of words in the decoration text in \meta{macro}.
1864 \end{key}
1865
1866 It is also possible to apply effects to specific characters such as
1867 coloring every instance of the character |a|, or changing the font of every
1868 |T| in the decoration text:
1869
1870 \begin{key}{/pgf/decoration/text effects/style characters=\marg{characters} with \marg{effects}}
1871 This key enables \meta{effects} to be applied to every character in the
1872 decoration text that is specified in \meta{characters}.
1873 %
1874 \begin{codeexample}[preamble={\usetikzlibrary{decorations.text}}]
1875 \begin{tikzpicture}[decoration={text effects along path,
1876 text={Falsches {\"U}ben von Xylophonmusik qu{\"a}lt jeden gr{\"o}{\ss}eren Zwerg},
1877 text effects/.cd,
1878 path from text,
1879 style characters=aeiou{\"U}{\"a}{\"o} with {text=blue},
1880 characters={text along path}}]
1881
1882 \path [decorate] (0,0);
1883 \end{tikzpicture}
1884 \end{codeexample}
1885 \end{key}
1886
1887 \begin{key}{/pgf/decoration/text effects/path from text=\opt{\marg{true or false}} (default true)}
1888 When this key is set to |true| and the decorated path consists only of
1889 a single point, the decoration will calculate the width of the
1890 decoration text using all the specified parameters as if the decorated
1891 path was actually a straight line starting from the given point. This
1892 `virtual' straight line is then decorated with the text.
1893 %
1894 \begin{codeexample}[preamble={\usetikzlibrary{decorations.text}}]
1895 \begin{tikzpicture}[decoration={text effects along path,
1896 text={text effects along path!},
1897 text effects/.cd,
1898 path from text,
1899 character count=\i, character total=\n,
1900 characters={text along path, scale=\i/\n+0.5}}]
1901
1902 \path [decorate] (0,0);
1903 \end{tikzpicture}
1904 \end{codeexample}
1905 \end{key}
1906
1907 \begin{key}{/pgf/decoration/text effects/path from text angle=\meta{angle}}
1908 When used in conjunction with the |path from text| key, the straight
1909 line that is used as the decorated path is rotated by \meta{angle}
1910 around the starting point.
1911 %
1912 \begin{codeexample}[preamble={\usetikzlibrary{decorations.text}}]
1913 \begin{tikzpicture}[decoration={text effects along path,
1914 text={text effects along path!},
1915 text effects/.cd,
1916 path from text, path from text angle=60,
1917 character count=\i, character total=\n,
1918 characters={text along path, scale=\i/\n+0.5}}]
1919
1920 \path [decorate] (0,0);
1921 \end{tikzpicture}
1922 \end{codeexample}
1923 \end{key}
1924
1925 \begin{key}{/pgf/decoration/text effects/fit text to path=\opt{\meta{true or false}} (default true)}
1926 This key will make the decoration increase the space between characters
1927 so that the entire path is used by the decoration.
1928 %
1929 \begin{codeexample}[preamble={\usetikzlibrary{decorations.text}}]
1930 \begin{tikzpicture}[decoration={text effects along path,
1931 text={text effects along path!},
1932 text effects/every character/.style={text along path}}]
1933
1934 \path [draw=gray, postaction={decorate}, rotate=90]
1935 (0,0) .. controls ++(2,0) and ++(-1,0) .. (5,-1);
1936 \path [draw=gray, postaction={decorate}, rotate=90, yshift=-1cm,
1937 text effects={fit text to path}]
1938 (0,0) .. controls ++(2,0) and ++(-1,0) .. (5,-1);
1939 \end{tikzpicture}
1940 \end{codeexample}
1941 %
1942 \end{key}
1943
1944 \begin{key}{/pgf/decoration/text effects/scale text to path=\opt{\meta{true or false}} (default true)}
1945 This key will make the decoration scale the text so that the entire
1946 path is used by the decoration.
1947 %
1948 \begin{codeexample}[preamble={\usetikzlibrary{decorations.text}}]
1949 \begin{tikzpicture}[decoration={text effects along path,
1950 text={text effects along path!},
1951 text effects/every character/.style={text along path}}]
1952
1953 \path [draw=gray, postaction={decorate}, rotate=90]
1954 (0,0) .. controls ++(2,0) and ++(-1,0) .. (5,-1);
1955 \path [draw=gray, postaction={decorate}, rotate=90, yshift=-1cm,
1956 text effects={scale text to path}]
1957 (0,0) .. controls ++(2,0) and ++(-1,0) .. (5,-1);
1958 \end{tikzpicture}
1959 \end{codeexample}
1960 %
1961 \end{key}
1962
1963 \begin{key}{/pgf/decoration/text effects/reverse text}
1964 Reverse the order of the characters in the decoration text. This may be
1965 useful if using `right-to-left` languages. Unfortunately, any leading
1966 `soft' spaces in the original text will be lost.
1967 %
1968 \begin{codeexample}[preamble={\usetikzlibrary{decorations.text}}]
1969 \begin{tikzpicture}[decoration={text effects along path,
1970 text={text effects along path!},
1971 text effects/.cd,
1972 path from text, path from text angle=60,
1973 reverse text,
1974 character count=\i, character total=\n,
1975 characters={text along path, scale=\i/\n+0.5}}]
1976
1977 \path [decorate] (0,0) .. controls ++(1,0) and ++(-1,0) .. (3,2);
1978 \end{tikzpicture}
1979 \end{codeexample}
1980
1981 It is important to note that the |reverse text| key reverses the text
1982 \emph{before} doing anything else. This means that the numbering of
1983 characters, letters and words will still be in the normal order, so any
1984 parameterized effects will have to take this into account.
1985 Alternatively, to get the numbering to follow the reversed text, it is
1986 possible to reverse the path and then invert the scale:
1987 %
1988 \begin{codeexample}[preamble={\usetikzlibrary{decorations.text}}]
1989 \begin{tikzpicture}[decoration={text effects along path,
1990 text={text effects along path!},
1991 text effects/.cd,
1992 path from text, path from text angle=60,
1993 character count=\i, character total=\n,
1994 characters={text along path, scale=\i/\n+0.5}}]
1995
1996 \path [decorate, text effects={reverse text}] (0,0);
1997 \path [blue, decorate, decoration={reverse path},
1998 text effects={characters/.append={scale=-1}}] (1,0);
1999 \end{tikzpicture}
2000 \end{codeexample}
2001 %
2002 \end{key}
2003
2004 \begin{key}{/pgf/decoration/text effects/group letters}
2005 Group sequences of letters together so they are treated as a single
2006 `character'.
2007 %
2008 \begin{codeexample}[preamble={\usetikzlibrary{decorations.text}}]
2009 \begin{tikzpicture}[decoration={text effects along path,
2010 text={text effects along path!},
2011 text effects/.cd,
2012 path from text, path from text angle=60,
2013 every word separator/.style={fill=none},
2014 character count=\i, character total=\n,
2015 characters={text along path, fill=gray!50, scale=\i/\n+0.5}}]
2016
2017 \path [decorate] (0,0);
2018 \path [decorate, text effects={group letters,
2019 characters/.append={fill=red!20}}]
2020 (1,0);
2021 \end{tikzpicture}
2022 \end{codeexample}
2023 \end{key}
2024
2025 The order in which the |reverse text| and |group letters| keys are applied
2026 is important:
2027 %
2028 \begin{codeexample}[preamble={\usetikzlibrary{decorations.text}}]
2029 \begin{tikzpicture}[decoration={text effects along path,
2030 text={text effects along path!},
2031 text effects/.cd,
2032 path from text, path from text angle=60,
2033 every word separator/.style={fill=none},
2034 character count=\i, character total=\n,
2035 characters={text along path, fill=gray!50, scale=\i/\n+0.5}}]
2036
2037 \path [decorate, text effects={reverse text, group letters}] (0,0);
2038 \path [decorate, text effects={group letters, reverse text,
2039 characters/.append={fill=red!20}}] (1,0);
2040 \end{tikzpicture}
2041 \end{codeexample}
2042
2043 \begin{key}{/pgf/decoration/text effects/repeat text=\opt{\meta{times}}}
2044 Usually, when the decoration runs out of text, it simply stops. This
2045 key will make the decoration repeat the decoration text for the
2046 specified number of \meta{times}. If no value is given the text will be
2047 repeated until the path is finished. There are two points to remember
2048 however. Firstly the numbering of characters, letters and words will be
2049 restarted each time the text is repeated. Secondly, the options for
2050 alignment, scaling or fitting the text to the path, fitting the path to
2051 the text, and so on, are computed using the decoration text before the
2052 decoration starts. If any of these options are given the behavior of
2053 the |repeat text| key is undefined, but typically it will be ignored.
2054 %
2055 \begin{codeexample}[preamble={\usetikzlibrary{decorations.text}}]
2056 \begin{tikzpicture}[decoration={text effects along path,
2057 text={text effects along path!\ },
2058 text effects/.cd,
2059 repeat text,
2060 character count=\m, character total=\n,
2061 characters={text along path, scale=0.5+\m/\n/2}}]
2062
2063 \path [draw=gray, ultra thin, postaction=decorate]
2064 (180:2) \foreach \a in {0,...,12}{ arc (180-\a*90:90-\a*90:1.5-\a/10) };
2065 \end{tikzpicture}
2066 \end{codeexample}
2067 \end{key}
2068
2069 \begin{key}{/pgf/decoration/text effects/character command=\meta{macro}}
2070 This key specifies a command that is executed when each character is
2071 placed in the node. The \meta{macro} should be an ordinary \TeX\ macro
2072 which takes one argument. The argument will be a macro which when
2073 expanded will contain the current character.
2074 %
2075 \begin{codeexample}[preamble={\usetikzlibrary{decorations.text}}]
2076 \def\mycommand#1{#1$_\n$}
2077 \begin{tikzpicture}[decoration={text effects along path,
2078 text={text effects along path!},
2079 text effects/.cd,
2080 path from text, path from text angle=60, group letters,
2081 word count=\n,
2082 every word/.style={character command=\mycommand},
2083 characters={text along path}}]
2084
2085 \path [decorate] (0,0);
2086 \end{tikzpicture}
2087 \end{codeexample}
2088 \end{key}
2089
2090 \begin{key}{/pgf/decoration/text effects/replace characters=\meta{characters} with \marg{code}}
2091 Replace the node for each character in \meta{characters} with
2092 \meta{code}. The \meta{code} can be thought of as describing a little
2093 picture or marking which will be used instead of the character node.
2094 The origin will be the current point along the decoration path. Any
2095 transformations associated with the \meta{characters} (e.g., applied
2096 with the |every character| or |every letter| styles) will also be
2097 applied to \meta{code}.
2098 %
2099 \begin{codeexample}[preamble={\usetikzlibrary{decorations.text}}]
2100 \begin{tikzpicture}[decoration={text effects along path,
2101 text={text effects along path!},
2102 text effects/.cd,
2103 path from text, path from text angle=60,
2104 replace characters=e with {\fill [red!20] (0,1mm) circle [radius=1mm];},
2105 replace characters=a with {\fill [black!20] (0,1mm) circle [radius=1mm];},
2106 character count=\i, character total=\n,
2107 characters={text along path, scale=\i/\n+0.5}}]
2108
2109 \path [decorate] (0,0);
2110 \end{tikzpicture}
2111 \end{codeexample}
2112 \end{key}
2113 \end{decoration}
2114
2115
2116 \subsection{Fractal Decorations}
2117
2118 \begin{pgflibrary}{decorations.fractals}
2119 The decorations of this library can be used to create fractal lines. To use
2120 them, you typically have to apply the decoration repeatedly to an
2121 originally straight path.
2122 \end{pgflibrary}
2123
2124 \begin{decoration}{Koch curve type 1}
2125 This decoration replaces a straight line by a ``rectangular bump''. By
2126 repeatedly applying this replacement, different levels of the Koch curve
2127 fractal can be created. Its Hausdorff dimension is $\log 5/\log 3$.
2128 %
2129 \begin{codeexample}[preamble={\usetikzlibrary{decorations.fractals}}]
2130 \begin{tikzpicture}[decoration=Koch curve type 1]
2131 \draw decorate{ (0,0) -- (3,0) };
2132 \draw decorate{ decorate{ (0,-1.5) -- (3,-1.5) }};
2133 \draw decorate{ decorate{ decorate{ (0,-3) -- (3,-3) }}};
2134 \end{tikzpicture}
2135 \end{codeexample}
2136 %
2137 \end{decoration}
2138
2139 \begin{decoration}{Koch curve type 2}
2140 This decoration replaces a straight line by a ``rectangular sine''. Its
2141 Hausdorff dimension is $3/2$.
2142 %
2143 \begin{codeexample}[preamble={\usetikzlibrary{decorations.fractals}}]
2144 \begin{tikzpicture}[decoration=Koch curve type 2]
2145 \draw decorate{ (0,0) -- (3,0) };
2146 \draw decorate{ decorate{ (0,-2) -- (3,-2) }};
2147 \draw decorate{ decorate{ decorate{ (0,-4) -- (3,-4) }}};
2148 \end{tikzpicture}
2149 \end{codeexample}
2150 %
2151 \end{decoration}
2152
2153 \begin{decoration}{Koch snowflake}
2154 This decoration replaces a straight line by a ``line with a spike''. The
2155 Hausdorff dimension of Koch's snowflake's is $\log 4/\log 3$.
2156 %
2157 \begin{codeexample}[preamble={\usetikzlibrary{decorations.fractals}}]
2158 \begin{tikzpicture}[decoration=Koch snowflake]
2159 \draw decorate{ (0,0) -- (3,0) };
2160 \draw decorate{ decorate{ (0,-1) -- (3,-1) }};
2161 \draw decorate{ decorate{ decorate{ (0,-2) -- (3,-2) }}};
2162 \draw decorate{ decorate{ decorate{ decorate{ (0,-3) -- (3,-3) }}}};
2163 \end{tikzpicture}
2164 \end{codeexample}
2165 %
2166 \end{decoration}
2167
2168 \begin{decoration}{Cantor set}
2169 This decoration replaces a straight line by a ``line with a gap in the
2170 middle''. The Hausdorff dimension of the Cantor set is $\log 2/\log 3$.
2171 %
2172 \begin{codeexample}[preamble={\usetikzlibrary{decorations.fractals}}]
2173 \begin{tikzpicture}[decoration=Cantor set,very thick]
2174 \draw decorate{ (0,0) -- (3,0) };
2175 \draw decorate{ decorate{ (0,-.5) -- (3,-.5) }};
2176 \draw decorate{ decorate{ decorate{ (0,-1) -- (3,-1) }}};
2177 \draw decorate{ decorate{ decorate{ decorate{ (0,-1.5) -- (3,-1.5) }}}};
2178 \end{tikzpicture}
2179 \end{codeexample}
2180 %
2181 \end{decoration}