diff options
Diffstat (limited to 'graphics/pgf/base/doc/pgfmanual-en-library-decorations.tex')
-rw-r--r-- | graphics/pgf/base/doc/pgfmanual-en-library-decorations.tex | 2181 |
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} |