summaryrefslogtreecommitdiff
path: root/graphics/pgf/base/doc/pgfmanual-en-library-decorations.tex
diff options
context:
space:
mode:
Diffstat (limited to 'graphics/pgf/base/doc/pgfmanual-en-library-decorations.tex')
-rw-r--r--graphics/pgf/base/doc/pgfmanual-en-library-decorations.tex2181
1 files changed, 2181 insertions, 0 deletions
diff --git a/graphics/pgf/base/doc/pgfmanual-en-library-decorations.tex b/graphics/pgf/base/doc/pgfmanual-en-library-decorations.tex
new file mode 100644
index 0000000000..ca6e67a371
--- /dev/null
+++ b/graphics/pgf/base/doc/pgfmanual-en-library-decorations.tex
@@ -0,0 +1,2181 @@
+% Copyright 2019 by Mark Wibrow and Till Tantau
+%
+% This file may be distributed and/or modified
+%
+% 1. under the LaTeX Project Public License and/or
+% 2. under the GNU Free Documentation License.
+%
+% See the file doc/generic/pgf/licenses/LICENSE for more details.
+
+
+\section{Decoration Library}
+\label{section-library-decorations}
+
+
+\subsection{Overview and Common Options}
+
+The decoration libraries define a number of (more or less useful) decorations
+that can be applied to paths. The usage of decorations is not covered in the
+present section, please consult Sections~\ref{section-tikz-decorations}, which
+explains how decorations are used in \tikzname, and
+\ref{section-base-decorations}, which explains how new decorations can be
+defined.
+
+The decorations are influenced by a number of parameters that can be set using
+the |decoration| option. These parameters are typically shared between
+different decorations. In the following, the general options are documented
+(they are defined directly in the |decoration| module), special-purpose keys
+are documented with the decoration that uses it.
+
+Since you are encouraged to use these keys to make your own decorations
+configurable, it is indicated for each key where the value is stored (so that
+you can access it). Note that some values are stored in \TeX\ dimension
+registers while others are stored in macros.
+
+\begin{key}{/pgf/decoration/amplitude=\meta{dimension} (initially 2.5pt)}
+ This key determines the ``desired height'' (or amplitude) of decorations
+ for which this makes sense. For instance, the initial value of |2.5pt|
+ means that deforming decorations should deform a path by up to 2.5pt away
+ from the original path.
+
+ This key sets the \TeX-dimension |\pgfdecorationsegmentamplitude|.
+\end{key}
+
+\begin{key}{/pgf/decoration/meta-amplitude=\meta{dimension} (initially 2.5pt)}
+ This key determines the amplitude for a meta-decoration.
+
+ The key sets the \TeX-macro (!) |\pgfmetadecorationsegmentamplitude|.
+\end{key}
+
+\begin{key}{/pgf/decoration/segment length=\meta{dimension} (initially 10pt)}
+ Many decorations are made up of small segments. This key determines the
+ desired length of such segments.
+
+ This key sets the \TeX-dimension |\pgfdecorationsegmentlength|.
+\end{key}
+
+\begin{key}{/pgf/decoration/meta-segment length=\meta{dimension} (initially 1cm)}
+ This determined the length of the meta-segments from which a
+ meta-decoration is made up.
+
+ This key sets the \TeX-macro (!) |\pgfmetadecorationsegmentlength|.
+\end{key}
+
+\begin{key}{/pgf/decoration/angle=\meta{degree} (initially 45)}
+ The way some decorations look like depends on a configurable angle. For
+ instance, a |wave| decoration consists of arcs and the opening angle of
+ these arcs is given by the |angle|.
+
+ This key sets the \TeX-macro |\pgfdecorationsegmentangle|.
+\end{key}
+
+\begin{key}{/pgf/decoration/aspect=\meta{factor} (initially 0.5)}
+ For some decorations there is a natural aspect ratio. For instance,
+ for a |brace| decoration the aspect ratio determines where the brace
+ point will be.
+
+ This key sets the \TeX-macro |\pgfdecorationsegmentaspect|.
+\end{key}
+
+\begin{key}{/pgf/decoration/start radius=\meta{dimension} (initially 2.5pt)}
+ For some decorations there is a natural start radius (of some circle,
+ presumably).
+
+ This key stores the value directly inside the key.
+\end{key}
+
+\begin{key}{/pgf/decoration/end radius=\meta{dimension} (initially 2.5pt)}
+ For some decorations there is a natural end radius (of some circle,
+ presumably).
+
+ This key stores the value directly inside the key.
+\end{key}
+
+\begin{stylekey}{/pgf/decoration/radius=\meta{dimension}}
+ Sets the start and end radius simultaneously.
+\end{stylekey}
+
+\begin{key}{/pgf/decoration/path has corners=\meta{boolean} (initially false)}
+ This is a hint to the decoration code as to whether the path has corners or
+ not. If a path has a sharp corner, setting this option to |true| may result
+ in better rendering of the decoration because the joins of input segments
+ are approached ``more carefully'' than when this key is set to false.
+ However, if the path is, say, a smooth circle, setting this key to |true|
+ will usually look worse. Most decorations ignore this key, anyway.
+ Internally, it sets the \TeX-if |\ifpgfdecoratepathhascorners|.
+\end{key}
+
+
+\subsection{Handling ``Dimension too large'' errors}
+
+In case you should run into a ``Dimension too large error'' when using the
+|decorations| libraries, there is a pretty high chance that you can resolve
+this by using the |fpu| library in combination with
+|/pgf/fpu/install only={reciprocal}|. Please note that this key should only be
+applied locally to avoid other errors (see also at the definition of this key
+on page~\pageref{fpu-install-only}).
+%
+\begin{codeexample}[preamble={\usetikzlibrary{decorations.markings,fpu}}]
+\begin{tikzpicture}
+ \begin{scope}[/pgf/fpu/install only={reciprocal}]
+ \draw[postaction=decorate,decoration={
+ markings,mark=at position 0.52 with {
+ \draw circle[radius=2pt];
+ }},
+ ] plot[smooth,variable=\x,domain=-1:1] (\x*\x*\x,\x*\x);
+ \end{scope}
+\end{tikzpicture}
+\end{codeexample}
+
+
+\subsection{Path Morphing Decorations}
+
+\begin{pgflibrary}{decorations.pathmorphing}
+ A \emph{path morphing decoration} ``morphs'' or ``deforms'' the
+ to-be-decorated path. This means that what used to be a straight line might
+ afterwards be a snaking curve and have bumps. However, a line is still a
+ line and path deforming decorations do not change the number of subpaths.
+ For instance, if the path used to consist of two circles and an open arc,
+ the path will, after the decoration process, still consist of two closed
+ subpaths and one open subpath.
+\end{pgflibrary}
+
+
+\subsubsection{Decorations Producing Straight Line Paths}
+
+The following deformations use only straight lines in order to morph the paths.
+
+\begin{decoration}{lineto}
+ This decoration replaces the path by straight lines. For each curve, the
+ path simply goes directly from the start point to the end point. In the
+ following example, the arc actually consist of two subcurves.
+
+ This decoration is actually always defined when the decoration module is
+ loaded, but it is documented here for consistency.
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{decorations}}]
+\begin{tikzpicture}[decoration=lineto]
+ \draw [help lines] grid (3,2);
+ \draw [decorate,fill=yellow!80!black]
+ (0,0) -- (3,1) arc (0:180:1.5 and 1) -- cycle;
+\end{tikzpicture}
+\end{codeexample}
+ %
+\end{decoration}
+
+\begin{decoration}{straight zigzag}
+ This (meta-)decoration decorates the path by alternating between |curveto|
+ and |zigzag| decorations. It always finishes with the |curveto| decoration.
+ The following parameters influence the decoration:
+ %
+ \begin{itemize}
+ \item |amplitude| determines how much the zigzag line raises above and
+ falls below a straight line to the target point.
+ \item |segment length| determines the length of a complete ``up-down''
+ cycle.
+ \item |meta-segment length| determines the length of the |curveto| and the
+ |zigzag| decorations.
+ \end{itemize}
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{decorations.pathmorphing}}]
+\begin{tikzpicture}[decoration={straight zigzag,meta-segment length=1.1cm}]
+ \draw [help lines] grid (3,2);
+ \draw [decorate,fill=yellow!80!black]
+ (0,0) -- (3,1) arc (0:180:1.5 and 1) -- cycle;
+\end{tikzpicture}
+\end{codeexample}
+ %
+\end{decoration}
+
+\begin{decoration}{random steps}
+ This decoration consists of straight line segments. The line segments head
+ towards the target, but each step is randomly shifted a little bit. The
+ following parameters influence the decorations:
+ %
+ \begin{itemize}
+ \item |segment length| determines the basic length of each step.
+ \item |amplitude| The end of each step is perturbed both in $x$- and in
+ $y$-direction by two values drawn uniformly from the interval
+ $[-d,d]$, where $d$ is the value of |amplitude|.
+ \end{itemize}
+ %
+\begin{codeexample}[pre={\pgfmathsetseed{1}},preamble={\usetikzlibrary{decorations.pathmorphing}}]
+\begin{tikzpicture}
+ [decoration={random steps,segment length=2mm}]
+ \draw [help lines] grid (3,2);
+ \draw [decorate,fill=yellow!80!black]
+ (0,0) -- (3,1) arc (0:180:1.5 and 1) -- cycle;
+\end{tikzpicture}
+\end{codeexample}
+ %
+\end{decoration}
+
+\begin{decoration}{saw}
+ This decoration looks like the blade of a saw. The following parameters
+ influence the decoration:
+ %
+ \begin{itemize}
+ \item |amplitude| determines how much each spike raises above the
+ straight line.
+ \item |segment length| determines the length each spike.
+ \end{itemize}
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{decorations.pathmorphing}}]
+\begin{tikzpicture}[decoration=saw]
+ \draw [help lines] grid (3,2);
+ \draw [decorate,fill=yellow!80!black]
+ (0,0) -- (3,1) arc (0:180:1.5 and 1) -- cycle;
+\end{tikzpicture}
+\end{codeexample}
+ %
+\end{decoration}
+
+\begin{decoration}{zigzag}
+ This decoration looks like a zigzag line. The following parameters
+ influence the decoration:
+ %
+ \begin{itemize}
+ \item |amplitude| determines how much the zigzag line raises above and
+ falls below a straight line to the target point.
+ \item |segment length| determines the length of a complete ``up-down''
+ cycle.
+ \end{itemize}
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{decorations.pathmorphing}}]
+\begin{tikzpicture}[decoration=zigzag]
+ \draw [help lines] grid (3,2);
+ \draw [decorate,fill=yellow!80!black]
+ (0,0) -- (3,1) arc (0:180:1.5 and 1) -- cycle;
+\end{tikzpicture}
+\end{codeexample}
+ %
+\end{decoration}
+
+
+\subsubsection{Decorations Producing Curved Line Paths}
+
+\begin{decoration}{bent}
+ This decoration adds a slightly bent line from the start to the target. The
+ amplitude of the bend is given |amplitude| (an amplitude of zero gives a
+ straight line).
+ %
+ \begin{itemize}
+ \item |amplitude| determines the amplitude of the bend.
+ \item |aspect| determines how tight the bend is. A good value is around
+ |0.3|.
+ \end{itemize}
+ %
+ Note that this decoration makes only little sense for curves. You should
+ apply it only to straight lines.
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{decorations.pathmorphing}}]
+\begin{tikzpicture}[decoration=bent]
+ \draw [help lines] grid (3,2);
+ \draw [decorate] (0,0) -- (3,1) -- (1.5,2) -- (0,1);
+\end{tikzpicture}
+\end{codeexample}
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{decorations.pathmorphing}}]
+\begin{tikzpicture}[decoration={bent,aspect=.3}]
+ \draw [decorate,fill=yellow!80!black] (0,0) rectangle (3.5,2);
+ \node[circle,draw] (A) at (.5,.5) {A};
+ \node[circle,draw] (B) at (3,1.5) {B};
+ \draw[->,decorate] (A) -- (B);
+ \draw[->,decorate] (B) -- (A);
+\end{tikzpicture}
+\end{codeexample}
+ %
+\end{decoration}
+
+\begin{decoration}{bumps}
+ This decoration replaces the path by little half ellipses. The following
+ parameters influence it.
+ %
+ \begin{itemize}
+ \item |amplitude| determines the height of the half ellipse.
+ \item |segment length| determines the width of the half ellipse.
+ \end{itemize}
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{decorations.pathmorphing}}]
+\begin{tikzpicture}[decoration=bumps]
+ \draw [help lines] grid (3,2);
+ \draw [decorate,fill=yellow!80!black]
+ (0,0) -- (3,1) arc (0:180:1.5 and 1) -- cycle;
+\end{tikzpicture}
+\end{codeexample}
+ %
+\end{decoration}
+
+\begin{decoration}{coil}
+ This decoration replaces the path by a coiled line. To understand how this
+ works, imagine a three-dimensional spring. The spring's axis points along
+ the path toward the target. Then, we ``view'' the spring from a certain
+ angle. If we look ``straight from the side'' we will see a perfect sine
+ curve, if we look ``more from the front'' we will see a coil. The following
+ parameters influence the decoration:
+ %
+ \begin{itemize}
+ \item |amplitude| determines how much the coil rises above the path and
+ falls below it. Thus, this is the radius of the coil.
+ \item |segment length| determines the distance between two consecutive
+ ``curls''. Thus, when the spring is see ``from the side'' this will
+ be the wave length of the sine curve.
+ \item |aspect| determines the ``viewing direction''. A value of |0|
+ means ``looking from the side'' and a value of |0.5|, which is the
+ default, means ``look more from the front''.
+ \end{itemize}
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{decorations.pathmorphing}}]
+\begin{tikzpicture}[decoration=coil]
+ \draw [help lines] grid (3,2);
+ \draw [decorate,fill=yellow!80!black]
+ (0,0) -- (3,1) arc (0:180:1.5 and 1) -- cycle;
+\end{tikzpicture}
+\end{codeexample}
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{decorations.pathmorphing}}]
+\begin{tikzpicture}
+ [decoration={coil,aspect=0.3,segment length=3mm,amplitude=3mm}]
+ \draw [help lines] grid (3,2);
+ \draw [decorate,fill=yellow!80!black]
+ (0,0) -- (3,1) arc (0:180:1.5 and 1) -- cycle;
+\end{tikzpicture}
+\end{codeexample}
+ %
+\end{decoration}
+
+\begin{decoration}{curveto}
+ This decoration simply yields a line following the original path. This
+ means that (ideally) it does not change the path and follows any curves in
+ the path (hence the name). In reality, due to the internals of how
+ decorations are implemented, this decoration actually replaces the path by
+ numerous small straight lines.
+
+ This decoration is mostly useful in conjunction with meta-decorations. It
+ is also actually defined in the decoration module and is always available.
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{decorations.pathmorphing}}]
+\begin{tikzpicture}[decoration=curveto]
+ \draw [help lines] grid (3,2);
+ \draw [decorate,fill=yellow!80!black]
+ (0,0) -- (3,1) arc (0:180:1.5 and 1) -- cycle;
+\end{tikzpicture}
+\end{codeexample}
+ %
+\end{decoration}
+
+\begin{decoration}{snake}
+ This decoration replaces the path by a line that looks like a snake seen
+ from above. More precisely, the snake is a sine wave with a ``softened''
+ start and ending. The following parameters influence the snake:
+ %
+ \begin{itemize}
+ \item |amplitude| determines the sine wave's amplitude.
+ \item |segment length| determines the sine wave's wavelength.
+ \end{itemize}
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{decorations.pathmorphing}}]
+\begin{tikzpicture}[decoration=snake]
+ \draw [help lines] grid (3,2);
+ \draw [decorate,fill=yellow!80!black]
+ (0,0) -- (3,1) arc (0:180:1.5 and 1) -- cycle;
+\end{tikzpicture}
+\end{codeexample}
+ %
+\end{decoration}
+
+
+\subsection{Path Replacing Decorations}
+
+\begin{pgflibrary}{decorations.pathreplacing}
+ This library defines decorations that replace the to-be-decorated path by
+ another path. Unlike morphing decorations, the replaced path might be quite
+ different, for instance a straight line might be replaced by a set of
+ circles. Note that filling a path that has been replaced using one of the
+ decorations in this library typically does not fill the original area but,
+ rather, the smaller area of the newly-created path segments.
+\end{pgflibrary}
+
+\begin{decoration}{border}
+ This decoration adds straight lines to the path that are at a specific
+ angle to the line toward the target. The idea is to add these little lines
+ to indicate the ``border'' of an area. The following parameters influence
+ the decoration:
+ %
+ \begin{itemize}
+ \item |segment length| determines the distance between consecutive
+ ticks.
+ \item |amplitude| determines the length of the ticks.
+ \item |angle| determines the angle between the ticks and the line of
+ the path.
+ \end{itemize}
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{decorations.pathreplacing}}]
+\begin{tikzpicture}[decoration=border]
+ \draw [help lines] grid (3,2);
+ \draw [postaction={decorate,draw,red}]
+ (0,0) -- (3,1) arc (0:180:1.5 and 1);
+\end{tikzpicture}
+\end{codeexample}
+ %
+\end{decoration}
+
+\begin{decoration}{brace}
+ This decoration replaces a straight line path by a long brace. The left and
+ right end of the brace will be exactly on the start and endpoint of the
+ decoration. The decoration really only makes sense for paths that are a
+ straight line.
+ %
+ \begin{itemize}
+ \item |amplitude| determines how much the brace rises above the path.
+ \item |aspect| determines the fraction of the total length where the
+ ``middle part'' of the brace will be.
+ \end{itemize}
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{decorations.pathreplacing}}]
+\begin{tikzpicture}[decoration=brace]
+ \draw [help lines] grid (3,2);
+ \draw [decorate] (0,0) -- (3,1);
+\end{tikzpicture}
+\end{codeexample}
+ %
+\end{decoration}
+
+\begin{decoration}{expanding waves}
+ This decoration adds arcs to the path that get bigger along the line
+ towards the target. The following parameters influence the decoration:
+ %
+ \begin{itemize}
+ \item |segment length| determines the distance between consecutive
+ arcs.
+ \item |angle| determines the opening angle below and above the path.
+ Thus, the total opening angle is twice this angle.
+ \end{itemize}
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{decorations.pathreplacing}}]
+\begin{tikzpicture}[decoration={expanding waves,angle=5}]
+ \draw [help lines] grid (3,2);
+ \draw [decorate] (0,0) -- (3,1) arc (0:180:1.5 and 1);
+\end{tikzpicture}
+\end{codeexample}
+ %
+\end{decoration}
+
+\begin{decoration}{moveto}
+ This decoration simply jumps to the end of the path using a move-to path
+ operation. It is mainly useful as |pre=moveto| or |post=moveto|
+ decorations.
+
+ This decoration is actually always defined when the decoration module is
+ loaded, but it is documented here for consistency.
+\end{decoration}
+
+\begin{decoration}{ticks}
+ This decoration replaces the path by straight lines that are orthogonal to
+ the path. The following parameters influence the decoration:
+ %
+ \begin{itemize}
+ \item |segment length| determines the distance between consecutive
+ ticks.
+ \item |amplitude| determines half the length of the ticks.
+ \end{itemize}
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{decorations.pathreplacing}}]
+\begin{tikzpicture}[decoration=ticks]
+ \draw [help lines] grid (3,2);
+ \draw [decorate] (0,0) -- (3,1) arc (0:180:1.5 and 1);
+\end{tikzpicture}
+\end{codeexample}
+ %
+\end{decoration}
+
+\begin{decoration}{waves}
+ This decoration replaces the path by arcs that have a constant size. The
+ following parameters influence the decoration:
+ %
+ \begin{itemize}
+ \item |segment length| determines the distance between consecutive
+ arcs.
+ \item |angle| determines the opening angle below and above the path.
+ Thus, the total opening angle is twice this angle.
+ \item |radius| determines the radius of each arc.
+ \end{itemize}
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{decorations.pathreplacing}}]
+\begin{tikzpicture}[decoration={waves,radius=4mm}]
+ \draw [help lines] grid (3,2);
+ \draw [decorate] (0,0) -- (3,1) arc (0:180:1.5 and 1);
+\end{tikzpicture}
+\end{codeexample}
+ %
+\end{decoration}
+
+\begin{decoration}{show path construction}
+ This decoration allows ``something different'' to be done for each
+ \emph{type} of input segment (i.e., moveto, lineto, curveto or closepath).
+ Typically, each segment will be replaced with another path, but this need
+ not necessarily be the case.
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{decorations.pathreplacing}}]
+\begin{tikzpicture}[>=stealth, every node/.style={midway, sloped, font=\tiny},
+ decoration={show path construction,
+ moveto code={
+ \fill [red] (\tikzinputsegmentfirst) circle (2pt)
+ node [fill=none, below] {moveto};},
+ lineto code={
+ \draw [blue,->] (\tikzinputsegmentfirst) -- (\tikzinputsegmentlast)
+ node [above] {lineto};
+ },
+ curveto code={
+ \draw [green!75!black,->] (\tikzinputsegmentfirst) .. controls
+ (\tikzinputsegmentsupporta) and (\tikzinputsegmentsupportb)
+ ..(\tikzinputsegmentlast) node [above] {curveto};
+ },
+ closepath code={
+ \draw [orange,->] (\tikzinputsegmentfirst) -- (\tikzinputsegmentlast)
+ node [above] {closepath};}
+ }]
+ \draw [help lines] grid (3,2);
+ \path [decorate] (0,0) -- (3,1) arc (0:180:1.5 and 1) -- cycle;
+\end{tikzpicture}
+\end{codeexample}
+
+ The following keys can be used to specify the code to execute for each type
+ of input segment.
+
+ \begin{key}{/pgf/decoration/moveto code=\meta{code} (initially \char`\{\char`\})}
+ Set the code to be executed for every moveto input segment. It is
+ important to remember that the transformations applied by the
+ decoration automaton are turned \emph{off} when \meta{code} is
+ executed.
+ \end{key}
+
+ \begin{key}{/pgf/decoration/lineto code=\meta{code} (initially \char`\{\char`\})}
+ Set the code to be executed for every lineto input segment.
+ \end{key}
+
+ \begin{key}{/pgf/decoration/curveto code=\meta{code} (initially \char`\{\char`\})}
+ Set the code to be executed for every curveto input segment.
+ \end{key}
+
+ \begin{key}{/pgf/decoration/closepath code=\meta{code} (initially \char`\{\char`\})}
+ Set the code to be executed for every closepath input segment.
+ \end{key}
+
+ Within \meta{code} the first and last points on the current input segment
+ can be accessed using |\pgfpointdecoratedinputsegmentfirst| and
+ |\pgfpointdecoratedinputsegmentlast|. For curves, the control (support)
+ points can be accessed using |\pgfpointdecoratedinputsegmentsupporta| and
+ |\pgfpointdecoratedinputsegmentsupportb|.
+
+ In \tikzname, you can use the following macros inside a \tikzname{}
+ coordinate.
+
+ \begin{command}{\tikzinputsegmentfirst}
+ The first point on the current input segment path.
+ \end{command}
+
+ \begin{command}{\tikzinputsegmentlast}
+ The last point on the current input segment path.
+ \end{command}
+
+ \begin{command}{\tikzinputsegmentsupporta}
+ The first support on the curveto input segment path.
+ \end{command}
+
+ \begin{command}{\tikzinputsegmentsupportb}
+ The second support on the curveto input segment path.
+ \end{command}
+ %
+{\ifpgfmanualexternalize\tikzexternaldisable\fi
+\begin{codeexample}[preamble={\usetikzlibrary{decorations.pathreplacing,shapes.misc}}]
+\tikzset{
+ show curve controls/.style={
+ decoration={
+ show path construction,
+ curveto code={
+ \draw [blue, dashed]
+ (\tikzinputsegmentfirst) -- (\tikzinputsegmentsupporta)
+ node [at end, cross out, draw, solid, red, inner sep=2pt]{};
+ \draw [blue, dashed]
+ (\tikzinputsegmentsupportb) -- (\tikzinputsegmentlast)
+ node [at start, cross out, draw, solid, red, inner sep=2pt]{};
+ }
+ },decorate
+ }
+}
+
+\tikzpicture
+ \draw [postaction=show curve controls, thick]
+ (0,2) .. controls (2.5,1.5) and (0.5,0.5) .. (3,0);
+\endtikzpicture
+\end{codeexample}
+}%
+ %
+\end{decoration}
+
+
+\subsection{Marking Decorations}
+
+\subsubsection{Overview}
+
+A \emph{marking on a path} is any kind of graphic that is placed on a specific
+position on a path. Markings are useful in rather diverse situations: you can
+use them to, say, place little ``footsteps'' along a path as if someone where
+walking along the path; to place arrow tips on the middle of a path to indicate
+the ``direction'' in which something is flowing; or you can use them to place
+informative information at certain positions of a path.
+
+For historical reasons there are three different libraries for placing marks on
+a path. They differ in what kind of markings can be added to a path. We start
+with the most general and most useful of these libraries.
+
+
+\subsection{Arbitrary Markings}
+
+\begin{pgflibrary}{decorations.markings}
+ Markings are arbitrary ``marks'' that can be put on a path. Marks can be
+ arrow tips or nodes or even whole pictures.
+\end{pgflibrary}
+
+\begin{decoration}{markings}
+ A \emph{marking} can be thought of a ``little picture'' or more precisely
+ of ``some scope contents'' that is placed ``on'' a path at a certain
+ position. Suppose the marking should be a simple cross. We can produce this
+ with the following code:
+ %
+\begin{codeexample}[code only]
+\draw (-2pt,-2pt) -- (2pt,2pt);
+\draw (2pt,-2pt) -- (-2pt,2pt);
+\end{codeexample}
+ %
+ If we use this code as a marking at position |2cm| on a path, then the
+ following happens: \pgfname\ determines the position on the path that is
+ 2cm along the path. Then is translates the coordinate system to this
+ position and rotates it such that the positive $x$-axis is tangent to the
+ path. Then a protective scope is created, inside which the above code is
+ executed -- resulting in a little cross on the path.
+
+ The |markings| decoration allows you to place one or more such markings on
+ a path. The decoration destroys the input path (except in certain cases,
+ detailed later), which means that it uses the path for determining
+ positions on the path, but after the decoration is done this path is gone.
+ You typically need to use a |postaction| to add markings.
+
+ Let us start with the above example in real code:
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{decorations.markings}}]
+\begin{tikzpicture}[decoration={
+ markings,% switch on markings
+ mark=% actually add a mark
+ at position 2cm
+ with
+ {
+ \draw (-2pt,-2pt) -- (2pt,2pt);
+ \draw (2pt,-2pt) -- (-2pt,2pt);
+ }
+ }
+ ]
+ \draw [help lines] grid (3,2);
+ \draw [postaction={decorate}] (0,0) -- (3,1) arc (0:180:1.5 and 1);
+\end{tikzpicture}
+\end{codeexample}
+
+ We can also add the cross repeatedly:
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{decorations.markings}}]
+\begin{tikzpicture}[decoration={
+ markings,% switch on markings
+ mark=% actually add a mark
+ between positions 0 and 1 step 5mm
+ with
+ {
+ \draw (-2pt,-2pt) -- (2pt,2pt);
+ \draw (2pt,-2pt) -- (-2pt,2pt);
+ }
+ }
+ ]
+ \draw [help lines] grid (3,2);
+ \draw [postaction={decorate}] (0,0) -- (3,1) arc (0:180:1.5 and 1);
+\end{tikzpicture}
+\end{codeexample}
+
+ The |mark| decoration option is used to specify a marking. It comes in two
+ versions:
+ %
+ \begin{key}{/pgf/decoration/mark=\texttt{at position }\meta{pos}\texttt{ with }\meta{code}}
+ The options specifies that when a |marking| decoration is applied,
+ there should be a marking at position \meta{pos} on the path whose code
+ is given by \meta{code}.
+
+ The \meta{pos} can have four different forms:
+ %
+ \begin{enumerate}
+ \item It can be a non-negative dimension like |0pt| or |2cm| or
+ |5cm/2|. In this case, it refers to the position along the path
+ that is this far displaced from the start.
+ \item It can be a negative dimension like |-1cm-2pt| or |-1sp|. In
+ this case, the position is taken from the end of the path.
+ Thus, |-1cm| is the position that is $-1$cm displaced from the
+ end of the path.
+ \item It can be a dimensionless non-negative number like |1/2| or
+ |0.333+2*0.1|. In this case, the \meta{pos} is interpreted as a
+ factor of the total path length. Thus, a \meta{pos} or |0.5|
+ refers to the middle of the path, |0.1| is near the start, and
+ so on.
+ \item It can be a dimensionless negative number like |-0.1|. Then,
+ again, the fraction of the path length counts ``from the end''.
+ \end{enumerate}
+
+ The \meta{pos} determines a position on the path. When the marking is
+ applied, the (high level) coordinate system will have been transformed
+ so that the origin lies at this position and the positive $x$-axis
+ points along the path. For this coordinate system, the \meta{code} is
+ executed. It can contain all sorts of graphic drawing commands,
+ including (even named) nodes.
+
+ If the position lies past the end of the path (for instance if
+ \meta{pos} is set to |1.2|), the marking will not be drawn.
+
+ It is possible to give the |mark| option several times, which causes
+ several markings to be applied. In this case, however, it is necessary
+ that the positions on the path are in increasing order. That is, it is
+ not allowed (and will result in chaos) to have a marking that lies
+ earlier on the path to follow a marking that is later on the path.
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{decorations.markings}}]
+\begin{tikzpicture}[decoration={
+ markings,% switch on markings
+ mark=at position 1cm with \node[red]{1cm};,
+ mark=at position .5 with \node[green]{mid};,
+ mark=at position -1cm with {\node[blue,transform shape]{1cm from end};}}
+ ]
+ \draw [help lines] grid (3,2);
+ \draw [postaction={decorate}] (0,0) -- (3,1) arc (0:180:1.5 and 1);
+\end{tikzpicture}
+\end{codeexample}
+
+ Here is an example that shows how markings can be used to place text on
+ plots:
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{decorations.markings}}]
+\begin{tikzpicture}[domain=0:4,label/.style={postaction={
+ decorate,
+ decoration={
+ markings,
+ mark=at position .75 with \node #1;}}}]
+ \draw[very thin,color=gray] (-0.1,-1.1) grid (3.9,3.9);
+
+ \draw[->] (-0.2,0) -- (4.2,0) node[right] {$x$};
+ \draw[->] (0,-1.2) -- (0,4.2) node[above] {$f(x)$};
+
+ \draw[red,label={[above left]{$f(x)=x$}}] plot (\x,\x);
+ \draw[blue,label={[below left]{$f(x)=\sin x$}}] plot (\x,{sin(\x r)});
+ \draw[orange,label={[right]{$f(x)= \frac{1}{20} \mathrm e^x$}}] plot (\x,{0.05*exp(\x)});
+\end{tikzpicture}
+\end{codeexample}
+
+ When the \meta{code} is being executed, two special keys will have been
+ set up, whose value may be of interest:
+ %
+ \begin{key}{/pgf/decoration/mark info/sequence number}
+ This key can only be read. Its value (which can be obtained using
+ the |\pgfkeysvalueof| command) is a ``sequence number'' of the
+ mark. The first mark that is added to a path has number |1|, the
+ second number |2|, and so on. This key is mainly useful in
+ conjunction with repeated markings (see below).
+ \end{key}
+ %
+ \begin{key}{/pgf/decoration/mark info/distance from start}
+ This key can only be read. Its value is the distance of the marking
+ from the start of the path in points. For instance, if the path
+ length is 100pt and the marking is in the middle of the path, the
+ value of this key would be |50.0pt|.
+ \end{key}
+ \end{key}
+
+ A second way to use the |mark| key is the following:
+ %
+ \begin{key}{/pgf/decoration/mark=\texttt{between positions }\meta{start pos}\texttt{ and }\meta{end pos}\texttt{ step }\meta{stepping}\texttt{ with }\meta{code}}
+ This works similarly to the |at position| version of this option, only
+ multiple marks are placed, starting at \meta{start pos} and then spaced
+ apart by \meta{stepping}. The \meta{start pos}, the \meta{end pos}, and
+ also the \meta{stepping} may all be specified in the same way as for
+ the |at position| version, that is, either using units or no units and
+ also using positive or negative values.
+
+ Let us start with a simple example in which we place ten crosses along
+ a path starting with the beginning of the path ($\meta{start pos} = 0$)
+ and ending at the end ($\meta{end pos} = 1$).
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{decorations.markings}}]
+\begin{tikzpicture}[decoration={markings,
+ mark=between positions 0 and 1 step 0.1
+ with { \draw (-2pt,-2pt) -- (2pt,2pt);
+ \draw (2pt,-2pt) -- (-2pt,2pt); }} ]
+ \draw [help lines] grid (3,2);
+ \draw [postaction={decorate}] (0,0) -- (3,1) arc (0:180:1.5 and 1);
+\end{tikzpicture}
+\end{codeexample}
+
+ In the next example we place arrow shapes on the path instead of
+ crosses. Note the use of the |transform shape| option to ensure that
+ the nodes are actually rotated.
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{decorations.markings,shapes.arrows}}]
+\begin{tikzpicture}[decoration={markings,
+ mark=between positions 0 and 1 step 1cm
+ with { \node [single arrow,fill=red,
+ single arrow head extend=3pt,transform shape] {};}}]
+ \draw [help lines] grid (3,2);
+ \draw [postaction={decorate}] (0,0) -- (3,1) arc (0:180:1.5 and 1);
+\end{tikzpicture}
+\end{codeexample}
+
+ Using the key |sequence number| we can also ``number'' the nodes and
+ even refer to them later on.
+ %
+% FIXME: the automatic key highlighting fails here!
+\begin{codeexample}[preamble={\usetikzlibrary{decorations.markings}}]
+\begin{tikzpicture}[decoration={markings,
+ mark=between positions 0 and 1 step 1cm with {
+ \node [draw,
+ name=mark-\pgfkeysvalueof{/pgf/decoration/mark info/sequence number},
+ transform shape]
+ {\pgfkeysvalueof{/pgf/decoration/mark info/sequence number}};}}]
+ \draw [help lines] grid (3,2);
+ \draw [postaction={decorate}] (0,0) -- (3,1) arc (0:180:1.5 and 1);
+ \draw [red,->] (mark-3) -- (mark-7);
+\end{tikzpicture}
+\end{codeexample}
+
+ In the following example we use the distance info to place ``length
+ information'' on a path:
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{decorations.markings}}]
+\begin{tikzpicture}[decoration={markings,
+ % Main marks
+ mark=between positions 0 and 1 step 40pt with
+ { \draw [help lines] (0,0) -- (0,0.5)
+ node[above,font=\tiny]{
+ \pgfkeysvalueof{/pgf/decoration/mark info/distance from start}}; },
+ mark=at position -0.1pt with
+ { \draw [help lines] (0,0) -- (0,0.5)
+ node[above,font=\tiny]{
+ \pgfkeysvalueof{/pgf/decoration/mark info/distance from start}}; }}]
+ \draw [help lines] grid (5,3);
+ \draw [postaction={decorate}] (0,0) .. controls (8,3) and (0,3) .. (5,0) ;
+\end{tikzpicture}
+\end{codeexample}
+ \end{key}
+
+ \begin{key}{/pgf/decoration/reset marks}
+ Since |mark| options accumulate, there needs to be a way to ``reset''
+ things, so that any |mark| options set in an enclosing scope do not
+ interfere. This option does exactly this. Note that when the
+ \meta{code} of a marking is executed, the markings are automatically
+ reset.
+ \end{key}
+
+ As mentioned earlier, the decoration usually destroys the path. However,
+ this is no longer the case when the following key is set:
+ %
+ \begin{key}{/pgf/decoration/mark connection node=\meta{node name} (initially empty)}
+ When this key is set to a non-empty \meta{node name} while the
+ decoration is being processed, the following happens: The marking code
+ should, among possibly other things, define a node named \meta{node
+ name}. Then, the output path of this decoration will contain a line-to
+ to ``one end'' of this node, followed by a moveto to the ``other end''
+ of the node. More precisely, the first end is given by the position on
+ the border of \meta{node name} that lies in the direction ``from which
+ the path heads toward the node'' while the other end lies on the border
+ ``where the path heads away from the node''. Furthermore, this option
+ causes the decoration to end with a line-to to the end instead of a
+ move-to.
+
+ The net effect of all this is that when you decorate a straight line
+ with one or more markings that contain just a node, the line will
+ effectively connect these nodes.
+
+ Here are two examples that show how this works:
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{decorations.markings}}]
+\begin{tikzpicture}[decoration={markings,
+ mark connection node=my node,
+ mark=at position .5 with
+ {\node [draw,blue,transform shape] (my node) {my node};}}]
+ \draw [help lines] grid (3,2);
+ \draw decorate { (0,0) -- (3,2) };
+\end{tikzpicture}
+\end{codeexample}
+
+\begin{codeexample}[preamble={\usetikzlibrary{decorations.markings}}]
+\begin{tikzpicture}[decoration={markings,
+ mark connection node=my node,
+ mark=at position .25 with
+ {\node [draw,red] (my node) {my node};}}]
+ \draw [help lines] grid (3,2);
+ \draw decorate { (0,0) -- (3,2) };
+\end{tikzpicture}
+\end{codeexample}
+ \end{key}
+\end{decoration}
+
+
+\subsubsection{Arrow Tip Markings}
+
+Frequent markings that are hard to create correctly are arrow tips. For them,
+two special commands are available when the \meta{code} of a |mark| option is
+executed. (They are only defined in this code):
+
+\begin{command}{\arrow\opt{\oarg{options}}\marg{arrow end tip}}
+ This command simply draws the \meta{arrow end tip} at the origin, pointing
+ right. This is exactly what you need when you want to draw an arrow tip as
+ a marking.
+
+ The \meta{options} can only be given when \tikzname\ is used. In this case,
+ they are executed in a scope that contains the arrow tip.
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{decorations.markings}}]
+\begin{tikzpicture}[decoration={
+ markings,% switch on markings
+ mark=at position 1cm with {\node[red]{1cm};},
+ mark=at position .75 with {\arrow[blue,line width=2mm]{>}},
+ mark=at position -1cm with {\arrowreversed[black]{stealth}}}
+ ]
+ \draw [help lines] grid (3,2);
+ \draw [postaction={decorate}] (0,0) -- (3,1) arc (0:180:1.5 and 1);
+\end{tikzpicture}
+\end{codeexample}
+
+ Here is a more useful example:
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{decorations.markings}}]
+\begin{tikzpicture}[decoration={
+ markings,% switch on markings
+ mark=between positions 0 and .75 step 4mm with {\arrow{stealth}},
+ mark=between positions .75 and 1 step 4mm with {\arrowreversed{stealth}}}
+ ]
+ \draw [help lines] grid (3,2);
+ \draw [postaction={decorate}] (0,0) -- (3,1) arc (0:180:1.5 and 1);
+\end{tikzpicture}
+\end{codeexample}
+ %
+\end{command}
+
+\begin{command}{\arrowreversed\opt{\oarg{options}}\marg{arrow end tip}}
+ As above, only the arrow end tip is flipped and points in the other
+ direction.
+\end{command}
+
+
+\subsubsection{Footprint Markings}
+
+\begin{pgflibrary}{decorations.footprints}
+ The decorations of this library can be used to decorate a path with little
+ footprints, as if someone had ``walked'' along the path.
+\end{pgflibrary}
+
+\begin{decoration}{footprints}
+ The footprint decoration adds little footprints around the path. They start
+ with the left foot.
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{decorations.footprints}}]
+\begin{tikzpicture}[decoration={footprints,foot length=5pt,stride length=10pt}]
+ \draw [help lines] grid (3,3);
+ \fill [decorate] (0,0) -- (3,2) arc (0:180:1.5 and 1);
+\end{tikzpicture}
+\end{codeexample}
+ %
+ You can influence the way this decoration looks using the following
+ options:
+ %
+ \begin{key}{/pgf/decoration/foot length (initially 10pt)}
+ The length or size of the footprint itself. A larger value makes the
+ footprint larger, but does not change the stride length.
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{decorations.footprints}}]
+\begin{tikzpicture}[decoration={footprints,foot length=20pt}]
+ \fill [decorate] (0,0) -- (3,0);
+\end{tikzpicture}
+\end{codeexample}
+ \end{key}
+ %
+ \begin{key}{/pgf/decoration/stride length (initially 30pt)}
+ The length of strides. This is the distance between the beginnings of
+ left footprints along the path.
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{decorations.footprints}}]
+\begin{tikzpicture}[decoration={footprints,stride length=50pt}]
+ \fill [decorate] (0,0) -- (3,0);
+\end{tikzpicture}
+\end{codeexample}
+ \end{key}
+ %
+ \begin{key}{/pgf/decoration/foot sep (initially 4pt)}
+ The separation in the middle between the footprints. The footprints are
+ moved away from the path by half this amount.
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{decorations.footprints}}]
+\begin{tikzpicture}[decoration={footprints,foot sep=10pt}]
+ \fill [decorate] (0,0) -- (3,0);
+\end{tikzpicture}
+\end{codeexample}
+ \end{key}
+ %
+ \begin{key}{/pgf/decoration/foot angle (initially 10)}
+ Footprints are rotated by this much.
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{decorations.footprints}}]
+\begin{tikzpicture}[decoration={footprints,foot angle=60}]
+ \fill [decorate] (0,0) -- (3,0);
+\end{tikzpicture}
+\end{codeexample}
+ \end{key}
+ %
+ \begin{key}{/pgf/decoration/foot of (initially human)}
+ The species whose footprints are shown. Possible values are:
+
+ \def\render#1{
+ \texttt{#1} &
+ \tikz [baseline,decoration={footprints,foot of=#1}]
+ \fill [decorate] (0,0) -- (6,0); \\[3em]
+ }
+ \begin{tabular}{ll}
+ \emph{Species} & \emph{Result} \\[1em]
+ \render{gnome}
+ \render{human}
+ \render{bird}
+ \render{felis silvestris}
+ \end{tabular}
+ \end{key}
+\end{decoration}
+
+
+\subsubsection{Shape Background Markings}
+
+The third library for adding markings uses the background paths of certain
+shapes. This library is included mostly for historical reasons, using the
+|markings| library is usually preferable.
+
+\begin{pgflibrary}{decorations.shapes}
+ This library defines decorations that use shapes or shape-like drawings to
+ decorate a path. The following options are common options used by the
+ decorations in this library:
+
+ \begin{key}{/pgf/decoration/shape width=\meta{dimension} (initially 2.5pt)}
+ The desired width of the shapes. For decorations that support varying
+ shape sizes, this key sets both the start and end width (which can be
+ overwritten using options like |shape start width|).
+ \end{key}
+
+ \begin{key}{/pgf/decoration/shape height=\meta{dimension} (initially 2.5pt)}
+ Works like the previous key, only for the height.
+ \end{key}
+
+ \begin{key}{/pgf/decoration/shape size=\meta{dimension}}
+ Sets the desired width and height simultaneously.
+ \end{key}
+
+ For the exact places and macros where these keys store the values, please
+ consult the beginning of the code of the library.
+\end{pgflibrary}
+
+\begin{decoration}{crosses}
+ This decoration replaces the path by (diagonal) crosses. The following
+ parameters influence the decoration:
+ %
+ \begin{itemize}
+ \item |segment length| determines the distance between (the centers of)
+ consecutive crosses.
+ \item |shape height| determines the height of each cross.
+ \item |shape width| determines the width of each cross.
+ \end{itemize}
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{decorations.shapes}}]
+\begin{tikzpicture}[decoration=crosses]
+ \draw [help lines] grid (3,2);
+ \draw [decorate] (0,0) -- (3,1) arc (0:180:1.5 and 1);
+\end{tikzpicture}
+\end{codeexample}
+ %
+\end{decoration}
+
+\begin{decoration}{triangles}
+ This decoration replaces the path by triangles that point along the path.
+ The following parameters influence the decoration:
+ %
+ \begin{itemize}
+ \item |segment length| determines the distance between consecutive
+ triangles.
+ \item |shape height| determines the height of the triangle side that is
+ orthogonal to the path.
+ \item |shape width| determines the width of the triangle.
+ \end{itemize}
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{decorations.shapes}}]
+\begin{tikzpicture}[decoration=triangles]
+ \draw [help lines] grid (3,2);
+ \draw [decorate,fill=yellow!80!black] (0,0) -- (3,1) arc (0:180:1.5 and 1);
+\end{tikzpicture}
+\end{codeexample}
+ %
+\end{decoration}
+
+\begin{decoration}{shape backgrounds}
+ This is a general decoration that replaces the to-be-decorated path by
+ repeated copies of the background path of an arbitrary shape that has
+ previously been defined using the |\pgfdeclareshape| command (that is, you
+ can use any shape in the shape libraries).
+
+ Please note that the background path of the shapes is used, but \emph{no
+ nodes are created}. This means that \emph{you cannot have text inside the
+ shapes of this path, you cannot name them, or refer to them.} Finally, this
+ decoration \emph{will not work with shapes that depend strongly on the
+ size of the text box (like the arrow shapes).} If any of these restrictions
+ pose a problem, use the |markings| library instead.
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{decorations.shapes,shapes.geometric}}]
+\begin{tikzpicture}[decoration={shape backgrounds,shape=star,shape size=5pt}]
+ \draw [help lines] grid (3,2);
+ \draw [decorate] (0,0) -- (3,1) arc (0:180:1.5 and 1);
+\end{tikzpicture}
+\end{codeexample}
+
+\begin{codeexample}[preamble={\usetikzlibrary{decorations.shapes,shapes.geometric}}]
+\tikzset{paint/.style={ draw=#1!50!black, fill=#1!50 },
+ decorate with/.style=
+ {decorate,decoration={shape backgrounds,shape=#1,shape size=2mm}}}
+\begin{tikzpicture}
+ \draw [decorate with=dart, paint=red] (0,1.5) -- (3,1.5);
+ \draw [decorate with=diamond, paint=green] (0,1) -- (3,1);
+ \draw [decorate with=rectangle, paint=blue] (0,0.5) -- (3,0.5);
+ \draw [decorate with=circle, paint=yellow] (0,0) -- (3,0);
+\end{tikzpicture}
+\end{codeexample}
+
+ All shapes are positioned by the anchor that is specified via the |anchor|
+ decoration option:
+
+ \begin{key}{/pgf/decoration/anchor=\meta{anchor} (initially center)}
+ The anchor used to position the shape backgrounds.
+ \end{key}
+
+ A shape background path is added at the start point of the path and, if the
+ distance between the shapes is appropriate, at the end point of the path.
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{decorations.shapes,shapes.geometric}}]
+\begin{tikzpicture}[decoration={
+ shape backgrounds,shape=regular polygon,shape size=4mm}]
+ \draw [help lines] grid (3,2);
+ \draw [thick] (0,0) -- (2,2) (1,0) -- (3,0);
+ \draw [red, decorate, decoration={shape sep=.5cm}] (1,0) -- (3,0);
+ \draw [blue, decorate, decoration={shape sep=.5cm}] (0,0) -- (2,2);
+\end{tikzpicture}
+\end{codeexample}
+
+ Keys for customizing specific shapes can be specified (e.g., |star points|,
+ |cloud puffs|, |kite angles|, and so on). The size of the shape is
+ ``enforced'' using transformations. This means that the shape is typeset
+ with an empty text box and some default size values, resulting in an
+ initial shape. This shape is then rescaled using coordinate transformations
+ so that it has the desired size (which may vary as we travel along the
+ to-be-decorated path). This means that settings involving angles and
+ distances may not appear entirely accurate. More general options such as
+ |inner sep| and |minimum size| will be ignored, but transformations can be
+ applied to each segment as described below.
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{decorations.shapes,shapes.geometric}}]
+\tikzset{
+ paint/.style={draw=#1!50!black, fill=#1!50},
+ my star/.style={decorate,decoration={shape backgrounds,shape=star},
+ star points=#1}
+}
+\begin{tikzpicture}[decoration={shape sep=.5cm, shape size=.5cm}]
+ \draw [my star=9, paint=red] (0,1.5) -- (3,1.5);
+ \draw [my star=5, paint=blue] (0,.75) -- (3,.75);
+ \draw [my star=5, paint=yellow, shape border rotate=30] (0,0) -- (3,0);
+\end{tikzpicture}
+\end{codeexample}
+
+ There are various keys to control the drawing of the shape decoration.
+
+ \begin{key}{/pgf/decoration/shape=\meta{shape name} (initially circle)}
+ The shape whose background path is used.
+ \end{key}
+
+ \begin{key}{/pgf/decoration/shape sep=\meta{spacing} (initially {.25cm, between centers})}
+ Set the spacing between the shapes on the decorations path. This can be
+ just a distance on its own, but the additional keywords
+ |between centers|, and |between borders| (which must be preceded by a
+ comma), specify that the distance is between the center anchors of the
+ shapes or between the edges of the \emph{boundaries} of the shape
+ borders.
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{decorations.shapes,shapes.symbols}}]
+\begin{tikzpicture}[
+ decoration={shape backgrounds,shape size=.5cm,shape=signal},
+ signal from=west, signal to=east,
+ paint/.style={decorate, draw=#1!50!black, fill=#1!50}]
+ \draw [help lines] grid (3,2);
+ \draw [paint=red, decoration={shape sep=.5cm}]
+ (0,2) -- (3,2);
+ \draw [paint=green, decoration={shape sep={1cm, between centers}}]
+ (0,1) -- (3,1);
+ \draw [paint=blue, decoration={shape sep={1cm, between borders}}]
+ (0,0) -- (3,0);
+\end{tikzpicture}
+\end{codeexample}
+ \end{key}
+
+ \begin{key}{/pgf/decoration/shape evenly spread=\meta{number}}
+ This key overrides the |shape sep| key and forces the decoration to fit
+ \meta{number} shapes evenly across the path. If \meta{number} is less
+ than |1|, then no shapes will be used. If \meta{number} equals |1|,
+ then one shape is put in the middle of the path. The additional
+ keywords |by centers| (the default, if no keyword is specified) and
+ |by borders| can be used (both preceded by a comma), to specify how the
+ distance between shapes is determined. These keywords will only have a
+ noticeable effect if the shapes sizes differ over time.
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{decorations.shapes}}]
+\tikzset{
+ paint/.style={draw=#1!50!black, fill=#1!50},
+ spreading/.style={
+ decorate,decoration={shape backgrounds, shape=rectangle,
+ shape start size=4mm,shape end size=1mm,shape evenly spread={#1}}}
+}
+\begin{tikzpicture}
+ \fill [paint=green,spreading={5, by borders},
+ decoration={shape scaled}] (0,2) -- (3,2);
+ \fill [paint=blue,spreading={5, by centers},
+ decoration={shape scaled}] (0,1.5) -- (3,1.5);
+ \fill [paint=red, spreading=5] (0,1) -- (3,1);
+ \fill [paint=orange, spreading=4] (0,.5) -- (3,.5);
+ \fill [paint=gray, spreading=1] (0,0) -- (3,0);
+\end{tikzpicture}
+\end{codeexample}
+ \end{key}
+
+ \begin{key}{/pgf/decoration/shape sloped=\opt{\meta{boolean}} (initially true)}
+ By default, shapes are rotated to the slope of the decorations path. If
+ \meta{boolean} is the value |false|, then this rotation is turned off.
+ Internally this sets the \TeX-if |\ifpgfshapedecorationsloped|
+ accordingly.
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{decorations.shapes,shapes.geometric}}]
+\tikzset{
+ paint/.style={draw=#1!50!black, fill=#1!50}
+}
+\begin{tikzpicture}[decoration={
+ shape width=.65cm, shape height=.45cm,
+ shape=isosceles triangle, shape sep=.75cm,
+ shape backgrounds}]
+ \draw [help lines] grid (3,2);
+ \draw [paint=red,decorate] (0,0) -- (2,2);
+ \draw [paint=blue,decorate,decoration={shape sloped=false}]
+ (1,0) -- (3,2);
+\end{tikzpicture}
+\end{codeexample}
+ \end{key}
+
+ It is possible to scale the width and height of the shapes along the length
+ of the decorations path. The shapes are scaled between the starting size
+ and the ending size. The following keys customize the way the decoration
+ shapes are scaled:
+
+ \begin{key}{/pgf/decoration/shape scaled=\meta{boolean} (initially false)}
+\begin{codeexample}[preamble={\usetikzlibrary{decorations.shapes}}]
+\tikzset{
+ bigger/.style={decoration={shape start size=.125cm, shape end size=.5cm}},
+ smaller/.style={decoration={shape start size=.5cm, shape end size=.125cm}},
+ decoration={shape backgrounds,
+ shape sep={.25cm, between borders},shape scaled}
+}
+\begin{tikzpicture}
+ \draw [help lines] grid (3,2);
+ \fill [decorate, bigger, red!50] (0,1) -- (3,2);
+ \fill [decorate, smaller, blue!50] (0,0) -- (3,1);
+\end{tikzpicture}
+\end{codeexample}
+
+ If this key is set to false (which is the default), then only the start
+ width and height are used. Note that the keys |shape width| and
+ |shape height| set the start and end height simultaneously.
+ \end{key}
+
+ \begin{key}{/pgf/decoration/shape start width=\meta{length} (initially 2.5pt)}
+ The starting width of the shape.
+ \end{key}%
+
+ \begin{key}{/pgf/decoration/shape start height=\meta{length} (initially 2.5pt)}
+ The starting height of the shape.
+ \end{key}%
+
+ \begin{stylekey}{/pgf/decoration/shape start size=\meta{length}}
+ Sets both the start height and start width simultaneously.
+ \end{stylekey}%
+
+ \begin{key}{/pgf/decoration/shape end width=\meta{length} (initially 2.5pt)}
+ The recommended ending width of the shape. Note that this is the width
+ that a shape will take only if it is drawn exactly at the end of the
+ path.
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{decorations.shapes}}]
+\tikzset{
+ bigger/.style={decoration={shape start size=.25cm, shape end size=1cm}},
+ smaller/.style={decoration={shape start size=1cm, shape end size=.25cm}},
+ decoration={shape backgrounds,
+ shape sep={.25cm, between borders},shape scaled}
+}
+\begin{tikzpicture}
+ \draw [help lines] grid (3,2);
+ \fill [decorate,bigger,
+ decoration={shape sep={.25cm, between borders}}, blue!50]
+ (0,1.5) -- (3,1.5);
+ \fill [decorate,smaller,
+ decoration={shape sep={1cm, between centers}}, red!50]
+ (0,.5) -- (3,.5);
+ \draw [gray, dotted] (0,1.625) -- (3,2) (0,1.375) -- (3,1)
+ (0,1) -- (3,.625) (0,0) -- (3,.375);
+\end{tikzpicture}
+\end{codeexample}
+ \end{key}
+
+ \begin{key}{/pgf/decoration/shape end height=\meta{length}}
+ The recommended ending height of the shape.
+ \end{key}
+
+ \begin{stylekey}{/pgf/decoration/shape end size=\meta{length}}
+ Set both the end height and end width simultaneously.
+ \end{stylekey}
+\end{decoration}
+
+
+\subsection{Text Decorations}
+
+\begin{pgflibrary}{decorations.text}
+ The decoration in this library decorates the path with some text. This can
+ be used to draw text that follows a curve.
+\end{pgflibrary}
+
+\begin{decoration}{text along path}
+ This decoration decorates the path with text. This drawing of the text is a
+ ``side effect'' of the decoration. The to-be-decorated path is only used to
+ determine where the characters should be put and it is thrown away after
+ the decoration is done. This is why no line is shown in the following
+ example.
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{decorations.text}}]
+\catcode`\|12
+\begin{tikzpicture}[decoration={text along path,
+ text={Some long text along a ridiculously long curve that}}]
+ \draw [help lines] grid (3,2);
+ \draw [decorate] (0,0) -- (3,1) arc (0:180:1.5 and 1);
+\end{tikzpicture}
+\end{codeexample}
+
+ \pgfname{} ``does its best'' to typeset the text, however you should note
+ the following points:
+ %
+ \begin{itemize}
+ \item Each character in the text is typeset in a separate |\hbox|. This
+ means that if you want fancy things like kerning or ligatures you
+ will have to manually annotate the characters in the decoration
+ text within a group, for example, |W{\kern-1ptA}TER|.
+ \item Each character is positioned using the center of its baseline. To
+ move the text vertically (relative to the path), the additional
+ decoration key |raise| should be used (see
+ Section~\ref{section-decorations-adjust} for details).
+ \item No attempt is made to ensure characters do not overlap when the
+ angle between segments is considerably less than 180$^\circ$ (this
+ is tricky to do in \TeX{} without a huge processing overhead). In
+ general this should not be too much of a problem, but, once again,
+ kerning can be used in most cases to overcome any undesirable
+ effects.
+ \item It is only possible to typeset text in math mode under
+ considerable restrictions. Math mode is entered and exited using
+ any character of category code 3 (e.g., in plain \TeX{} this is |$|). %$
+ Math subscripts and superscripts need to be contained within
+ braces (e.g., |{^y_i}|) as do commands like |\times| or |\cdot|.
+ However, even modestly complex mathematical typesetting is
+ unlikely to be successful along a path (or even desirable).
+ \item Some inaccuracies in positioning may be particularly apparent at
+ input segment boundaries. This can (unfortunately) only be solved
+ on a case-by-case basis by individually kerning the offending
+ characters within a group.
+ \end{itemize}
+
+ The following keys are used by the |text| decoration:
+ %
+ \begin{key}{/pgf/decoration/text=\meta{text} (initially \normalfont empty)}
+ Sets the text to typeset along the curve. Consecutive spaces are
+ ignored, so |\ | (or |\space| in \LaTeX) should be used to insert
+ multiple spaces. It is possible to format the text using normal
+ formatting commands, such as |\it|, |\bf| and |\color|, within
+ customizable delimiters. Initially these delimiters are both
+ {\tt\char`\|} (however, care will be needed regarding the category
+ codes of delimiters -- see below).
+ %
+{\catcode`\|12
+\begin{codeexample}[preamble={\usetikzlibrary{decorations.text}}]
+\catcode`\|12
+\begin{tikzpicture}
+ \draw [help lines] grid (3,2);
+ \path [decorate,decoration={text along path,
+ text={a big |\color{green}|green|| juicy apple.}}]
+ (0,0) .. controls (0,2) and (3,0) .. (3,2);
+\end{tikzpicture}
+\end{codeexample}
+}
+ %
+ By following the first delimiter with |+|, the formatting commands are
+ added to any existing formatting.
+ %
+{\catcode`\|12
+\begin{codeexample}[preamble={\usetikzlibrary{decorations.text}}]
+\begin{tikzpicture}
+ \draw [help lines] grid (3,2);
+ \path [decorate,decoration={text along path,
+ text={a |\large|big |+\bf\color{red}|red|| juicy apple.}}]
+ (0,0) .. controls (0,2) and (3,0) .. (3,2);
+\end{tikzpicture}
+\end{codeexample}
+}
+
+ Internally, the text is stored in the macro |\pgfdecorationtext|. Any
+ characters that have not been typeset when the end of the path has been
+ reached will be stored in |\pgfdecorationrestoftext|.
+ \end{key}
+
+{\catcode`\|12
+ \begin{key}{/pgf/decoration/text format delimiters=\marg{before}\marg{after} (initially \char`\{|\char`\}\char`\{\char`\})}
+ \catcode`\|13
+
+ Set the characters that the text decoration will use to parse
+ formatting commands. If \meta{after} is empty, then \meta{before} will
+ be used for both delimiters. In general you should stick to characters
+ whose category codes are |11| or |12|. As |+| is used to indicate that
+ the specified format commands are added to any existing ones, you
+ should avoid using |+| as a delimiter.
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{decorations.text}}]
+\begin{tikzpicture}
+ \draw [help lines] grid (3,2);
+ \path [decorate, decoration={text along path,text format delimiters={[}{]},
+ text={A big [\color{red}]red[] and [\color{green}]green[] apple.}}]
+ (0,0) .. controls (0,2) and (3,0) .. (3,2);
+\end{tikzpicture}
+\end{codeexample}
+ \end{key}
+}
+
+ \begin{key}{/pgf/decoration/text color=\meta{color} (initially black)}
+ The color of the text.
+ \end{key}
+
+ \begin{key}{/pgf/decoration/reverse path=\meta{boolean} (initially false)}
+ This key reverses the path. This is especially useful for typesetting
+ text along different sides of curves.
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{decorations.text}}]
+\begin{tikzpicture}
+ \draw [help lines] grid (3,2);
+ \draw [gray, ->]
+ [postaction={decoration={text along path,
+ text={a big juicy apple}, text color=red}, decorate}]
+ [postaction={decoration={text along path,
+ text={a big juicy apple}, text color=blue, reverse path}, decorate}]
+ (3,0) .. controls (3,2) and (0,2) .. (0,0);
+\end{tikzpicture}
+\end{codeexample}
+ %
+ \end{key}
+
+ \begin{key}{/pgf/decoration/text align={\ttfamily\char`\{}\meta{alignment options}{\ttfamily\char`\}}}
+ This changes the key path to |/pgf/decoration/text align| and executes
+ \meta{alignment options}.
+ \end{key}
+
+ \begin{key}{/pgf/decoration/text align/align=\meta{alignment} (initially left)}
+ Aligns the text according to \meta{alignment}, which should be one of
+ |left|, |right|, or |center|.
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{decorations.text}}]
+\begin{tikzpicture}
+\draw [help lines] grid (3,2);
+\draw [red, dashed]
+[postaction={decoration={text along path, text={a big juicy apple},
+ text align={align=right}}, decorate}]
+(0,0) .. controls (0,2) and (3,2) .. (3,0);
+\end{tikzpicture}
+\end{codeexample}
+ \end{key}
+
+ \begin{stylekey}{/pgf/decoration/text align/left}
+ Aligns the text to the left end of the path.
+ \end{stylekey}
+
+ \begin{stylekey}{/pgf/decoration/text align/right}
+ Aligns the text to the right end of the path.
+ \end{stylekey}
+
+ \begin{stylekey}{/pgf/decoration/text align/center}
+ Aligns the text to the center of the path.
+ \end{stylekey}
+
+ \begin{key}{/pgf/decoration/text align/left indent=\meta{length} (initially 0pt)}
+ Specifies a distance which the automaton should move along before it
+ starts typesetting the text.
+ \end{key}
+
+ \begin{key}{/pgf/decoration/text align/right indent=\meta{length} (initially 0pt)}
+ Specifies a distance before the end of the path, where the automaton
+ should stop typesetting the text.
+ \end{key}
+
+ \begin{key}{/pgf/decoration/text align/fit to path=\meta{boolean} (initially false)}
+ This key makes the decoration automaton try to fit the text to the
+ length of the path. The automaton shifts forward by a small amount
+ between each character in order to fit the text to the path. If,
+ however, the length of the text is longer than the length of the path
+ (i.e., the automaton would have to shift \emph{backwards} between
+ characters) this key will have no effect.
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{decorations.text}}]
+\begin{tikzpicture}
+ \draw [help lines] grid (3,2);
+ \draw [red, dashed]
+ [postaction={decoration={text along path, text={a big juicy apple},
+ text align=fit to path}, decorate}]
+ (0,0) .. controls (0,2) and (3,2) .. (3,0);
+\end{tikzpicture}
+\end{codeexample}
+ %
+ \end{key}
+
+ \begin{key}{/pgf/decoration/text align/fit to path stretching spaces=\meta{boolean} (initially false)}
+ This key works like the previous key except the automaton shifts
+ forward only for space characters (including |\space|, but
+ \emph{excluding} |\ |).
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{decorations.text}}]
+\begin{tikzpicture}
+ \draw [help lines] grid (3,2);
+ \draw [red, dashed]
+ [postaction={decoration={text along path, text={a big juicy apple},
+ text align={fit to path stretching spaces}}, decorate}]
+ (0,0) .. controls (0,2) and (3,2) .. (3,0);
+\end{tikzpicture}
+\end{codeexample}
+ \end{key}
+\end{decoration}
+
+\begin{decoration}{text effects along path}
+ This decoration is similar to the |text along path| decoration except that
+ each character is inserted into the picture as a \tikzname\ node, and node
+ options (such as |text|, |scale| and |opacity|) can be used to create `text
+ effects'.
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{decorations.text,math}}]
+\bfseries\large
+\begin{tikzpicture}[decoration={text effects along path,
+ text={text effects along path!}, text align=center,
+ text effects/.cd,
+ character count=\i, character total=\n,
+ characters={evaluate={\c=\i/\n*100;}, text along path, text=red!\c!orange},
+ character widths={text along path, xslant=0, yscale=1}}]
+
+\path [postaction={decorate}, preaction={decorate,
+ text effects={characters/.append={yscale=-1.5, opacity=0.5,
+ text=gray, xslant=(\i/\n-0.5)*3}}}]
+ (0,0) .. controls ++(2,1) and ++(-2,-1) .. (3,4);
+\end{tikzpicture}
+\end{codeexample}
+
+ There are some important differences between this decoration and the
+ |text along path| decoration:
+ %
+ \begin{itemize}
+ \item formatting (e.g., font and color) cannot be specified in the
+ decoration text. They can only be specified using the keys
+ described below.
+ \item as a consequence of using the \tikzname\ node options, this
+ decoration is only available in \tikzname.
+ \item due to the number of computations involved, this is quite a slow
+ decoration.
+ \end{itemize}
+
+ The following keys are shared with the |text along path| decoration:
+
+ \begin{key}{/pgf/decoration/text=\marg{text}}
+ Set the text this decoration will use. Braces can be used to group
+ multiple characters together, or commands that should not be expanded
+ until they are typeset, for example |gr{\"o}{\ss}eren|. You should
+ \emph{not} use the formatting delimiters or math mode characters that
+ the |text along path| decoration supports.
+ \end{key}
+
+ \begin{key}{/pgf/decoration/text align=\meta{align}}
+ This sets the alignment of the text along the path. The \meta{align}
+ argument should be |left|, |right| or |center|. Spreading the text out,
+ or stretching the spaces between words is \emph{not} supported.
+ \end{key}
+
+ The decoration text can be thought of as consisting of \emph{characters}
+ arranged in to sequences of \emph{letters} to make \emph{words} which are
+ separated by a \emph{word separator}. This, however, does not mean that you
+ are limited to using only natural language as the decoration text.
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{decorations.text}}]
+\begin{tikzpicture}[decoration={text effects along path,
+ text={000-001-010-011-100-101-110-111},
+ text effects/.cd,
+ path from text,
+ word separator=-,
+ every letter/.style={shape=rectangle, fill=blue!20, draw=blue!40}}]
+
+\path [decorate] (0,0);
+\end{tikzpicture}
+\end{codeexample}
+
+ In addition, it is possible to replace characters with \tikzname\ code:
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{decorations.text}}]
+\begin{tikzpicture}[decoration={text effects along path,
+ text={000-001-010-011-100-101-110-111}, text align=center,
+ text effects/.cd,
+ word separator=-,
+ replace characters=0 with {\fill [purple] circle [radius=2pt]; },
+ replace characters=1 with {\fill [orange] circle [radius=2pt]; },
+ replace characters=- with {\path circle [radius=2pt]; },
+ every letter/.style={shape=rectangle, fill=blue!20, draw=blue!40}}]
+
+\path [decorate] (0,0) .. controls ++(2,0) and ++(-2,0) .. (3,4);
+\end{tikzpicture}
+\end{codeexample}
+
+ There are many keys and styles that can be used to add effects to the
+ decoration text. Many of these keys have the parent path
+ |/pgf/decoration/text effects/|, but for convenience, these keys can be
+ accessed using the following key:
+
+ \begin{key}{/tikz/text effects=\marg{options}}
+ Execute every option in \marg{options} with the key path for each option
+ temporarily set to |/pgf/decoration/text effects/|.
+ \end{key}
+
+ The following keys can be used to customise the
+ appearance of text in the |text effects along path|
+ decoration.
+
+ \begin{stylekey}{/pgf/decoration/text effects/every character}
+ Set the effects that will be applied to every character in the
+ decoration text. The effects will typically be \tikzname\ node options.
+ Initially, this style is empty so the decoration simply positions nodes
+ at the appropriate position along the path. In order to make the text
+ `follow the path' like the |text along path| decoration the following
+ key can be added to the |every character| style.
+ \end{stylekey}
+
+ \begin{stylekey}{/pgf/decoration/text effects/text along path}
+ This style automatically sets the \tikzname\ keys |transform shape| (to
+ make the character slope with the path), |anchor=baseline| (to make the
+ baseline of the characters `sit' on the path) and |inner xsep=0pt| (to
+ horizontally fit each node to the character it contains, reducing the
+ spacing between characters).
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{decorations.text}}]
+\begin{tikzpicture}[decoration={text effects along path,
+ text={text effects along path!}}]
+
+\path [draw=red, dotted, postaction={decorate}]
+ (0,0) .. controls ++(1,0) and ++(-1,0) .. (3,2);
+\path [draw=blue, dotted, yshift=1cm, postaction={decorate},
+ text effects={text along path}]
+ (0,0) .. controls ++(1,0) and ++(-1,0) .. (3,2);
+\end{tikzpicture}
+\end{codeexample}
+ \end{stylekey}
+
+ \begin{key}{/pgf/decoration/text effects/characters=\marg{effects}}
+ Shorthand for the |every character|.
+ \end{key}
+
+ \begin{stylekey}{/pgf/decoration/text effects/character \meta{number}}
+ Specify additional effects for the character \meta{number}.
+ \end{stylekey}
+
+ \begin{stylekey}{/pgf/decoration/text effects/every letter}
+ Specify additional effects for every letter (i.e., every character that
+ isn't the word separator) in the decoration text.
+ \end{stylekey}
+
+ \begin{stylekey}{/pgf/decoration/text effects/letter \meta{number}}
+ Specify the effects for letter \meta{number} in \emph{every} word.
+ \end{stylekey}
+
+
+\begin{stylekey}{/pgf/decoration/text effects/every first letter}
+ Specify additional effects for the first letter in \emph{every} word.
+\end{stylekey}
+
+\begin{stylekey}{/pgf/decoration/text effects/every last letter}
+ Specify additional effects for the last letter in \emph{every} word.
+\end{stylekey}
+
+\begin{stylekey}{/pgf/decoration/text effects/every word}
+ Specify additional effects for every word in the decoration text.
+\end{stylekey}
+
+\begin{stylekey}{/pgf/decoration/text effects/word \meta{number}}
+ Specify additional effects for word \meta{number} in the decoration text.
+\end{stylekey}
+
+\begin{stylekey}{/pgf/decoration/text effects/word \meta{m} letter \meta{n}}
+ Specify additional effects for letter \meta{n} in word \meta{m} in the
+ decoration text.
+\end{stylekey}
+
+\begin{stylekey}{/pgf/decoration/text effects/every word separator}
+ Specify additional effects for every character that is a word separator.
+\end{stylekey}
+
+\begin{key}{/pgf/decoration/text effects/word separator=\meta{character} (initially space)}
+ Specify the character that is to be used as the word separator. This
+ \emph{must} be a single character such as |a| or |-| or the special value
+ |space| (which should be used to indicate that spaces should be used as the
+ separator).
+\end{key}
+
+ By default, the width for each character is calculated according to the
+ bounding box of the node in which it is contained. However, if the node is
+ rotated or slanted, or has a substantial |inner sep|, this bounding box
+ will be quite big. The following key enables different effects to be
+ applied to the node that is used to calculate the width.
+
+ \begin{stylekey}{/pgf/decoration/text effects/every character width}
+ This style is applied to the (invisible) nodes used for calculating the
+ width of a character node.
+ \end{stylekey}
+
+ \begin{key}{/pgf/decoration/text effects/character widths=\marg{effects}}
+ Shorthand for the |every character width| style.
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{decorations.text}}]
+\begin{tikzpicture}[decoration={text effects along path,
+ text={text effects along path!}, text align=center,
+ text effects/.cd,
+ character count=\i,
+ characters={xslant=0.5, text along path, name=c-\i}}]
+
+\path [decorate] (0,0) -- (3,2);
+\path [decorate,
+ text effects={character widths={inner xsep=0pt, xslant=0}}]
+ (0,1) -- (3,3);
+\end{tikzpicture}
+\end{codeexample}
+ \end{key}
+
+ It is possible to parameterize effects, perhaps for doing calculations, or
+ labelling nodes based on the number of the character in the decoration
+ text. To access the number of the character, and the total number of
+ characters the following keys can be used. However, these keys should
+ \emph{not} be used inside the style keys given above.
+
+ \begin{key}{/pgf/decoration/text effects/character count=\meta{macro}}
+ Store the number of the character being typeset in \meta{macro}.
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{decorations.text}}]
+\begin{tikzpicture}[decoration={text effects along path,
+ text={text effects along path!},
+ text effects/.cd,
+ path from text,
+ character count=\i, every word separator/.style={fill=red!30},
+ characters={text along path, shape=circle, fill=gray!50}}]
+
+\path [decorate, text effects={characters/.append={label=above:\footnotesize\i}}] (0,0);
+\end{tikzpicture}
+\end{codeexample}
+ \end{key}
+
+ \begin{key}{/pgf/decoration/text effects/character total=\meta{macro}}
+ Store the total number of the characters in the decoration text in
+ \meta{macro}. This key can be used with the |character count| key to
+ produce some quite pleasing effects:
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{decorations.text,math}}]
+\begin{tikzpicture}[decoration={text effects along path,
+ text={text effects along path!},
+ text effects/.cd,
+ character count=\i, character total=\n,
+ characters={text along path, evaluate={\c=\i/\n*100;},
+ text=orange!\c!blue, scale=\i/\n+0.5}}]
+
+\path [decorate]
+ (0,0) .. controls ++(1,0) and ++(-1,0) .. (3,2);
+\end{tikzpicture}
+\end{codeexample}
+ \end{key}
+
+ \begin{key}{/pgf/decoration/text effects/letter count=\meta{macro}}
+ Store the number of letter being typeset (i.e., the position of the
+ character in the word) in \meta{macro}. Numbering starts at |1| and the
+ character acting as a word separator is numbered |0|.
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{decorations.text}}]
+\begin{tikzpicture}[decoration={text effects along path,
+ text={text effects along path!},
+ text effects/.cd,
+ path from text, letter count=\i, every word separator/.style={fill=red!30},
+ characters={text along path, shape=circle, fill=gray!50}}]
+
+\path [decorate, text effects={characters/.append={label=above:\footnotesize\i}}] (0,0);
+\end{tikzpicture}
+\end{codeexample}
+ \end{key}
+
+ \begin{key}{/pgf/decoration/text/effetcs/letter total=\meta{macro}}
+ Store the number of letters in the current word in \meta{macro}. When
+ the character is the word separator, this value is |0|.
+ \end{key}
+
+ \begin{key}{/pgf/decoration/text effects/word count=\meta{macro}}
+ Store the number of words in the decoration text in \meta{macro}.
+ Numbering starts at |1|. When the character is the word separator,
+ \meta{macro} takes the number of the previous word. If the decoration
+ text starts with a word separator \meta{macro} will be |0|.
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{decorations.text}}]
+\begin{tikzpicture}[decoration={text effects along path,
+ text={text effects along path!},
+ text effects/.cd,
+ path from text, word count=\i, every word separator/.style={fill=red!30},
+ characters={text along path, shape=circle, fill=gray!50}}]
+
+ \path [decorate, text effects={characters/.append={label=above:\footnotesize\i}}] (0,0);
+\end{tikzpicture}
+\end{codeexample}
+ %
+ \end{key}
+
+ \begin{key}{/pgf/decoration/text effects/word total=\meta{macro}}
+ Store the total number of words in the decoration text in \meta{macro}.
+ \end{key}
+
+ It is also possible to apply effects to specific characters such as
+ coloring every instance of the character |a|, or changing the font of every
+ |T| in the decoration text:
+
+ \begin{key}{/pgf/decoration/text effects/style characters=\marg{characters} with \marg{effects}}
+ This key enables \meta{effects} to be applied to every character in the
+ decoration text that is specified in \meta{characters}.
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{decorations.text}}]
+\begin{tikzpicture}[decoration={text effects along path,
+ text={Falsches {\"U}ben von Xylophonmusik qu{\"a}lt jeden gr{\"o}{\ss}eren Zwerg},
+ text effects/.cd,
+ path from text,
+ style characters=aeiou{\"U}{\"a}{\"o} with {text=blue},
+ characters={text along path}}]
+
+\path [decorate] (0,0);
+\end{tikzpicture}
+\end{codeexample}
+ \end{key}
+
+ \begin{key}{/pgf/decoration/text effects/path from text=\opt{\marg{true or false}} (default true)}
+ When this key is set to |true| and the decorated path consists only of
+ a single point, the decoration will calculate the width of the
+ decoration text using all the specified parameters as if the decorated
+ path was actually a straight line starting from the given point. This
+ `virtual' straight line is then decorated with the text.
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{decorations.text}}]
+\begin{tikzpicture}[decoration={text effects along path,
+ text={text effects along path!},
+ text effects/.cd,
+ path from text,
+ character count=\i, character total=\n,
+ characters={text along path, scale=\i/\n+0.5}}]
+
+\path [decorate] (0,0);
+\end{tikzpicture}
+\end{codeexample}
+ \end{key}
+
+ \begin{key}{/pgf/decoration/text effects/path from text angle=\meta{angle}}
+ When used in conjunction with the |path from text| key, the straight
+ line that is used as the decorated path is rotated by \meta{angle}
+ around the starting point.
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{decorations.text}}]
+\begin{tikzpicture}[decoration={text effects along path,
+ text={text effects along path!},
+ text effects/.cd,
+ path from text, path from text angle=60,
+ character count=\i, character total=\n,
+ characters={text along path, scale=\i/\n+0.5}}]
+
+\path [decorate] (0,0);
+\end{tikzpicture}
+\end{codeexample}
+ \end{key}
+
+ \begin{key}{/pgf/decoration/text effects/fit text to path=\opt{\meta{true or false}} (default true)}
+ This key will make the decoration increase the space between characters
+ so that the entire path is used by the decoration.
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{decorations.text}}]
+\begin{tikzpicture}[decoration={text effects along path,
+ text={text effects along path!},
+ text effects/every character/.style={text along path}}]
+
+\path [draw=gray, postaction={decorate}, rotate=90]
+ (0,0) .. controls ++(2,0) and ++(-1,0) .. (5,-1);
+\path [draw=gray, postaction={decorate}, rotate=90, yshift=-1cm,
+ text effects={fit text to path}]
+ (0,0) .. controls ++(2,0) and ++(-1,0) .. (5,-1);
+\end{tikzpicture}
+\end{codeexample}
+ %
+ \end{key}
+
+ \begin{key}{/pgf/decoration/text effects/scale text to path=\opt{\meta{true or false}} (default true)}
+ This key will make the decoration scale the text so that the entire
+ path is used by the decoration.
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{decorations.text}}]
+\begin{tikzpicture}[decoration={text effects along path,
+ text={text effects along path!},
+ text effects/every character/.style={text along path}}]
+
+\path [draw=gray, postaction={decorate}, rotate=90]
+ (0,0) .. controls ++(2,0) and ++(-1,0) .. (5,-1);
+\path [draw=gray, postaction={decorate}, rotate=90, yshift=-1cm,
+ text effects={scale text to path}]
+ (0,0) .. controls ++(2,0) and ++(-1,0) .. (5,-1);
+\end{tikzpicture}
+\end{codeexample}
+ %
+ \end{key}
+
+ \begin{key}{/pgf/decoration/text effects/reverse text}
+ Reverse the order of the characters in the decoration text. This may be
+ useful if using `right-to-left` languages. Unfortunately, any leading
+ `soft' spaces in the original text will be lost.
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{decorations.text}}]
+\begin{tikzpicture}[decoration={text effects along path,
+ text={text effects along path!},
+ text effects/.cd,
+ path from text, path from text angle=60,
+ reverse text,
+ character count=\i, character total=\n,
+ characters={text along path, scale=\i/\n+0.5}}]
+
+\path [decorate] (0,0) .. controls ++(1,0) and ++(-1,0) .. (3,2);
+\end{tikzpicture}
+\end{codeexample}
+
+ It is important to note that the |reverse text| key reverses the text
+ \emph{before} doing anything else. This means that the numbering of
+ characters, letters and words will still be in the normal order, so any
+ parameterized effects will have to take this into account.
+ Alternatively, to get the numbering to follow the reversed text, it is
+ possible to reverse the path and then invert the scale:
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{decorations.text}}]
+\begin{tikzpicture}[decoration={text effects along path,
+ text={text effects along path!},
+ text effects/.cd,
+ path from text, path from text angle=60,
+ character count=\i, character total=\n,
+ characters={text along path, scale=\i/\n+0.5}}]
+
+\path [decorate, text effects={reverse text}] (0,0);
+\path [blue, decorate, decoration={reverse path},
+ text effects={characters/.append={scale=-1}}] (1,0);
+\end{tikzpicture}
+\end{codeexample}
+ %
+ \end{key}
+
+ \begin{key}{/pgf/decoration/text effects/group letters}
+ Group sequences of letters together so they are treated as a single
+ `character'.
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{decorations.text}}]
+\begin{tikzpicture}[decoration={text effects along path,
+ text={text effects along path!},
+ text effects/.cd,
+ path from text, path from text angle=60,
+ every word separator/.style={fill=none},
+ character count=\i, character total=\n,
+ characters={text along path, fill=gray!50, scale=\i/\n+0.5}}]
+
+\path [decorate] (0,0);
+\path [decorate, text effects={group letters,
+ characters/.append={fill=red!20}}]
+ (1,0);
+\end{tikzpicture}
+\end{codeexample}
+ \end{key}
+
+ The order in which the |reverse text| and |group letters| keys are applied
+ is important:
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{decorations.text}}]
+\begin{tikzpicture}[decoration={text effects along path,
+ text={text effects along path!},
+ text effects/.cd,
+ path from text, path from text angle=60,
+ every word separator/.style={fill=none},
+ character count=\i, character total=\n,
+ characters={text along path, fill=gray!50, scale=\i/\n+0.5}}]
+
+\path [decorate, text effects={reverse text, group letters}] (0,0);
+\path [decorate, text effects={group letters, reverse text,
+ characters/.append={fill=red!20}}] (1,0);
+\end{tikzpicture}
+\end{codeexample}
+
+ \begin{key}{/pgf/decoration/text effects/repeat text=\opt{\meta{times}}}
+ Usually, when the decoration runs out of text, it simply stops. This
+ key will make the decoration repeat the decoration text for the
+ specified number of \meta{times}. If no value is given the text will be
+ repeated until the path is finished. There are two points to remember
+ however. Firstly the numbering of characters, letters and words will be
+ restarted each time the text is repeated. Secondly, the options for
+ alignment, scaling or fitting the text to the path, fitting the path to
+ the text, and so on, are computed using the decoration text before the
+ decoration starts. If any of these options are given the behavior of
+ the |repeat text| key is undefined, but typically it will be ignored.
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{decorations.text}}]
+\begin{tikzpicture}[decoration={text effects along path,
+ text={text effects along path!\ },
+ text effects/.cd,
+ repeat text,
+ character count=\m, character total=\n,
+ characters={text along path, scale=0.5+\m/\n/2}}]
+
+\path [draw=gray, ultra thin, postaction=decorate]
+ (180:2) \foreach \a in {0,...,12}{ arc (180-\a*90:90-\a*90:1.5-\a/10) };
+\end{tikzpicture}
+\end{codeexample}
+ \end{key}
+
+ \begin{key}{/pgf/decoration/text effects/character command=\meta{macro}}
+ This key specifies a command that is executed when each character is
+ placed in the node. The \meta{macro} should be an ordinary \TeX\ macro
+ which takes one argument. The argument will be a macro which when
+ expanded will contain the current character.
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{decorations.text}}]
+\def\mycommand#1{#1$_\n$}
+\begin{tikzpicture}[decoration={text effects along path,
+ text={text effects along path!},
+ text effects/.cd,
+ path from text, path from text angle=60, group letters,
+ word count=\n,
+ every word/.style={character command=\mycommand},
+ characters={text along path}}]
+
+\path [decorate] (0,0);
+\end{tikzpicture}
+\end{codeexample}
+ \end{key}
+
+ \begin{key}{/pgf/decoration/text effects/replace characters=\meta{characters} with \marg{code}}
+ Replace the node for each character in \meta{characters} with
+ \meta{code}. The \meta{code} can be thought of as describing a little
+ picture or marking which will be used instead of the character node.
+ The origin will be the current point along the decoration path. Any
+ transformations associated with the \meta{characters} (e.g., applied
+ with the |every character| or |every letter| styles) will also be
+ applied to \meta{code}.
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{decorations.text}}]
+\begin{tikzpicture}[decoration={text effects along path,
+ text={text effects along path!},
+ text effects/.cd,
+ path from text, path from text angle=60,
+ replace characters=e with {\fill [red!20] (0,1mm) circle [radius=1mm];},
+ replace characters=a with {\fill [black!20] (0,1mm) circle [radius=1mm];},
+ character count=\i, character total=\n,
+ characters={text along path, scale=\i/\n+0.5}}]
+
+\path [decorate] (0,0);
+\end{tikzpicture}
+\end{codeexample}
+ \end{key}
+\end{decoration}
+
+
+\subsection{Fractal Decorations}
+
+\begin{pgflibrary}{decorations.fractals}
+ The decorations of this library can be used to create fractal lines. To use
+ them, you typically have to apply the decoration repeatedly to an
+ originally straight path.
+\end{pgflibrary}
+
+\begin{decoration}{Koch curve type 1}
+ This decoration replaces a straight line by a ``rectangular bump''. By
+ repeatedly applying this replacement, different levels of the Koch curve
+ fractal can be created. Its Hausdorff dimension is $\log 5/\log 3$.
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{decorations.fractals}}]
+\begin{tikzpicture}[decoration=Koch curve type 1]
+ \draw decorate{ (0,0) -- (3,0) };
+ \draw decorate{ decorate{ (0,-1.5) -- (3,-1.5) }};
+ \draw decorate{ decorate{ decorate{ (0,-3) -- (3,-3) }}};
+\end{tikzpicture}
+\end{codeexample}
+ %
+\end{decoration}
+
+\begin{decoration}{Koch curve type 2}
+ This decoration replaces a straight line by a ``rectangular sine''. Its
+ Hausdorff dimension is $3/2$.
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{decorations.fractals}}]
+\begin{tikzpicture}[decoration=Koch curve type 2]
+ \draw decorate{ (0,0) -- (3,0) };
+ \draw decorate{ decorate{ (0,-2) -- (3,-2) }};
+ \draw decorate{ decorate{ decorate{ (0,-4) -- (3,-4) }}};
+\end{tikzpicture}
+\end{codeexample}
+ %
+\end{decoration}
+
+\begin{decoration}{Koch snowflake}
+ This decoration replaces a straight line by a ``line with a spike''. The
+ Hausdorff dimension of Koch's snowflake's is $\log 4/\log 3$.
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{decorations.fractals}}]
+\begin{tikzpicture}[decoration=Koch snowflake]
+ \draw decorate{ (0,0) -- (3,0) };
+ \draw decorate{ decorate{ (0,-1) -- (3,-1) }};
+ \draw decorate{ decorate{ decorate{ (0,-2) -- (3,-2) }}};
+ \draw decorate{ decorate{ decorate{ decorate{ (0,-3) -- (3,-3) }}}};
+\end{tikzpicture}
+\end{codeexample}
+ %
+\end{decoration}
+
+\begin{decoration}{Cantor set}
+ This decoration replaces a straight line by a ``line with a gap in the
+ middle''. The Hausdorff dimension of the Cantor set is $\log 2/\log 3$.
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{decorations.fractals}}]
+\begin{tikzpicture}[decoration=Cantor set,very thick]
+ \draw decorate{ (0,0) -- (3,0) };
+ \draw decorate{ decorate{ (0,-.5) -- (3,-.5) }};
+ \draw decorate{ decorate{ decorate{ (0,-1) -- (3,-1) }}};
+ \draw decorate{ decorate{ decorate{ decorate{ (0,-1.5) -- (3,-1.5) }}}};
+\end{tikzpicture}
+\end{codeexample}
+ %
+\end{decoration}