| 1 |
% Copyright 2019 by Till Tantau and Mark Wibrow |
| 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{Decorations} |
| 12 |
\label{section-base-decorations} |
| 13 |
|
| 14 |
\begin{pgfmodule}{decorations} |
| 15 |
The commands for creating decorations are defined in this module, so you |
| 16 |
need to load this module to use decorations. This module is automatically |
| 17 |
loaded by the different decoration libraries. |
| 18 |
\end{pgfmodule} |
| 19 |
|
| 20 |
|
| 21 |
\subsection{Overview} |
| 22 |
|
| 23 |
Decorations are a general way of creating graphics by ``moving along'' a path |
| 24 |
and, while doing so, either drawing something or constructing a new path. This |
| 25 |
could be as simple as extending a path with a ``zigzagged'' line\ldots |
| 26 |
% |
| 27 |
\begin{codeexample}[preamble={\usetikzlibrary{decorations,decorations.pathmorphing}}] |
| 28 |
\tikz \draw decorate[decoration=zigzag] {(0,0) -- (3,0)}; |
| 29 |
\end{codeexample} |
| 30 |
% |
| 31 |
\ldots but could also be as complex as typesetting text along a path: |
| 32 |
% |
| 33 |
{\catcode`\|12 |
| 34 |
\begin{codeexample}[preamble={\usetikzlibrary{decorations,decorations.text}}] |
| 35 |
\tikz \path decorate [decoration={text along path, |
| 36 |
text={Some text along a path}}] |
| 37 |
{ (0,2) .. controls (2,2) and (1,0) .. (3,0) }; |
| 38 |
\end{codeexample} |
| 39 |
} |
| 40 |
|
| 41 |
The workflow for using decorations is the following: |
| 42 |
% |
| 43 |
\begin{enumerate} |
| 44 |
\item You define a decoration using the |\pgfdeclaredecoration| command. |
| 45 |
Different useful decorations are already declared in libraries like |
| 46 |
|decorations.shapes|. |
| 47 |
\item You use normal path construction commands like |\pgfpathlineto| to |
| 48 |
construct a path. Let us call this path the \emph{to-be-decorated} |
| 49 |
path. |
| 50 |
\item You place the path construction commands inside the environment |
| 51 |
|{pgfdecoration}|. This environment takes the name of a previously |
| 52 |
declared decoration as a parameter. It will then start ``walking |
| 53 |
along'' the to-be-decorated path. As it does this, a special finite |
| 54 |
automaton called a \emph{decoration automaton} produces new path |
| 55 |
commands as its output (or even other outputs). These outputs replace |
| 56 |
the to-be-decorated path; indeed, after the to-be-decorated path has |
| 57 |
been fully walked along it is thrown away, only the output of the |
| 58 |
automaton persists. |
| 59 |
\end{enumerate} |
| 60 |
|
| 61 |
In the present section the process of how decoration automata work is explained |
| 62 |
first. Then the command(s) for declaring decoration automata and for using them |
| 63 |
are covered. |
| 64 |
|
| 65 |
|
| 66 |
\subsection{Decoration Automata} |
| 67 |
|
| 68 |
Decoration automata (and the closely related meta-decoration automata) are a |
| 69 |
general concept for creating graphics ``along paths''. For straight lines, this |
| 70 |
idea was first proposed by Till Tantau in an earlier version of \pgfname, the |
| 71 |
idea to extend this to arbitrary path was proposed and implemented by Mark |
| 72 |
Wibrow. Further versatility is provided by ``meta-decorations''. These are |
| 73 |
automata that decorate a path with decorations. |
| 74 |
|
| 75 |
In the present subsection the different ideas underlying decoration automata |
| 76 |
are presented. |
| 77 |
|
| 78 |
|
| 79 |
\subsubsection{The Different Paths} |
| 80 |
|
| 81 |
In order to prevent confusion with different types of paths, such as those that |
| 82 |
are extended, those that are decorated and those that are created, the |
| 83 |
following conventions will be used: |
| 84 |
% |
| 85 |
\begin{itemize} |
| 86 |
\item The \emph{preexisting} path refers to the current path in existence |
| 87 |
before a decoration environment. (Possibly this path has been created |
| 88 |
by another decoration used earlier, but we will still call this path |
| 89 |
the preexisting path also in this case.) |
| 90 |
\item The \emph{input} path refers to the to-be-decorated path that the |
| 91 |
decoration automaton moves along. The input path may consist of many |
| 92 |
line and curve input segments (for example, a circle or an ellipse |
| 93 |
consists of four curves). It is specified inside the decoration |
| 94 |
environment. |
| 95 |
\item The \emph{output} path refers to the path that the decoration |
| 96 |
creates. Depending on the decoration, this path may or may not be empty |
| 97 |
(a decoration can also choose to use side-effects instead of producing |
| 98 |
an output path). The input path is always consumed by the decoration |
| 99 |
automaton, that is, it is no longer available in any way after the |
| 100 |
decoration automaton has finished. |
| 101 |
\end{itemize} |
| 102 |
|
| 103 |
The effect of a decoration environment is the following: The input path, which |
| 104 |
is specified inside the environment, is constructed and stored. This process |
| 105 |
does not alter the preexisting path in any way. Then the decoration automaton |
| 106 |
is started (as described later) and it produces an output path (possibly |
| 107 |
empty). Whenever part of the output path is produced, it is concatenated with |
| 108 |
the preexisting path. After the environment, the current path will equal the |
| 109 |
original preexisting path followed by the output path. |
| 110 |
|
| 111 |
It is permissible that a decoration issues a |\pgfusepath| command. As usual, |
| 112 |
this causes the current path to be filled or stroked or some other action to be |
| 113 |
taken and the current path is set to the empty path. As described above, when |
| 114 |
the decoration automaton starts, the current path is the preexisting path and |
| 115 |
as the automaton progresses, the current path is constantly being extended by |
| 116 |
the output path. This means that first time a |\pgfusepath| command is used on |
| 117 |
a decoration, the preexisting path is part of the path this command operates |
| 118 |
on; in subsequent calls only the part of the output path constructed since the |
| 119 |
last |\pgfusepath| command will be used. |
| 120 |
|
| 121 |
You can use this mechanism to stroke or fill different parts of the output path |
| 122 |
in different colors, line widths, fills and shades; all within the same |
| 123 |
decoration. Alternatively, a decoration can choose to produce no output path at |
| 124 |
all: the |text| decoration simply typesets text along a path. |
| 125 |
|
| 126 |
|
| 127 |
\subsubsection{Segments and States} |
| 128 |
|
| 129 |
The most common use of a decoration is to ``repeat something along a path'' |
| 130 |
(for example, the |zigzag| decoration repeats |
| 131 |
% |
| 132 |
\tikz\draw decorate[decoration=zigzag] {(0,0)--(\pgfdecorationsegmentlength,0)}; |
| 133 |
% |
| 134 |
along a path). However, it not necessarily the case that only one thing is |
| 135 |
repeated: a decoration can consist of different parts, or \emph{segments}, |
| 136 |
repeated in a particular order. |
| 137 |
|
| 138 |
When you declare a decoration, you provide a description of how their different |
| 139 |
segments will be rendered. The description of each segment should be given in a |
| 140 |
way as if the ``$x$-axis'' of the segment is the tangent to the path at a |
| 141 |
particular point, and that point is the origin of the segment. Thus, for |
| 142 |
example, the segment of the |zigzag| decoration might be defined using the |
| 143 |
following code: |
| 144 |
% |
| 145 |
\begin{codeexample}[code only] |
| 146 |
\pgfpathlineto{\pgfpoint{5pt}{5pt}} |
| 147 |
\pgfpathlineto{\pgfpoint{15pt}{-5pt}} |
| 148 |
\pgfpathlineto{\pgfpoint{20pt}{0pt}} |
| 149 |
\end{codeexample} |
| 150 |
|
| 151 |
\pgfname\ will ensure that an appropriate coordinate transformation is in place |
| 152 |
when the segment is rendered such that the segment actually points in the right |
| 153 |
direction. Also, subsequent segments will be transformed such that they are |
| 154 |
``further along the path'' toward the end of the path. All transformations are |
| 155 |
set up automatically. |
| 156 |
|
| 157 |
Note that we did not use a |\pgfpathmoveto{\pgfpointorigin}| at the beginning |
| 158 |
of the segment code. Doing so would subdivide the path into numerous subpaths. |
| 159 |
Rather, we assume that the previous segment caused the current point to be at |
| 160 |
the origin. |
| 161 |
|
| 162 |
The width of a segment can (and must) be specified explicitly. \pgfname\ will |
| 163 |
use this width to find out the start point of the next segment and the correct |
| 164 |
rotation. The width the you provide need not be the ``real'' width of the |
| 165 |
segment, which allows decoration segments to overlap or to be spaced far apart. |
| 166 |
|
| 167 |
The |zigzag| decoration only has one segment that is repeated again and again. |
| 168 |
However, we might also like to have \emph{different} segments and use rules to |
| 169 |
describe which segment should be used where. For example, we might have special |
| 170 |
segments at the start and at the end. |
| 171 |
|
| 172 |
Decorations use a mechanism known in theoretical in computer science as |
| 173 |
\emph{finite state automata} to describe which segment is used at a particular |
| 174 |
point. The idea is the following: For the first segment we start in a special |
| 175 |
\emph{state} called the \emph{initial state}. In this state, and also in all |
| 176 |
other states later, \pgfname\ first computes how much space is left on the |
| 177 |
input path. That is, \pgfname\ keeps track of the distance to the end of the |
| 178 |
input path. Attached to each state there is a set of rules of the following |
| 179 |
form: ``If the remaining distance on the input path is less than $x$, switch to |
| 180 |
state~$q$.'' \pgfname\ checks for each of these rules whether it applies and, |
| 181 |
if so, immediately switches to state~$q$. |
| 182 |
|
| 183 |
Only if none of the rules tell us to switch to another state, \pgfname\ will |
| 184 |
execute the state's code. This code will (typically) add a segment to the |
| 185 |
output path. In addition to the rules there is also a width parameter attached |
| 186 |
to each state. \pgfname\ then translates the coordinate system by this width |
| 187 |
and reduces the remaining distance on the input path. Then, \pgfname\ either |
| 188 |
stays in the current state or switches to another state, depending on yet |
| 189 |
another property attached of the state. |
| 190 |
|
| 191 |
The whole process stops when a special state called |final| is reached. The |
| 192 |
segment of this state is immediately added to the output path (it is often |
| 193 |
empty, though) and the process ends. |
| 194 |
|
| 195 |
|
| 196 |
\subsection{Declaring Decorations} |
| 197 |
|
| 198 |
The following command is used to declare a decoration. Essentially, this |
| 199 |
command describes the decoration automaton. |
| 200 |
|
| 201 |
\begin{command}{\pgfdeclaredecoration\marg{name}\marg{initial state}\marg{states}} |
| 202 |
This command declares a new decoration called \meta{name}. The |
| 203 |
\meta{states} argument contains a description of the decoration automaton's |
| 204 |
states and the transitions between them. The \meta{initial state} is the |
| 205 |
state in which the automaton starts. |
| 206 |
|
| 207 |
When the automaton is later applied to an input path, it keeps track of a |
| 208 |
certain position on the input path. This current point will ``travel along |
| 209 |
the path'', each time being moved along by a certain distance. This will |
| 210 |
also work if the path is not a straight line. That is, it is permissible |
| 211 |
that the path curves are veers at a sharp angle. It is also permissible |
| 212 |
that while traveling along the input path, the current input segment ends |
| 213 |
and a new input segment starts. In this case, the remaining distance on the |
| 214 |
first input segment is subtracted from the \meta{dimension} and then we |
| 215 |
travel along the second input segment for the remaining distance. This |
| 216 |
input segment may also end early, in which case we travel along the next |
| 217 |
input segment, and so on. Note that it cannot happen that we travel past |
| 218 |
the end of the input path since this would have caused an immediate switch |
| 219 |
to the |final| state. |
| 220 |
|
| 221 |
Note that the computation of the path lengths has only a low accuracy |
| 222 |
because of \TeX's small math capabilities. Do not expect high accuracy |
| 223 |
alignments when using decorations (unless the input path consists only of |
| 224 |
horizontal and vertical lines). |
| 225 |
|
| 226 |
The \meta{states} argument should consist of |\state| commands, one for |
| 227 |
each state of the decoration automaton. The |\state| command is defined |
| 228 |
only when the \meta{states} argument is executed. |
| 229 |
|
| 230 |
\begin{command}{\state\marg{name}\oarg{options}\marg{code}} |
| 231 |
This command declares a new state inside the current decoration |
| 232 |
automaton. The state is named \meta{name}. |
| 233 |
|
| 234 |
When the decoration automaton is in state \meta{name}, the following |
| 235 |
things happen: |
| 236 |
% |
| 237 |
\begin{enumerate} |
| 238 |
\item The \meta{options} are parsed. This may lead to a state |
| 239 |
switch, see below. When this happens, the following steps are |
| 240 |
not executed. The \meta{options} are executed one after the |
| 241 |
other in the given order. If an option causes a state switch, |
| 242 |
the switch is immediate, even if later options might cause a |
| 243 |
different state switch. |
| 244 |
\item The \meta{code} is executed in a \TeX-group with the current |
| 245 |
transformation matrix set up in such a way that the origin is |
| 246 |
on the input path at the current point (the point at the |
| 247 |
distance traveled up to now) and the coordinate system is |
| 248 |
rotated in such a way that the positive $x$-axis points in the |
| 249 |
direction of the tangent to the input path at the current |
| 250 |
point, while the positive $y$-axis points to the left of this |
| 251 |
tangent. |
| 252 |
|
| 253 |
As described earlier, the \meta{code} can have two different |
| 254 |
effects: If it just contains path construction commands, the |
| 255 |
decoration will produce an output path, that is, it extends the |
| 256 |
preexisting path. Here is an example: |
| 257 |
% |
| 258 |
\begin{codeexample}[preamble={\usetikzlibrary{decorations}}] |
| 259 |
\pgfdeclaredecoration{example}{initial} |
| 260 |
{ |
| 261 |
\state{initial}[width=10pt] |
| 262 |
{ |
| 263 |
\pgfpathlineto{\pgfpoint{0pt}{5pt}} |
| 264 |
\pgfpathlineto{\pgfpoint{5pt}{5pt}} |
| 265 |
\pgfpathlineto{\pgfpoint{5pt}{-5pt}} |
| 266 |
\pgfpathlineto{\pgfpoint{10pt}{-5pt}} |
| 267 |
\pgfpathlineto{\pgfpoint{10pt}{0pt}} |
| 268 |
} |
| 269 |
\state{final} |
| 270 |
{ |
| 271 |
\pgfpathlineto{\pgfpointdecoratedpathlast} |
| 272 |
} |
| 273 |
} |
| 274 |
\tikz[decoration=example] |
| 275 |
{ |
| 276 |
\draw [decorate] (0,0) -- (3,0); |
| 277 |
\draw [red,decorate] (0,0) to [out=45,in=135] (3,0); |
| 278 |
} |
| 279 |
\end{codeexample} |
| 280 |
|
| 281 |
Alternatively, the \meta{code} can also contain the |
| 282 |
|\pgfusepath| command. This will use the path in the usual |
| 283 |
manner, where ``the path'' is the preexisting path plus a part |
| 284 |
of the output path for the first invocation and the different |
| 285 |
parts of the rest of the output path for the following |
| 286 |
invocation. Here is an example: |
| 287 |
% |
| 288 |
\begin{codeexample}[pre={\pgfmathsetseed{1}},preamble={\usetikzlibrary{decorations,shapes.geometric}}] |
| 289 |
\pgfdeclaredecoration{stars}{initial}{ |
| 290 |
\state{initial}[width=15pt] |
| 291 |
{ |
| 292 |
\pgfmathparse{round(rnd*100)} |
| 293 |
\pgfsetfillcolor{yellow!\pgfmathresult!orange} |
| 294 |
\pgfsetstrokecolor{yellow!\pgfmathresult!red} |
| 295 |
\pgfnode{star}{center}{}{}{\pgfusepath{stroke,fill}} |
| 296 |
} |
| 297 |
\state{final} |
| 298 |
{ |
| 299 |
\pgfpathmoveto{\pgfpointdecoratedpathlast} |
| 300 |
} |
| 301 |
} |
| 302 |
\tikz\path[decorate, decoration=stars, star point ratio=2, star points=5, |
| 303 |
inner sep=0, minimum size=rnd*10pt+2pt] |
| 304 |
(0,0) .. controls (0,2) and (3,2) .. (3,0) |
| 305 |
.. controls (3,-3) and (0,0) .. (0,-3) |
| 306 |
.. controls (0,-5) and (3,-5) .. (3,-3); |
| 307 |
\end{codeexample} |
| 308 |
% |
| 309 |
\item After the \meta{code} has been executed (possibly more than |
| 310 |
once, if the |repeat state| option is used), the state switches |
| 311 |
to whatever state has been specified inside the \meta{options} |
| 312 |
using the |next state| option. If no |next state| has been |
| 313 |
specified, the state stays the same. |
| 314 |
\end{enumerate} |
| 315 |
|
| 316 |
The \meta{options} are executed with the key path set to |
| 317 |
|/pgf/decoration automaton|. The following keys are defined: |
| 318 |
% |
| 319 |
\begin{key}{/pgf/decoration automaton/switch if less than=\meta{dimension}\texttt{ to }\meta{new state}} |
| 320 |
When this key is encountered, \pgfname\ checks whether the |
| 321 |
remaining distance to the end of the input path is less than |
| 322 |
\meta{dimension}. If so, an immediate state switch to \meta{new |
| 323 |
state} occurs. |
| 324 |
\end{key} |
| 325 |
% |
| 326 |
\begin{key}{/pgf/decoration automaton/switch if input segment less than=\\\meta{dimension}\texttt{ to }\meta{new state}} |
| 327 |
When this key is encountered, \pgfname\ checks whether the |
| 328 |
remaining distance to the end of the current input segment of the |
| 329 |
input path is less than \meta{dimension}. If so, an immediate state |
| 330 |
switch to \meta{new state} occurs. |
| 331 |
\end{key} |
| 332 |
% |
| 333 |
\begin{key}{/pgf/decoration automaton/width=\meta{dimension}} |
| 334 |
First, this option causes an immediate switch to the state |final| |
| 335 |
if the remaining distance on the input path is less than |
| 336 |
\meta{dimension}. The effect is the same as if you had said |
| 337 |
|switch if less than=|\meta{dimension}| to final| just before the |
| 338 |
|width| option. |
| 339 |
|
| 340 |
If no switch occurs, this option tells \pgfname\ the width of the |
| 341 |
segment. The current point will travel along the input path (as |
| 342 |
described earlier) by this distance. |
| 343 |
\end{key} |
| 344 |
% |
| 345 |
\begin{key}{/pgf/decoration automaton/repeat state=\meta{repetitions} (initially 0)} |
| 346 |
Tells \pgfname\ how long the automaton stays ``normally'' in the |
| 347 |
current state. This count is reset to \meta{repetitions} each time |
| 348 |
one of the |switch if| keys causes a state switch. If no state |
| 349 |
switches occur, the \meta{code} is executed and the repetition |
| 350 |
counter is decreased. Then, there is once more a chance of a state |
| 351 |
change caused by any of the \meta{options}. If no repetition |
| 352 |
occurs, the \meta{code} is executed once more and the counter is |
| 353 |
decreased once more. When the counter reaches zero, the \meta{code} |
| 354 |
is executed once more, but, then, a different state is entered, as |
| 355 |
specified by the |next state| option. |
| 356 |
|
| 357 |
Note, that the maximum number of times the state will be executed |
| 358 |
is $\meta{repetitions}+1$. |
| 359 |
\end{key} |
| 360 |
% |
| 361 |
\begin{key}{/pgf/decoration automaton/next state=\meta{new state}} |
| 362 |
After the \meta{code} for state has been executed for the last |
| 363 |
time, a state switch to \meta{new state} is performed. If this |
| 364 |
option is not given, the next state is the same as the current |
| 365 |
state. |
| 366 |
\end{key} |
| 367 |
|
| 368 |
\begin{key}{/pgf/decoration automaton/if input segment is closepath=\meta{options}} |
| 369 |
This key checks whether the current input segment is a closepath |
| 370 |
operation. If so, the \meta{options} get executed; otherwise |
| 371 |
nothing happens. You can use this option to handle a closepath in |
| 372 |
some special way, for instance, switching to a new state in which |
| 373 |
|\pgfpathclose| is executed. |
| 374 |
\end{key} |
| 375 |
|
| 376 |
\begin{key}{/pgf/decoration automaton/auto end on length=\meta{dimension}} |
| 377 |
This key is just included for convenience, it does nothing that |
| 378 |
cannot be achieved using the previous options. The effect is the |
| 379 |
following: If the remaining input path's length is at most |
| 380 |
\meta{dimension}, the decorated path is ended with a straight line |
| 381 |
to the end of the input path and, possibly, it is closed, namely if |
| 382 |
the input path ended with a closepath operation. Otherwise, it is |
| 383 |
checked whether the current input segment is a closepath segment |
| 384 |
and whether the remaining distance on the current input segment is |
| 385 |
at most \meta{distance}. If so, then a closepath operation is used |
| 386 |
to close the decorated path and the automaton continues with the |
| 387 |
next subpath, remaining in the current state. |
| 388 |
|
| 389 |
In all other cases, nothing happens. |
| 390 |
\end{key} |
| 391 |
|
| 392 |
\begin{key}{/pgf/decoration automaton/auto corner on length=\meta{dimension}} |
| 393 |
This key has the following effect: Firstly, in case the \TeX-if |
| 394 |
|\ifpgfdecoratepathhascorners| is false, nothing happens. |
| 395 |
Otherwise, it is tested whether the remaining distance on the |
| 396 |
current input segment is at most \meta{dimension}. If so, a |
| 397 |
|lineto| operation is used to reach the end of this input segment |
| 398 |
and the automaton continues with the next input segment, but |
| 399 |
remains in the current state. |
| 400 |
|
| 401 |
The main idea behind this option is to avoid having decoration |
| 402 |
segments ``overshoot'' past a corner. |
| 403 |
\end{key} |
| 404 |
|
| 405 |
You may sometimes wish to do computations outside the transformational |
| 406 |
\TeX-group of the current segment, so that these results of these |
| 407 |
computations are available in the next state. For this, the following |
| 408 |
two options are useful: |
| 409 |
|
| 410 |
\begin{key}{/pgf/decoration automaton/persistent precomputation=\meta{precode}} |
| 411 |
If the \meta{code} of the state is executed, the \meta{precode} is |
| 412 |
executed first and it is executed outside the \TeX-group of the |
| 413 |
\meta{code}. Note that when the \meta{precode} is executed, the |
| 414 |
transformation matrix is not set up. |
| 415 |
\end{key} |
| 416 |
|
| 417 |
\begin{key}{/pgf/decoration automaton/persistent postcomputation=\meta{postcode}} |
| 418 |
Works like the |persistent precomputation| option, only the |
| 419 |
\meta{postcode} is executed after (and also outside) the \TeX-group |
| 420 |
of the main \meta{code}. |
| 421 |
\end{key} |
| 422 |
|
| 423 |
There are a number of macros and dimensions which may be useful inside |
| 424 |
a decoration automaton. The following macros are available: |
| 425 |
|
| 426 |
\begin{command}{\pgfdecoratedpathlength} |
| 427 |
The length of the input path. If the input path consists of several |
| 428 |
input segments, this number is the sum of the lengths of the input |
| 429 |
segments. |
| 430 |
\end{command} |
| 431 |
|
| 432 |
\begin{command}{\pgfdecoratedinputsegmentlength} |
| 433 |
The length of the current input segment of the input path. |
| 434 |
``Current input segment'' refers to the input segment on which the |
| 435 |
current point lies. |
| 436 |
\end{command} |
| 437 |
|
| 438 |
\begin{command}{\pgfpointdecoratedpathlast} |
| 439 |
The final point of the input path. |
| 440 |
\end{command} |
| 441 |
|
| 442 |
\begin{command}{\pgfpointdecoratedinputsegmentlast} |
| 443 |
The final point of the current input segment of the input path. |
| 444 |
\end{command} |
| 445 |
|
| 446 |
\begin{command}{\pgfdecoratedangle} |
| 447 |
The angle of the tangent to the decorated path at the \emph{origin} |
| 448 |
of the current segment. The transformation matrix applied at the |
| 449 |
beginning of a state includes a rotation equivalent to this angle. |
| 450 |
\end{command} |
| 451 |
|
| 452 |
The following \TeX\ dimension registers are also available inside the |
| 453 |
automaton: |
| 454 |
|
| 455 |
\begin{command}{\pgfdecoratedremainingdistance} |
| 456 |
The remaining distance on the input path. |
| 457 |
\end{command} |
| 458 |
|
| 459 |
\begin{command}{\pgfdecoratedcompleteddistance} |
| 460 |
The completed distance on the input path. |
| 461 |
\end{command} |
| 462 |
|
| 463 |
\begin{command}{\pgfdecoratedinputsegmentremainingdistance} |
| 464 |
The remaining distance on the current input segment of the input path. |
| 465 |
\end{command} |
| 466 |
|
| 467 |
\begin{command}{\pgfdecoratedinputsegmentcompleteddistance} |
| 468 |
The completed distance on the current input segment of the input path. |
| 469 |
\end{command} |
| 470 |
|
| 471 |
Further keys and macros are defined and used by the decoration |
| 472 |
libraries, see Section~\ref{section-library-decorations}. |
| 473 |
|
| 474 |
The following example shows how these options can be used: |
| 475 |
% |
| 476 |
\begin{codeexample}[preamble={\usetikzlibrary{decorations}}] |
| 477 |
\pgfdeclaredecoration{complicated example decoration}{initial} |
| 478 |
{ |
| 479 |
\state{initial}[width=5pt,next state=up] |
| 480 |
{ \pgfpathlineto{\pgfpoint{5pt}{0pt}} } |
| 481 |
|
| 482 |
\state{up}[width=5pt,next state=down] |
| 483 |
{ |
| 484 |
\ifdim\pgfdecoratedremainingdistance>\pgfdecoratedcompleteddistance |
| 485 |
% Growing |
| 486 |
\pgfpathlineto{\pgfpoint{0pt}{\pgfdecoratedcompleteddistance}} |
| 487 |
\pgfpathlineto{\pgfpoint{5pt}{\pgfdecoratedcompleteddistance}} |
| 488 |
\pgfpathlineto{\pgfpoint{5pt}{0pt}} |
| 489 |
\else |
| 490 |
% Shrinking |
| 491 |
\pgfpathlineto{\pgfpoint{0pt}{\pgfdecoratedremainingdistance}} |
| 492 |
\pgfpathlineto{\pgfpoint{5pt}{\pgfdecoratedremainingdistance}} |
| 493 |
\pgfpathlineto{\pgfpoint{5pt}{0pt}} |
| 494 |
\fi% |
| 495 |
} |
| 496 |
\state{down}[width=5pt,next state=up] |
| 497 |
{ |
| 498 |
\ifdim\pgfdecoratedremainingdistance>\pgfdecoratedcompleteddistance |
| 499 |
% Growing |
| 500 |
\pgfpathlineto{\pgfpoint{0pt}{-\pgfdecoratedcompleteddistance}} |
| 501 |
\pgfpathlineto{\pgfpoint{5pt}{-\pgfdecoratedcompleteddistance}} |
| 502 |
\pgfpathlineto{\pgfpoint{5pt}{0pt}} |
| 503 |
\else |
| 504 |
% Shrinking |
| 505 |
\pgfpathlineto{\pgfpoint{0pt}{-\pgfdecoratedremainingdistance}} |
| 506 |
\pgfpathlineto{\pgfpoint{5pt}{-\pgfdecoratedremainingdistance}} |
| 507 |
\pgfpathlineto{\pgfpoint{5pt}{0pt}} |
| 508 |
\fi% |
| 509 |
} |
| 510 |
\state{final} |
| 511 |
{ |
| 512 |
\pgfpathlineto{\pgfpointdecoratedpathlast} |
| 513 |
} |
| 514 |
} |
| 515 |
\begin{tikzpicture}[decoration=complicated example decoration] |
| 516 |
\draw decorate{ (0,0) -- (3,0)}; |
| 517 |
\fill [red!50,rounded corners=2pt] |
| 518 |
decorate {(.5,-2) -- ++(2.5,-2.5)} -- (3,-5) -| (0,-2) -- cycle; |
| 519 |
\end{tikzpicture} |
| 520 |
\end{codeexample} |
| 521 |
\end{command} |
| 522 |
\end{command} |
| 523 |
|
| 524 |
|
| 525 |
\subsubsection{Predefined Decorations} |
| 526 |
|
| 527 |
The three decorations |moveto|, |lineto|, and |curveto| are predefined and |
| 528 |
``always available''. They are mostly useful in conjunction with |
| 529 |
meta-decorations. They are documented in |
| 530 |
Section~\ref{section-library-decorations} alongside the other decorations. |
| 531 |
|
| 532 |
|
| 533 |
\subsection{Using Decorations} |
| 534 |
|
| 535 |
Once a decoration has been declared, it can be used. |
| 536 |
|
| 537 |
\begin{environment}{{pgfdecoration}\marg{decoration list}} |
| 538 |
The \meta{environment contents} should contain commands for creating an |
| 539 |
path. This path is the basis for the \emph{input paths} for the decorations |
| 540 |
in the \meta{decoration list}. In detail, the following happens: |
| 541 |
% |
| 542 |
\begin{enumerate} |
| 543 |
\item The preexisting unused path is saved. |
| 544 |
\item The path commands specified in \meta{environment contents} are |
| 545 |
executed and this resulting path is saved. The path is then divided |
| 546 |
into different \emph{input paths} as follows: The format for each |
| 547 |
item in \marg{decoration list} is |
| 548 |
% |
| 549 |
\begin{quote} |
| 550 |
\marg{decoration}\marg{length}\opt{\marg{before code}\marg{after code}} |
| 551 |
\end{quote} |
| 552 |
% |
| 553 |
The \meta{before code} and the \meta{after code} are optional. The |
| 554 |
input path is divided into input paths as follows: The first input |
| 555 |
path consists of the first lines of the path specified in the |
| 556 |
\meta{environment contents} until the \meta{length} of the first |
| 557 |
element of the \meta{decoration list} is reached. If this length is |
| 558 |
reached in the middle of a line, the line is broken up at this |
| 559 |
exact position. Then the second input path has the \meta{length} of |
| 560 |
the second element in the \meta{decoration list} and consists of |
| 561 |
the lines making up the following \meta{length} part of the path in |
| 562 |
the \meta{environment contents}, and so on. |
| 563 |
|
| 564 |
If the lengths in the \meta{decoration list} do not add up to the |
| 565 |
total length of the path in the \meta{environment contents}, either |
| 566 |
some decorations are dropped (if their lengths add up to more than |
| 567 |
the length of the \meta{environment contents}) or the input path is |
| 568 |
not fully used (if their lengths add up to less). |
| 569 |
\item The preexisting path is reinstalled. |
| 570 |
\item The decoration automata move along the input paths, thus creating |
| 571 |
(and possibly using) the output paths. These output paths extend |
| 572 |
the current path (unless they are used). |
| 573 |
\end{enumerate} |
| 574 |
|
| 575 |
Some important points should be noted regarding the use of this |
| 576 |
environment: |
| 577 |
% |
| 578 |
\begin{itemize} |
| 579 |
\item If \meta{environment contents} does not begin with |
| 580 |
|\pgfpathmoveto|, the last known point on the preexisting path is |
| 581 |
assumed as the starting point. |
| 582 |
\item All except the last of any sequence of consecutive move-to |
| 583 |
commands in \meta{environment contents} are discarded. |
| 584 |
\item Any move-to commands at the end of \meta{environment contents} |
| 585 |
are ignored. |
| 586 |
\item Any close-path commands on the input path are interpreted as |
| 587 |
straight lines. Internally, something a little more complicated is |
| 588 |
going on, however, a closed path on the input path has no effect on |
| 589 |
the output path, other than causing the automaton to travel in a |
| 590 |
straight line towards the location of the last move-to command on |
| 591 |
the input path. |
| 592 |
\item Although tangent computations for the input path work with the |
| 593 |
last point on the preexisting path, no automatic move-to operations |
| 594 |
are issued for the output path. If an output path starts with a |
| 595 |
line-to or curve-to when the existing path is empty, an appropriate |
| 596 |
move-to command should be inserted before the decoration starts. |
| 597 |
\item If a decoration uses its own path, the first time this happens |
| 598 |
the preexisting path is part of the path that is used at this |
| 599 |
point. |
| 600 |
\end{itemize} |
| 601 |
|
| 602 |
Before the automata start to ``work on'' their respective inputs paths, |
| 603 |
\meta{before code} is executed. After the decoration automaton has |
| 604 |
finished, \meta{after code} is executed. |
| 605 |
% |
| 606 |
\begin{codeexample}[preamble={\usetikzlibrary{decorations,decorations.pathmorphing}}] |
| 607 |
\begin{tikzpicture}[decoration={segment length=5pt}] |
| 608 |
\draw [help lines] grid (3,2); |
| 609 |
\begin{pgfdecoration}{{curveto}{1cm},{zigzag}{2cm},{curveto}{1cm}} |
| 610 |
\pgfpathmoveto{\pgfpointorigin} |
| 611 |
\pgfpathcurveto |
| 612 |
{\pgfpoint{0cm}{2cm}}{\pgfpoint{3cm}{2cm}}{\pgfpoint{3cm}{0cm}} |
| 613 |
\end{pgfdecoration} |
| 614 |
\pgfusepath{stroke} |
| 615 |
\end{tikzpicture} |
| 616 |
\end{codeexample} |
| 617 |
|
| 618 |
When the lengths are evaluated, the dimension |
| 619 |
|\pgfdecoratedremainingdistance| holds the remaining distance on the entire |
| 620 |
decorated path, and |\pgfdecoratedpathlength| holds the total length of the |
| 621 |
path. Thus, it is possible to specify lengths like |
| 622 |
|\pgfdecoratedpathlength/3|. |
| 623 |
% |
| 624 |
\begin{codeexample}[preamble={\usetikzlibrary{decorations,decorations.pathmorphing}}] |
| 625 |
\begin{tikzpicture}[decoration={segment length=5pt}] |
| 626 |
\draw [help lines] grid (3,2); |
| 627 |
\begin{pgfdecoration}{ |
| 628 |
{curveto}{\pgfdecoratedpathlength/3}, |
| 629 |
{zigzag}{\pgfdecoratedpathlength/3}, |
| 630 |
{curveto}{\pgfdecoratedremainingdistance} |
| 631 |
} |
| 632 |
\pgfpathmoveto{\pgfpointorigin} |
| 633 |
\pgfpathcurveto |
| 634 |
{\pgfpoint{0cm}{2cm}}{\pgfpoint{3cm}{2cm}}{\pgfpoint{3cm}{0cm}} |
| 635 |
\end{pgfdecoration} |
| 636 |
\pgfusepath{stroke} |
| 637 |
\end{tikzpicture} |
| 638 |
\end{codeexample} |
| 639 |
|
| 640 |
When \meta{before code} is executed, the following macro is useful: |
| 641 |
% |
| 642 |
\begin{command}{\pgfpointdecoratedpathfirst} |
| 643 |
Returns the point corresponding to the start of the current input path. |
| 644 |
\end{command} |
| 645 |
% |
| 646 |
When \meta{after code} is executed, the following macro can be used: |
| 647 |
% |
| 648 |
\begin{command}{\pgfpointdecoratedpathlast} |
| 649 |
Returns the point corresponding to the end of the current input path. |
| 650 |
\end{command} |
| 651 |
% |
| 652 |
This means that if decorations do not use their own path, it is possible to |
| 653 |
do something with them and continue from the correct place. |
| 654 |
% |
| 655 |
\begin{codeexample}[preamble={\usetikzlibrary{decorations,decorations.pathmorphing}}] |
| 656 |
\begin{tikzpicture} |
| 657 |
\draw [help lines] grid (3,2); |
| 658 |
\begin{pgfdecoration}{ |
| 659 |
{curveto}{\pgfdecoratedpathlength/3} |
| 660 |
{} |
| 661 |
{ |
| 662 |
\pgfusepath{stroke} |
| 663 |
}, |
| 664 |
{zigzag}{\pgfdecoratedpathlength/3} |
| 665 |
{ |
| 666 |
\pgfpathmoveto{\pgfpointdecoratedpathfirst} |
| 667 |
\pgfdecorationsegmentlength=5pt |
| 668 |
} |
| 669 |
{ |
| 670 |
\pgfsetstrokecolor{red} |
| 671 |
\pgfusepath{stroke} |
| 672 |
\pgfpathmoveto{\pgfpointdecoratedpathlast} |
| 673 |
\pgfsetstrokecolor{black} |
| 674 |
}, |
| 675 |
{curveto}{\pgfdecoratedremainingdistance} |
| 676 |
} |
| 677 |
\pgfpathmoveto{\pgfpointorigin} |
| 678 |
\pgfpathcurveto |
| 679 |
{\pgfpoint{0cm}{2cm}}{\pgfpoint{3cm}{2cm}}{\pgfpoint{3cm}{0cm}} |
| 680 |
\end{pgfdecoration} |
| 681 |
\pgfusepath{stroke} |
| 682 |
\end{tikzpicture} |
| 683 |
\end{codeexample} |
| 684 |
|
| 685 |
After the |{decoration}| environment has finished, the following macros are |
| 686 |
available: |
| 687 |
|
| 688 |
\begin{command}{\pgfdecorateexistingpath} |
| 689 |
The preexisting path before the environment was entered. |
| 690 |
\end{command} |
| 691 |
|
| 692 |
\begin{command}{\pgfdecoratedpath} |
| 693 |
The (total) input path (that is, the path created by the environment |
| 694 |
contents). |
| 695 |
\end{command} |
| 696 |
|
| 697 |
\begin{command}{\pgfdecorationpath} |
| 698 |
The output path. If the path is used, this macro contains only the last |
| 699 |
unused part of the output path. |
| 700 |
\end{command} |
| 701 |
|
| 702 |
\begin{command}{\pgfpointdecoratedpathlast} |
| 703 |
The final point of the input path. |
| 704 |
\end{command} |
| 705 |
|
| 706 |
\begin{command}{\pgfpointdecorationpathlast} |
| 707 |
The final point of the output path. |
| 708 |
\end{command} |
| 709 |
|
| 710 |
The following style is executed each time a decoration is used. You may use |
| 711 |
it to set up default options for decorations. |
| 712 |
% |
| 713 |
\begin{stylekey}{/pgf/every decoration (initially \normalfont empty)} |
| 714 |
This style is executed for every decoration. |
| 715 |
\end{stylekey} |
| 716 |
\end{environment} |
| 717 |
|
| 718 |
\begin{plainenvironment}{{pgfdecoration}\marg{name}} |
| 719 |
The plain-\TeX{} version of the |{pgfdecorate}| environment. |
| 720 |
\todosp{`pgfdecorate' right or `pgfdecoration'? really no idea} |
| 721 |
\end{plainenvironment} |
| 722 |
|
| 723 |
\begin{contextenvironment}{{pgfdecoration}\marg{name}} |
| 724 |
The Con\TeX t version of the |{pgfdecoration}| environment. |
| 725 |
\end{contextenvironment} |
| 726 |
|
| 727 |
For convenience, the following macros provide a ``shorthand'' for decorations |
| 728 |
(internally, they all use the |{pgfdecoration}| environment). |
| 729 |
|
| 730 |
\begin{command}{\pgfdecoratepath\marg{name}\marg{path commands}} |
| 731 |
Decorate the path described by \meta{path commands} with the decoration |
| 732 |
\meta{name}. This is equivalent to |
| 733 |
% |
| 734 |
\begin{codeexample}[code only] |
| 735 |
\pgfdecoration{{name}{\pgfdecoratedpathlength} |
| 736 |
{\pgfdecoratebeforecode}{\pgfdecorateaftercode}} |
| 737 |
// the path commands. |
| 738 |
\endpgfdecoration |
| 739 |
\end{codeexample} |
| 740 |
% |
| 741 |
\end{command} |
| 742 |
|
| 743 |
\begin{command}{\pgfdecoratecurrentpath\marg{name}} |
| 744 |
Decorate the preexisting path with the decoration \meta{name}. |
| 745 |
\end{command} |
| 746 |
|
| 747 |
Both the above commands use the current definitions of the following macros: |
| 748 |
|
| 749 |
\begin{command}{\pgfdecoratebeforecode} |
| 750 |
Code executed as \meta{before code}, see the description of |
| 751 |
|\pgfdecoration|. |
| 752 |
\end{command} |
| 753 |
|
| 754 |
\begin{command}{\pgfdecorateaftercode} |
| 755 |
Code executed as \meta{after code}, see the description of |
| 756 |
|\pgfdecoration|. |
| 757 |
\end{command} |
| 758 |
|
| 759 |
It may sometimes be useful to add an additional transformation for each segment |
| 760 |
of a decoration. The following command allows you to define such a ``last |
| 761 |
minute transformation''. |
| 762 |
|
| 763 |
\begin{command}{\pgfsetdecorationsegmenttransformation\marg{code}} |
| 764 |
The \meta{code} will be executed at the very beginning of each segment. |
| 765 |
Note when applying multiple decorations, this will be reset between |
| 766 |
decorations, so it needs to be specified for each segment. |
| 767 |
% |
| 768 |
\begin{codeexample}[preamble={\usetikzlibrary{decorations,decorations.pathmorphing}}] |
| 769 |
\begin{tikzpicture} |
| 770 |
\draw [help lines] grid (3,2); |
| 771 |
\begin{pgfdecoration}{ |
| 772 |
{curveto}{\pgfdecoratedpathlength/3}, |
| 773 |
{zigzag}{\pgfdecoratedpathlength/3} |
| 774 |
{ |
| 775 |
\pgfdecorationsegmentlength=5pt |
| 776 |
\pgfsetdecorationsegmenttransformation{\pgftransformyshift{.5cm}} |
| 777 |
}, |
| 778 |
{curveto}{\pgfdecoratedremainingdistance} |
| 779 |
} |
| 780 |
\pgfpathmoveto{\pgfpointorigin} |
| 781 |
\pgfpathcurveto |
| 782 |
{\pgfpoint{0cm}{2cm}}{\pgfpoint{3cm}{2cm}}{\pgfpoint{3cm}{0cm}} |
| 783 |
\end{pgfdecoration} |
| 784 |
\pgfusepath{stroke} |
| 785 |
\end{tikzpicture} |
| 786 |
\end{codeexample} |
| 787 |
% |
| 788 |
\end{command} |
| 789 |
|
| 790 |
|
| 791 |
\subsection{Meta-Decorations} |
| 792 |
\label{section-base-meta-decorations} |
| 793 |
|
| 794 |
A meta-decoration provides an alternative way to decorate a path with multiple |
| 795 |
decorations. It is, in essence, an automaton that decorates an input path with |
| 796 |
decoration automatons. In general, however, the end effect is still that a path |
| 797 |
is decorated with other paths, and the input path should be thought of as being |
| 798 |
divided into sub-input-paths, each with their own decoration. Like ordinary |
| 799 |
decorations, a meta-decoration must be declared before it can be used. |
| 800 |
|
| 801 |
|
| 802 |
\subsubsection{Declaring Meta-Decorations} |
| 803 |
|
| 804 |
\begin{command}{\pgfdeclaremetadecorate\marg{name}\marg{initial state}\marg{states}} |
| 805 |
This command declares a new meta-decoration called \meta{name}. The |
| 806 |
\meta{states} argument contains a description of the meta-decoration |
| 807 |
automaton's states and the transitions between them. The \meta{initial |
| 808 |
state} is the state in which the automaton starts. |
| 809 |
|
| 810 |
The |\state| command is similar to the one found in decoration |
| 811 |
declarations, and takes the same form: |
| 812 |
|
| 813 |
\begin{command}{\state\marg{name}\oarg{options}\marg{code}} Declares the |
| 814 |
state \meta{name} inside the current meta-decoration automaton. Unlike |
| 815 |
decorations, states in meta-decorations are not executed within a |
| 816 |
group, which makes the persistent computation options superfluous. |
| 817 |
Consider using an initial state with |width=0pt| to do precalculations |
| 818 |
that could speed the execution of the meta-decoration. |
| 819 |
|
| 820 |
The \meta{options} are executed with the key path set to |
| 821 |
|/pgf/meta-decorations automaton/|, and the following keys are defined |
| 822 |
for this path: |
| 823 |
|
| 824 |
\begin{key}{/pgf/meta-decoration automaton/switch if less than=\meta{dimension}| to |\meta{new state}} |
| 825 |
This causes \pgfname\ to check whether the remaining distance to |
| 826 |
the end of the input path is less than \meta{dimension}, and, if |
| 827 |
so, to immediately switch to the state \meta{new state}. When this |
| 828 |
key is evaluated, the macro |\pgfmetadecoratedpathlength| will be |
| 829 |
defined as the total length of the decoration path, allowing for |
| 830 |
values such as |\pgfmetadecoratedpathlength/8|. |
| 831 |
\end{key} |
| 832 |
|
| 833 |
\begin{key}{/pgf/meta-decoration automaton/width=\meta{dimension}} |
| 834 |
As always, this option will cause an immediate switch to the state |
| 835 |
|final| if the remaining distance on the input path is less than |
| 836 |
\meta{dimension}. |
| 837 |
|
| 838 |
Otherwise, this option tells \pgfname\ the width of the |
| 839 |
``meta-segment'', that is, the length of the sub-input-path which |
| 840 |
the decoration automaton specified in \meta{code} will decorate. |
| 841 |
\end{key} |
| 842 |
|
| 843 |
\begin{key}{/pgf/meta-decoration automaton/next state=\meta{new state}} |
| 844 |
After the code for a state has been executed, a state switch to |
| 845 |
\meta{new state} is performed. If this option is not given, the |
| 846 |
next state is the same as the current state. |
| 847 |
\end{key} |
| 848 |
|
| 849 |
The code in \meta{code} is quite different from the code in a |
| 850 |
decoration state. In almost all cases only the following three macros |
| 851 |
will be required: |
| 852 |
|
| 853 |
\begin{command}{\decoration\marg{name}} |
| 854 |
This sets the decoration for the current state to \meta{name}. If |
| 855 |
this command is omitted, the |moveto| decoration will be used. |
| 856 |
\end{command} |
| 857 |
|
| 858 |
\begin{command}{\beforedecoration\marg{before code}} |
| 859 |
Defines \meta{before code} as (typically) \pgfname{} commands to be |
| 860 |
executed before the decoration is applied to the current segment. |
| 861 |
This command can be omitted. If you wish to set up some decoration |
| 862 |
specific parameters such as segment length, or segment amplitude, |
| 863 |
then they can be set in \meta{before code}. |
| 864 |
\end{command} |
| 865 |
|
| 866 |
\begin{command}{\afterdecoration\marg{after code}} |
| 867 |
Defines \meta{after code} as commands to be executed after the |
| 868 |
decoration has been applied to the current segment. This command |
| 869 |
can be omitted. |
| 870 |
\end{command} |
| 871 |
|
| 872 |
There are some macros that may be useful when creating meta-decorations |
| 873 |
(note that they are all macros): |
| 874 |
|
| 875 |
\begin{command}{\pgfpointmetadecoratedpathfirst} |
| 876 |
When the \meta{before code} is executed, this macro stores the |
| 877 |
first point on the current sub-input-path. |
| 878 |
\end{command} |
| 879 |
|
| 880 |
\begin{command}{\pgfpointmetadecoratedpathlast} |
| 881 |
When the \meta{after code} is executed, this macro stores the last |
| 882 |
point on the current sub-input-path. |
| 883 |
\end{command} |
| 884 |
|
| 885 |
\begin{command}{\pgfmetadecoratedpathlength} |
| 886 |
The entire length of the entire input path. |
| 887 |
\end{command} |
| 888 |
|
| 889 |
\begin{command}{\pgfmetadecoratedcompleteddistance} |
| 890 |
The completed distance on the entire input path. |
| 891 |
\end{command} |
| 892 |
|
| 893 |
\begin{command}{\pgfmetadecoratedremainingdistance} |
| 894 |
The remaining distance on the entire input path. |
| 895 |
\end{command} |
| 896 |
|
| 897 |
\begin{command}{\pgfmetadecoratedinputsegmentcompleteddistance} |
| 898 |
The completed distance on the current input segment of the entire |
| 899 |
input path. |
| 900 |
\end{command} |
| 901 |
|
| 902 |
\begin{command}{\pgfmetadecoratedinputsegmentremainingdistance} |
| 903 |
The remaining distance on the current input segment of the entire |
| 904 |
input path. |
| 905 |
\end{command} |
| 906 |
\end{command} |
| 907 |
|
| 908 |
Here is a complete example of a meta-decoration: |
| 909 |
% |
| 910 |
\begin{codeexample}[preamble={\usetikzlibrary{decorations,decorations.pathmorphing}}] |
| 911 |
\pgfdeclaremetadecoration{arrows}{initial}{ |
| 912 |
\state{initial}[width=0pt, next state=arrow] |
| 913 |
{ |
| 914 |
\pgfmathdivide{100}{\pgfmetadecoratedpathlength} |
| 915 |
\let\factor\pgfmathresult |
| 916 |
\pgfsetlinewidth{1pt} |
| 917 |
\pgfset{/pgf/decoration/segment length=4pt} |
| 918 |
} |
| 919 |
\state{arrow}[ |
| 920 |
switch if less than=\pgfmetadecorationsegmentlength to final, |
| 921 |
width=\pgfmetadecorationsegmentlength/3, |
| 922 |
next state=zigzag] |
| 923 |
{ |
| 924 |
\decoration{curveto} |
| 925 |
\beforedecoration |
| 926 |
{ |
| 927 |
\pgfmathparse{\pgfmetadecoratedcompleteddistance*\factor} |
| 928 |
\pgfsetcolor{red!\pgfmathresult!yellow} |
| 929 |
\pgfpathmoveto{\pgfpointmetadecoratedpathfirst} |
| 930 |
} |
| 931 |
} |
| 932 |
\state{zigzag}[width=\pgfmetadecorationsegmentlength/3, next state=end arrow] |
| 933 |
{ |
| 934 |
\decoration{zigzag} |
| 935 |
} |
| 936 |
\state{end arrow}[width=\pgfmetadecorationsegmentlength/3, next state=move] |
| 937 |
{ |
| 938 |
\decoration{curveto} |
| 939 |
\beforedecoration{\pgfpathmoveto{\pgfpointmetadecoratedpathfirst}} |
| 940 |
\afterdecoration |
| 941 |
{ |
| 942 |
\pgfsetarrowsend{to} |
| 943 |
\pgfusepath{stroke} |
| 944 |
} |
| 945 |
} |
| 946 |
\state{move}[width=\pgfmetadecorationsegmentlength/2, next state=arrow]{} |
| 947 |
\state{final}{} |
| 948 |
} |
| 949 |
|
| 950 |
\tikz\draw[decorate,decoration={arrows,meta-segment length=2cm}] |
| 951 |
(0,0) .. controls (0,2) and (3,2) .. (3,0) |
| 952 |
.. controls (3,-2) and (0,-2) .. (0,-4) |
| 953 |
.. controls (0,-6) and (3,-6) .. (3,-8) |
| 954 |
.. controls (3,-10) and (0,-10) .. (0,-8); |
| 955 |
\end{codeexample} |
| 956 |
% |
| 957 |
\end{command} |
| 958 |
|
| 959 |
|
| 960 |
\subsubsection{Predefined Meta-decorations} |
| 961 |
|
| 962 |
There are no predefined meta-decorations loaded with \pgfname{}. |
| 963 |
|
| 964 |
|
| 965 |
\subsubsection{Using Meta-Decorations} |
| 966 |
|
| 967 |
Using meta-decorations is ``simpler'' than using decorations, because you can |
| 968 |
only use one meta-decoration per path. |
| 969 |
|
| 970 |
\begin{environment}{{pgfmetadecoration}\marg{name}} |
| 971 |
This environment decorates the input path described in \meta{environment |
| 972 |
contents}, with the meta-decoration \meta{name}. |
| 973 |
\end{environment} |
| 974 |
|
| 975 |
\begin{plainenvironment}{{pgfmetadecoration}\marg{name}} |
| 976 |
The plain \TeX{} version of the |{pgfmetadecoration}| environment. |
| 977 |
\end{plainenvironment} |
| 978 |
|
| 979 |
\begin{contextenvironment}{{pgfmetadecoration}\marg{name}} |
| 980 |
The Con\TeX t version of the |{pgfmetadecoration}| environment. |
| 981 |
\end{contextenvironment} |