diff options
Diffstat (limited to 'Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-decorations.tex')
-rw-r--r-- | Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-decorations.tex | 2281 |
1 files changed, 1068 insertions, 1213 deletions
diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-decorations.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-decorations.tex index 277543a1951..58d2b6f3af8 100644 --- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-decorations.tex +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-decorations.tex @@ -7,134 +7,130 @@ % % 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. +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 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|. + 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. + This key determines the amplitude for a meta-decoration. - The key sets the \TeX-macro (!) |\pgfmetadecorationsegmentamplitude|. + 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. + Many decorations are made up of small segments. This key determines the + desired length of such segments. - This key sets the \TeX-dimension |\pgfdecorationsegmentlength|. + 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 determined the length of the meta-segments from which a + meta-decoration is made up. - This key sets the \TeX-macro (!) |\pgfmetadecorationsegmentlength|. + 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|. + 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|. + 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. + 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|. + 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). + For some decorations there is a natural start radius (of some circle, + presumably). - This key stores the value directly inside the key. + 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). + For some decorations there is a natural end radius (of some circle, + presumably). - This key stores the value directly inside the key. + 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. + 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|. + 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{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. + 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. +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 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. + This decoration is actually always defined when the decoration module is + loaded, but it is documented here for consistency. + % \begin{codeexample}[] \begin{tikzpicture}[decoration=lineto] \draw [help lines] grid (3,2); @@ -142,24 +138,23 @@ the paths. (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} - + 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}[] \begin{tikzpicture}[decoration={straight zigzag,meta-segment length=1.1cm}] \draw [help lines] grid (3,2); @@ -167,21 +162,21 @@ the paths. (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} + 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}[] \begin{tikzpicture} [decoration={random steps,segment length=2mm}] @@ -190,18 +185,19 @@ the paths. (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} + 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}[] \begin{tikzpicture}[decoration=saw] \draw [help lines] grid (3,2); @@ -209,19 +205,20 @@ the paths. (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} + 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}[] \begin{tikzpicture}[decoration=zigzag] \draw [help lines] grid (3,2); @@ -229,30 +226,33 @@ the paths. (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. + 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}[] \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}[] \begin{tikzpicture}[decoration={bent,aspect=.3}] \draw [decorate,fill=yellow!80!black] (0,0) rectangle (3.5,2); @@ -262,18 +262,18 @@ the paths. \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} + 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}[] \begin{tikzpicture}[decoration=bumps] \draw [help lines] grid (3,2); @@ -281,29 +281,28 @@ the paths. (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} + 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}[] \begin{tikzpicture}[decoration=coil] \draw [help lines] grid (3,2); @@ -311,6 +310,7 @@ the paths. (0,0) -- (3,1) arc (0:180:1.5 and 1) -- cycle; \end{tikzpicture} \end{codeexample} + % \begin{codeexample}[] \begin{tikzpicture} [decoration={coil,aspect=0.3,segment length=3mm,amplitude=3mm}] @@ -319,22 +319,19 @@ the paths. (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. + 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}[] \begin{tikzpicture}[decoration=curveto] \draw [help lines] grid (3,2); @@ -342,21 +339,19 @@ the paths. (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} + 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}[] \begin{tikzpicture}[decoration=snake] \draw [help lines] grid (3,2); @@ -364,36 +359,35 @@ the paths. (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. + 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} + 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}[] \begin{tikzpicture}[decoration=border] \draw [help lines] grid (3,2); @@ -401,109 +395,105 @@ the paths. (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} + 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}[] \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} + 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}[] \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 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. + 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} + 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}[] \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} + 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}[] \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. - + 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}[] \begin{tikzpicture}[>=stealth, every node/.style={midway, sloped, font=\tiny}, decoration={show path construction, @@ -528,56 +518,53 @@ the paths. \end{tikzpicture} \end{codeexample} + The following keys can be used to specify the code to execute for each type + of input segment. - 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/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/curveto code=\meta{code} (initially \char`\{\char`\})} - Set the code to be executed for every curveto input segment. -\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/closepath code=\meta{code} (initially \char`\{\char`\})} - Set the code to be executed for every closepath 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} -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|. + \begin{key}{/pgf/decoration/closepath code=\meta{code} (initially \char`\{\char`\})} + Set the code to be executed for every closepath input segment. + \end{key} -In \tikzname, you can use the following macros -inside a \tikzname{} coordinate. + 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|. -\begin{command}{\tikzinputsegmentfirst} - The first point on the current input segment path. -\end{command} + In \tikzname, you can use the following macros inside a \tikzname{} + coordinate. -\begin{command}{\tikzinputsegmentlast} - The last point on the current input segment path. -\end{command} + \begin{command}{\tikzinputsegmentfirst} + The first 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}{\tikzinputsegmentlast} + The last point on the current input segment path. + \end{command} -\begin{command}{\tikzinputsegmentsupportb} - The second support on the curveto 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} + % {\tikzexternaldisable \begin{codeexample}[] \tikzset{ @@ -602,61 +589,59 @@ inside a \tikzname{} coordinate. \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. +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. + 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: + 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. + % + 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. + 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: + Let us start with the above example in real code: + % \begin{codeexample}[] \begin{tikzpicture}[decoration={ markings,% switch on markings @@ -674,7 +659,8 @@ a path. We start with the most general and most useful of these libraries. \end{tikzpicture} \end{codeexample} - We can also add the cross repeatedly: + We can also add the cross repeatedly: + % \begin{codeexample}[] \begin{tikzpicture}[decoration={ markings,% switch on markings @@ -692,50 +678,49 @@ a path. We start with the most general and most useful of these libraries. \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}| 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. - + 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}| 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}[] \begin{tikzpicture}[decoration={ markings,% switch on markings @@ -748,8 +733,9 @@ a path. We start with the most general and most useful of these libraries. \end{tikzpicture} \end{codeexample} - Here is an example that shows how markings can be used to place text - on plots: + Here is an example that shows how markings can be used to place text on + plots: + % \begin{codeexample}[] \begin{tikzpicture}[domain=0:4,label/.style={postaction={ decorate, @@ -767,39 +753,42 @@ a path. We start with the most general and most useful of these libraries. \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). + 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} - \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=|between positions| - \meta{start pos} |and| \meta{end pos} |step| \meta{stepping} - |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$). + + A second way to use the |mark| key is the following: + % + \begin{key}{/pgf/decoration/mark=|between positions| + \meta{start pos} |and| \meta{end pos} |step| + \meta{stepping} |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}[] \begin{tikzpicture}[decoration={markings, mark=between positions 0 and 1 step 0.1 @@ -810,9 +799,10 @@ a path. We start with the most general and most useful of these libraries. \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. + 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}[] \begin{tikzpicture}[decoration={markings, mark=between positions 0 and 1 step 1cm @@ -823,9 +813,10 @@ a path. We start with the most general and most useful of these libraries. \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! + 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}[] \begin{tikzpicture}[decoration={markings, mark=between positions 0 and 1 step 1cm with { @@ -839,8 +830,9 @@ a path. We start with the most general and most useful of these libraries. \end{tikzpicture} \end{codeexample} - In the following example we use the distance info to place - ``length information'' on a path: + In the following example we use the distance info to place ``length + information'' on a path: + % \begin{codeexample}[] \begin{tikzpicture}[decoration={markings, % Main marks @@ -856,37 +848,38 @@ a path. We start with the most general and most useful of these libraries. \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: + \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}[] \begin{tikzpicture}[decoration={markings, mark connection node=my node, @@ -906,25 +899,24 @@ a path. We start with the most general and most useful of these libraries. \draw decorate { (0,0) -- (3,2) }; \end{tikzpicture} \end{codeexample} - - \end{key} + \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): +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. + 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. + 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}[] \begin{tikzpicture}[decoration={ markings,% switch on markings @@ -937,7 +929,7 @@ a |mark| option is executed. (They are only defined in this code): \end{tikzpicture} \end{codeexample} - Here is a more useful example: + Here is a more useful example: \begin{codeexample}[] \begin{tikzpicture}[decoration={ markings,% switch on markings @@ -948,173 +940,181 @@ a |mark| option is executed. (They are only defined in this code): \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. + 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. + 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. + The footprint decoration adds little footprints around the path. They start + with the left foot. + % \begin{codeexample}[] \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. + % + 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}[] \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. + \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}[] \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. + \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}[] \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. + \end{key} + % + \begin{key}{/pgf/decoration/foot angle (initially 10)} + Footprints are rotated by this much. + % \begin{codeexample}[] \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{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. +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} + 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} + 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}[] \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} + 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}[] \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. - + 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}[] \begin{tikzpicture}[decoration={shape backgrounds,shape=star,shape size=5pt}] \draw [help lines] grid (3,2); @@ -1134,17 +1134,16 @@ reasons, using the |markings| library is usually preferable. \end{tikzpicture} \end{codeexample} - All shapes are positioned by the anchor that is specified via the - |anchor| decoration option: + 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} + \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. - + 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}[] \begin{tikzpicture}[decoration={ shape backgrounds,shape=regular polygon,shape size=4mm}] @@ -1155,20 +1154,18 @@ reasons, using the |markings| library is usually preferable. \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}[] -\tikzset{ + 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}[] \tikzset{ paint/.style={draw=#1!50!black, fill=#1!50}, my star/.style={decorate,decoration={shape backgrounds,shape=star}, star points=#1} @@ -1180,21 +1177,20 @@ reasons, using the |markings| library is usually preferable. \end{tikzpicture} \end{codeexample} - There are various keys to control the drawing of the shape - decoration. + 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=\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{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}[] \begin{tikzpicture}[ decoration={shape backgrounds,shape size=.5cm,shape=signal}, @@ -1209,20 +1205,18 @@ reasons, using the |markings| library is usually preferable. (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. + \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}[] \tikzset{ paint/.style={draw=#1!50!black, fill=#1!50}, @@ -1240,14 +1234,14 @@ reasons, using the |markings| library is usually preferable. \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. + \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}[] \tikzset{ paint/.style={draw=#1!50!black, fill=#1!50} @@ -1262,14 +1256,14 @@ reasons, using the |markings| library is usually preferable. (1,0) -- (3,2); \end{tikzpicture} \end{codeexample} - \end{key}% + \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: - 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{key}{/pgf/decoration/shape scaled=\meta{boolean} (initially false)} \begin{codeexample}[] \tikzset{ bigger/.style={decoration={shape start size=.125cm, shape end size=.5cm}}, @@ -1284,29 +1278,28 @@ reasons, using the |markings| library is usually preferable. \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}% + 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{stylekey}{/pgf/decoration/shape start size=\meta{length}} - Sets both the start height and start width simultaneously. - \end{stylekey}% + \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 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{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}[] \tikzset{ bigger/.style={decoration={shape start size=.25cm, shape end size=1cm}}, @@ -1326,35 +1319,32 @@ reasons, using the |markings| library is usually preferable. (0,1) -- (3,.625) (0,0) -- (3,.375); \end{tikzpicture} \end{codeexample} - \end{key}% + \end{key} - \begin{key}{/pgf/decoration/shape end height=\meta{length}} - The recommended ending height of the shape. - \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} + \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. + 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. - + 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}[] \catcode`\|12 \begin{tikzpicture}[decoration={text along path, @@ -1364,51 +1354,47 @@ reasons, using the |markings| library is usually preferable. \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 - transform key should be used. - \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). - + \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 + transform key should be used. + \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}[] \catcode`\|12 @@ -1420,10 +1406,10 @@ reasons, using the |markings| library is usually preferable. \end{tikzpicture} \end{codeexample} } - By following the first delimiter - with |+|, the formatting commands are added to any existing - formatting. - + % + By following the first delimiter with |+|, the formatting commands are + added to any existing formatting. + % {\catcode`\|12 \begin{codeexample}[] \begin{tikzpicture} @@ -1434,28 +1420,23 @@ reasons, using the |markings| library is usually preferable. \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} + 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{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}[] \begin{tikzpicture} \draw [help lines] grid (3,2); @@ -1464,18 +1445,17 @@ reasons, using the |markings| library is usually preferable. (0,0) .. controls (0,2) and (3,0) .. (3,2); \end{tikzpicture} \end{codeexample} - \end{key} + \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{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}[] \begin{tikzpicture} \draw [help lines] grid (3,2); @@ -1487,62 +1467,59 @@ reasons, using the |markings| library is usually preferable. (3,0) .. controls (3,2) and (0,2) .. (0,0); \end{tikzpicture} \end{codeexample} + % + \end{key} -\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{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}[] \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); +\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} -\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/left} + Aligns the text to the left 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{stylekey}{/pgf/decoration/text align/right} + Aligns the text to the right end 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{stylekey}{/pgf/decoration/text align/center} + Aligns the text to the center of the path. + \end{stylekey} -\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/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/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{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}[] \begin{tikzpicture} \draw [help lines] grid (3,2); @@ -1552,14 +1529,14 @@ reasons, using the |markings| library is usually preferable. (0,0) .. controls (0,2) and (3,2) .. (3,0); \end{tikzpicture} \end{codeexample} + % + \end{key} -\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{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}[] \begin{tikzpicture} \draw [help lines] grid (3,2); @@ -1569,86 +1546,65 @@ reasons, using the |markings| library is usually preferable. (0,0) .. controls (0,2) and (3,2) .. (3,0); \end{tikzpicture} \end{codeexample} -\end{key} - + \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'. - + 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}[] \bfseries\large -\begin{tikzpicture}[decoration={text effects along path, +\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}}}] +\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 typset, 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} - 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 typset, 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{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}[] \begin{tikzpicture}[decoration={text effects along path, text={000-001-010-011-100-101-110-111}, @@ -1656,14 +1612,13 @@ reasons, using the |markings| library is usually preferable. 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: - + + In addition, it is possible to replace characters with \tikzname\ code: + % \begin{codeexample}[] \begin{tikzpicture}[decoration={text effects along path, text={000-001-010-011-100-101-110-111}, text align=center, @@ -1673,299 +1628,229 @@ reasons, using the |markings| library is usually preferable. 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} + 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: - 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} + \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} - 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). - + 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}[] \begin{tikzpicture}[decoration={text effects along path, - text={text effects along path!}}] - -\path [draw=red, dotted, postaction={decorate}] + 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}] + 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} - + \end{stylekey} -\begin{stylekey}{/pgf/decoration/text effects/every letter} + \begin{key}{/pgf/decoration/text effects/characters=\marg{effects}} + Shorthand for the |every character|. + \end{key} - 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/character \meta{number}} + Specify additional effects for the character \meta{number}. + \end{stylekey} -\begin{stylekey}{/pgf/decoration/text effects/letter \meta{number}} + \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} - Specify the effects for letter \meta{number} in \emph{every} word. - -\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. - + 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. - + 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. - + 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. - + 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. - + 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. - + 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). - + 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 appplied 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}} + 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. - Shorthand for the |every character width| style. + \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}[] -\begin{tikzpicture}[decoration={text effects along path, +\begin{tikzpicture}[decoration={text effects along path, text={text effects along path!}, text align=center, text effects/.cd, - character count=\i, + character count=\i, characters={xslant=0.5, text along path, name=c-\i}}] \path [decorate] (0,0) -- (3,2); -\path [decorate, +\path [decorate, text effects={character widths={inner xsep=0pt, xslant=0}}] (0,1) -- (3,3); \end{tikzpicture} \end{codeexample} -\end{key} + \end{key} - It is possible to parametrize 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}. - + 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}[] \begin{tikzpicture}[decoration={text effects along path, - text={text effects along path!}, + text={text effects along path!}, text effects/.cd, - path from text, + 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} + \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{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}[] \begin{tikzpicture}[decoration={text effects along path, - text={text effects along path!}, + text={text effects along path!}, text effects/.cd, - character count=\i, character total=\n, + 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] + +\path [decorate] (0,0) .. controls ++(1,0) and ++(-1,0) .. (3,2); \end{tikzpicture} \end{codeexample} + \end{key} -\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{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}[] \begin{tikzpicture}[decoration={text effects along path, - text={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} -\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{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}[] \begin{tikzpicture}[decoration={text effects along path, - text={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} - + % + \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}} + \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} - This key enables \meta{effects} to be applied to every character - in the decoration text that is specified in \meta{characters}. + 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}[] -\begin{tikzpicture}[decoration={text effects along path, +\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, @@ -1975,127 +1860,112 @@ reasons, using the |markings| library is usually preferable. \path [decorate] (0,0); \end{tikzpicture} \end{codeexample} + \end{key} -\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{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}[] \begin{tikzpicture}[decoration={text effects along path, - text={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} -\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{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}[] \begin{tikzpicture}[decoration={text effects along path, - text={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} -\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{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}[] \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] + +\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}] + 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)} + % + \end{key} - This key will make the decoration scale the text - so that the entire path is used by the decoration. - + \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}[] \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] + +\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}] + 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} + % + \end{key} - 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{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}[] \begin{tikzpicture}[decoration={text effects along path, - text={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 - still be in the normal order, so any parametrized 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: - + 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}[] - \begin{tikzpicture}[decoration={text effects along path, - text={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, @@ -2106,65 +1976,60 @@ reasons, using the |markings| library is usually preferable. 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'. + % + \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}[] \begin{tikzpicture}[decoration={text effects along path, - text={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} -\end{key} - - The order in which the |reverse text| and |group letters| keys - are applied is important: - + The order in which the |reverse text| and |group letters| keys are applied + is important: + % \begin{codeexample}[] \begin{tikzpicture}[decoration={text effects along path, - text={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 behaviour of the |repeat text| key is undefined, but - typically it will be ignored. - + \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 behaviour of + the |repeat text| key is undefined, but typically it will be ignored. + % \begin{codeexample}[] \begin{tikzpicture}[decoration={text effects along path, text={text effects along path!\ }, @@ -2172,82 +2037,73 @@ reasons, using the |markings| library is usually preferable. 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] + +\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} + \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{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}[] \def\mycommand#1{#1$_\n$} \begin{tikzpicture}[decoration={text effects along path, - text={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}} + \end{key} - 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{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}[] \begin{tikzpicture}[decoration={text effects along path, - text={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{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. + 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$. + 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}[] \begin{tikzpicture}[decoration=Koch curve type 1] \draw decorate{ (0,0) -- (3,0) }; @@ -2255,12 +2111,13 @@ reasons, using the |markings| library is usually preferable. \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$. + This decoration replaces a straight line by a ``rectangular sine''. Its + Hausdorff dimension is $3/2$. + % \begin{codeexample}[] \begin{tikzpicture}[decoration=Koch curve type 2] \draw decorate{ (0,0) -- (3,0) }; @@ -2268,11 +2125,13 @@ reasons, using the |markings| library is usually preferable. \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$. + 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}[] \begin{tikzpicture}[decoration=Koch snowflake] \draw decorate{ (0,0) -- (3,0) }; @@ -2281,12 +2140,13 @@ reasons, using the |markings| library is usually preferable. \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$. + 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}[] \begin{tikzpicture}[decoration=Cantor set,very thick] \draw decorate{ (0,0) -- (3,0) }; @@ -2295,10 +2155,5 @@ reasons, using the |markings| library is usually preferable. \draw decorate{ decorate{ decorate{ decorate{ (0,-1.5) -- (3,-1.5) }}}}; \end{tikzpicture} \end{codeexample} + % \end{decoration} - - - - - -\endinput |