summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-decorations.tex
diff options
context:
space:
mode:
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.tex2281
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