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.tex843
1 files changed, 751 insertions, 92 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 bb0e6cadad9..4496bc06f4d 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
@@ -1,4 +1,4 @@
-% Copyright 2008 by Mark Wibrow
+% Copyright 2013 by Mark Wibrow and Till Tantau
%
% This file may be distributed and/or modified
%
@@ -40,27 +40,27 @@ stored in \TeX\ dimension registers while others are stored in macros.
value of |2.5pt| means that deforming decorations should deform a
path by up to 2.5pt away from the original path.
- This key set 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.
- The key set 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.
- This key set 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 key set the \TeX-macro (!) |\pgfmetadecorationsegmentlength|.
+ This key sets the \TeX-macro (!) |\pgfmetadecorationsegmentlength|.
\end{key}
\begin{key}{/pgf/decoration/angle=\meta{degree} (initially 45)}
@@ -68,7 +68,7 @@ stored in \TeX\ dimension registers while others are stored in macros.
instance, a |wave| decoration consists of arcs and the opening angle
of these arcs is given by the |angle|.
- This key set the \TeX-macro |\pgfdecorationsegmentangle|.
+ This key sets the \TeX-macro |\pgfdecorationsegmentangle|.
\end{key}
\begin{key}{/pgf/decoration/aspect=\meta{factor} (initially 0.5)}
@@ -76,7 +76,7 @@ stored in \TeX\ dimension registers while others are stored in macros.
for a |brace| decoration the aspect ratio determines where the brace
point will be.
- This key set the \TeX-macro |\pgfdecorationsegmentaspect|.
+ This key sets the \TeX-macro |\pgfdecorationsegmentaspect|.
\end{key}
\begin{key}{/pgf/decoration/start radius=\meta{dimension} (initially 2.5pt)}
@@ -86,7 +86,7 @@ stored in \TeX\ dimension registers while others are stored in macros.
\end{key}
\begin{key}{/pgf/decoration/end radius=\meta{dimension} (initially 2.5pt)}
- For some decorations there is a natural 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.
\end{key}
@@ -111,13 +111,13 @@ stored in \TeX\ dimension registers while others are stored in macros.
\subsection{Path Morphing Decorations}
\begin{pgflibrary}{decorations.pathmorphing}
- A \emph{path morphing decorations} ``morphs'' or ``deforms'' the
+ 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 and a line and path deforming decorations do not
+ 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 subpath and one open
+ 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}
@@ -138,7 +138,7 @@ the paths.
\begin{codeexample}[]
\begin{tikzpicture}[decoration=lineto]
\draw [help lines] grid (3,2);
- \draw [decorate,fill=examplefill]
+ \draw [decorate,fill=yellow!80!black]
(0,0) -- (3,1) arc (0:180:1.5 and 1) -- cycle;
\end{tikzpicture}
\end{codeexample}
@@ -152,18 +152,18 @@ the paths.
the decoration:
\begin{itemize}
\item |amplitude|
- determines how much the zigzag lines raises above and falls below
+ 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|
+ \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);
- \draw [decorate,fill=examplefill]
+ \draw [decorate,fill=yellow!80!black]
(0,0) -- (3,1) arc (0:180:1.5 and 1) -- cycle;
\end{tikzpicture}
\end{codeexample}
@@ -186,7 +186,7 @@ the paths.
\begin{tikzpicture}
[decoration={random steps,segment length=2mm}]
\draw [help lines] grid (3,2);
- \draw [decorate,fill=examplefill]
+ \draw [decorate,fill=yellow!80!black]
(0,0) -- (3,1) arc (0:180:1.5 and 1) -- cycle;
\end{tikzpicture}
\end{codeexample}
@@ -205,7 +205,7 @@ the paths.
\begin{codeexample}[]
\begin{tikzpicture}[decoration=saw]
\draw [help lines] grid (3,2);
- \draw [decorate,fill=examplefill]
+ \draw [decorate,fill=yellow!80!black]
(0,0) -- (3,1) arc (0:180:1.5 and 1) -- cycle;
\end{tikzpicture}
\end{codeexample}
@@ -217,7 +217,7 @@ the paths.
influence the decoration:
\begin{itemize}
\item |amplitude|
- determines how much the zigzag lines raises above and falls below
+ 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.
@@ -225,7 +225,7 @@ the paths.
\begin{codeexample}[]
\begin{tikzpicture}[decoration=zigzag]
\draw [help lines] grid (3,2);
- \draw [decorate,fill=examplefill]
+ \draw [decorate,fill=yellow!80!black]
(0,0) -- (3,1) arc (0:180:1.5 and 1) -- cycle;
\end{tikzpicture}
\end{codeexample}
@@ -237,13 +237,13 @@ the paths.
\begin{decoration}{bent}
This decoration adds a slightly bent line from the start to the
- target. The amplitude of the bent is given |amplitude|
+ 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 bent.
+ determines the amplitude of the bend.
\item |aspect|
- determines how tight the bent is. A good value is around |0.3|.
+ 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.
@@ -255,7 +255,7 @@ the paths.
\end{codeexample}
\begin{codeexample}[]
\begin{tikzpicture}[decoration={bent,aspect=.3}]
- \draw [decorate,fill=examplefill] (0,0) rectangle (3.5,2);
+ \draw [decorate,fill=yellow!80!black] (0,0) rectangle (3.5,2);
\node[circle,draw] (A) at (.5,.5) {A};
\node[circle,draw] (B) at (3,1.5) {B};
\draw[->,decorate] (A) -- (B);
@@ -277,7 +277,7 @@ the paths.
\begin{codeexample}[]
\begin{tikzpicture}[decoration=bumps]
\draw [help lines] grid (3,2);
- \draw [decorate,fill=examplefill]
+ \draw [decorate,fill=yellow!80!black]
(0,0) -- (3,1) arc (0:180:1.5 and 1) -- cycle;
\end{tikzpicture}
\end{codeexample}
@@ -307,7 +307,7 @@ the paths.
\begin{codeexample}[]
\begin{tikzpicture}[decoration=coil]
\draw [help lines] grid (3,2);
- \draw [decorate,fill=examplefill]
+ \draw [decorate,fill=yellow!80!black]
(0,0) -- (3,1) arc (0:180:1.5 and 1) -- cycle;
\end{tikzpicture}
\end{codeexample}
@@ -315,7 +315,7 @@ the paths.
\begin{tikzpicture}
[decoration={coil,aspect=0.3,segment length=3mm,amplitude=3mm}]
\draw [help lines] grid (3,2);
- \draw [decorate,fill=examplefill]
+ \draw [decorate,fill=yellow!80!black]
(0,0) -- (3,1) arc (0:180:1.5 and 1) -- cycle;
\end{tikzpicture}
\end{codeexample}
@@ -338,7 +338,7 @@ the paths.
\begin{codeexample}[]
\begin{tikzpicture}[decoration=curveto]
\draw [help lines] grid (3,2);
- \draw [decorate,fill=examplefill]
+ \draw [decorate,fill=yellow!80!black]
(0,0) -- (3,1) arc (0:180:1.5 and 1) -- cycle;
\end{tikzpicture}
\end{codeexample}
@@ -355,12 +355,12 @@ the paths.
\item |amplitude|
determines the sine wave's amplitude.
\item |segment length|
- determines the sine wave's wave length.
+ determines the sine wave's wavelength.
\end{itemize}
\begin{codeexample}[]
\begin{tikzpicture}[decoration=snake]
\draw [help lines] grid (3,2);
- \draw [decorate,fill=examplefill]
+ \draw [decorate,fill=yellow!80!black]
(0,0) -- (3,1) arc (0:180:1.5 and 1) -- cycle;
\end{tikzpicture}
\end{codeexample}
@@ -382,9 +382,9 @@ the paths.
\end{pgflibrary}
\begin{decoration}{border}
- This decoration adds straight lines the path that are at a specific
+ 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'' or an area. The following
+ lines to indicate the ``border'' of an area. The following
parameters influence the decoration:
\begin{itemize}
\item |segment length|
@@ -499,11 +499,11 @@ the paths.
\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,
@@ -533,10 +533,10 @@ the paths.
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.
+ 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`\})}
@@ -544,7 +544,7 @@ the paths.
\end{key}
\begin{key}{/pgf/decoration/curveto code=\meta{code} (initially \char`\{\char`\})}
- Set the code to be executed for every curveto input segment.
+ Set the code to be executed for every curveto input segment.
\end{key}
\begin{key}{/pgf/decoration/closepath code=\meta{code} (initially \char`\{\char`\})}
@@ -563,19 +563,19 @@ In \tikzname, you can use the following macros
inside a \tikzname{} coordinate.
\begin{command}{\tikzinputsegmentfirst}
- The first point on the current input segment path.
+ The first point on the current input segment path.
\end{command}
\begin{command}{\tikzinputsegmentlast}
- The last point on the current input segment path.
+ The last point on the current input segment path.
\end{command}
\begin{command}{\tikzinputsegmentsupporta}
- The first support on the curveto input segment path.
+ The first support on the curveto input segment path.
\end{command}
\begin{command}{\tikzinputsegmentsupportb}
- The second support on the curveto input segment path.
+ The second support on the curveto input segment path.
\end{command}
{\tikzexternaldisable
@@ -585,7 +585,7 @@ inside a \tikzname{} coordinate.
decoration={
show path construction,
curveto code={
- \draw [blue, dashed]
+ \draw [blue, dashed]
(\tikzinputsegmentfirst) -- (\tikzinputsegmentsupporta)
node [at end, cross out, draw, solid, red, inner sep=2pt]{};
\draw [blue, dashed]
@@ -693,8 +693,8 @@ a path. We start with the most general and most useful of these libraries.
\end{codeexample}
The |mark| decoration option is used to specify a marking. It comes
- in two version:
- \begin{key}{/pgf/decoration/mark=|at position|
+ 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
@@ -704,10 +704,10 @@ a path. We start with the most general and most useful of these libraries.
\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 removed from the start.
+ 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 removed from the end of
+ |-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
@@ -722,7 +722,7 @@ a path. We start with the most general and most useful of these libraries.
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 contains all sorts of
+ 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
@@ -767,8 +767,8 @@ a path. We start with the most general and most useful of these libraries.
\end{tikzpicture}
\end{codeexample}
- When the \meta{code} is begin executed, two special keys will have
- been setup, whose value may be of interest:
+ 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
@@ -825,6 +825,7 @@ a path. We start with the most general and most useful of these libraries.
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 {
@@ -869,9 +870,9 @@ a path. We start with the most general and most useful of these libraries.
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 nonempty \meta{node name} while the
+ 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 node named
+ 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
@@ -914,7 +915,7 @@ a path. We start with the most general and most useful of these libraries.
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 execute. (They are only defined in this code):
+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,
@@ -1001,7 +1002,7 @@ a |mark| option is execute. (They are only defined in this code):
\end{codeexample}
\end{key}
\begin{key}{/pgf/decoration/foot angle (initially 10)}
- Footprints are rotate by this much.
+ Footprints are rotated by this much.
\begin{codeexample}[]
\begin{tikzpicture}[decoration={footprints,foot angle=60}]
\fill [decorate] (0,0) -- (3,0);
@@ -1086,7 +1087,7 @@ reasons, using the |markings| library is usually preferable.
\item |segment length|
determines the distance between consecutive triangles.
\item |shape height|
- determines height of the triangle side that is orthogonal
+ determines the height of the triangle side that is orthogonal
to the path.
\item |shape width|
determines the width of the triangle.
@@ -1094,7 +1095,7 @@ reasons, using the |markings| library is usually preferable.
\begin{codeexample}[]
\begin{tikzpicture}[decoration=triangles]
\draw [help lines] grid (3,2);
- \draw [decorate,fill=examplefill] (0,0) -- (3,1) arc (0:180:1.5 and 1);
+ \draw [decorate,fill=yellow!80!black] (0,0) -- (3,1) arc (0:180:1.5 and 1);
\end{tikzpicture}
\end{codeexample}
\end{decoration}
@@ -1103,14 +1104,14 @@ reasons, using the |markings| library is usually preferable.
\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 defined using the |\pgfdeclareshape| command (that is,
+ 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 of the size of the text box (like the
+ 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.
@@ -1137,13 +1138,13 @@ reasons, using the |markings| library is usually preferable.
|anchor| decoration option:
\begin{key}{/pgf/decoration/anchor=\meta{anchor} (initially center)}
- The anchor used to position the shapes backgrounds.
+ The anchor used to position the shape backgrounds.
\end{key}
A shape background path is added at the start point of the path and,
if the distance between the shapes is appropriate, at the end point
of the path.
-
+
\begin{codeexample}[]
\begin{tikzpicture}[decoration={
shape backgrounds,shape=regular polygon,shape size=4mm}]
@@ -1190,10 +1191,10 @@ reasons, using the |markings| library is usually preferable.
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
+ 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},
@@ -1202,7 +1203,7 @@ reasons, using the |markings| library is usually preferable.
\draw [help lines] grid (3,2);
\draw [paint=red, decoration={shape sep=.5cm}]
(0,2) -- (3,2);
- \draw [paint=green, decoration={shape sep={1cm, between center}}]
+ \draw [paint=green, decoration={shape sep={1cm, between centers}}]
(0,1) -- (3,1);
\draw [paint=blue, decoration={shape sep={1cm, between borders}}]
(0,0) -- (3,0);
@@ -1245,7 +1246,7 @@ reasons, using the |markings| library is usually preferable.
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|
- appropriately.
+ accordingly.
\begin{codeexample}[]
\tikzset{
@@ -1263,11 +1264,11 @@ reasons, using the |markings| library is usually preferable.
\end{codeexample}
\end{key}%
- It is possible to scale the width and height of the shapes across the
+ It is possible to scale the width and height of the shapes along the
length of the decorations path. The shapes are scaled between the starting
size and the ending size. The following keys customize the way the
decoration shapes are scaled:
-
+
\begin{key}{/pgf/decoration/shape scaled=\meta{boolean} (initially false)}
\begin{codeexample}[]
\tikzset{
@@ -1297,11 +1298,11 @@ reasons, using the |markings| library is usually preferable.
\end{key}%
\begin{stylekey}{/pgf/decoration/shape start size=\meta{length}}
- Set both the start height and start width simultaneously.
+ 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
+ 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.
@@ -1351,9 +1352,9 @@ reasons, using the |markings| library is usually preferable.
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 in
- the following example no line is shown.
-
+ 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,
@@ -1377,36 +1378,36 @@ reasons, using the |markings| library is usually preferable.
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\textdegree{}
+ 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
+ \item
It is only possible to typeset text in math mode under considerable
- restrictions. Math mode is entered and exited using any character
+ 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
+ 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
+ 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 case by case basis by individually kerning the offending
+ 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)}
- Set the text to typeset along the curve.
+ 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
+ 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).
+ regarding the category codes of delimiters --- see below).
{\catcode`\|12
\begin{codeexample}[]
@@ -1433,7 +1434,7 @@ 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|.
@@ -1444,15 +1445,15 @@ reasons, using the |markings| library is usually preferable.
\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
+ 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
+ are added to any existing ones, you should avoid using |+| as
a delimiter.
\begin{codeexample}[]
@@ -1524,12 +1525,12 @@ reasons, using the |markings| library is usually preferable.
\end{stylekey}
\begin{key}{/pgf/decoration/text align/left indent=\meta{length} (initially 0pt)}
- Specify a distance which the automaton should move along
+ Specifies a distance which the automaton should move along
before it starts typesetting the text.
\end{key}
\begin{key}{/pgf/decoration/text align/right indent=\meta{length} (initially 0pt)}
- Specify a distance before the end of the path, where
+ Specifies a distance before the end of the path, where
the automaton should stop typesetting the text.
\end{key}
@@ -1575,6 +1576,664 @@ reasons, using the |markings| library is usually preferable.
+\begin{decoration}{text effects along path}
+
+ This decoration is similar to the |text along path| decoration
+ except that each character is inserted into the picture
+ as a \tikzname\ node, and node options (such as |text|, |scale| and |opacity|)
+ can be used to create `text effects'.
+
+\begin{codeexample}[]
+\bfseries\large
+\begin{tikzpicture}[decoration={text effects along path,
+ text={text effects along path!}, text align=center,
+ text effects/.cd,
+ character count=\i, character total=\n,
+ characters={evaluate={\c=\i/\n*100;}, text along path, text=red!\c!orange},
+ character widths={text along path, xslant=0, yscale=1}}]
+
+\path [postaction={decorate}, preaction={decorate,
+ text effects={characters/.append={yscale=-1.5, opacity=0.5,
+ text=gray, xslant=(\i/\n-0.5)*3}}}]
+ (0,0) .. controls ++(2,1) and ++(-2,-1) .. (3,4);
+\end{tikzpicture}
+\end{codeexample}
+
+
+ There are some important differences between this decoration and the
+ |text along path| decoration:
+
+ \begin{itemize}
+ \item
+ formatting (e.g., font and color)
+ cannot be specified in the decoration text. They can only be specified
+ using the keys described below.
+ \item
+ as a consequence of using the \tikzname\ node options, this
+ decoration is only available in \tikzname.
+ \item
+ due to the number of computations involved, this is
+ quite a slow decoration.
+
+ \end{itemize}
+
+ The following keys are shared with the |text along path|
+ decoration:
+
+\begin{key}{/pgf/decoration/text=\marg{text}}
+
+
+ Set the text this decoration will use. Braces can be
+ used to group multiple characters together,
+ or commands that should not be expanded until they are 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{codeexample}[]
+\begin{tikzpicture}[decoration={text effects along path,
+ text={000-001-010-011-100-101-110-111},
+ text effects/.cd,
+ path from text,
+ word separator=-,
+ every letter/.style={shape=rectangle, fill=blue!20, draw=blue!40}}]
+
+\path [decorate] (0,0);
+\end{tikzpicture}
+\end{codeexample}
+
+ In addition, it is possible to replace characters
+ with \tikzname\ code:
+
+\begin{codeexample}[]
+\begin{tikzpicture}[decoration={text effects along path,
+ text={000-001-010-011-100-101-110-111}, text align=center,
+ text effects/.cd,
+ word separator=-,
+ replace characters=0 with {\fill [purple] circle [radius=2pt]; },
+ replace characters=1 with {\fill [orange] circle [radius=2pt]; },
+ replace characters=- with {\path circle [radius=2pt]; },
+ every letter/.style={shape=rectangle, fill=blue!20, draw=blue!40}}]
+
+\path [decorate] (0,0) .. controls ++(2,0) and ++(-2,0) .. (3,4);
+\end{tikzpicture}
+\end{codeexample}
+
+
+ There are many keys and styles that can be used to add effects
+ to the decoration text.
+ Many of these keys have the parent path |/pgf/decoration/text effects/|,
+ but for convenience, these keys can be accessed using the following
+ key:
+
+\begin{key}{/tikz/text effects=\marg{options}}
+
+ Execute every option in \marg{options} with the
+ key path for each option temporarily set to |/pgf/decoration/text effects/|.
+
+\end{key}
+
+
+ The following keys can be used to customise the
+ appearance of text in the |text effects along path|
+ decoration.
+
+
+
+
+\begin{stylekey}{/pgf/decoration/text effects/every character}
+
+ Set the effects that will be applied to
+ every character in the decoration text. The effects
+ will typically be \tikzname\ node options.
+ Initially, this style is empty so the decoration simply positions
+ nodes at the appropriate position along the path. In order to
+ make the text `follow the path' like the |text along path| decoration
+ the following key can be added to the |every character| style.
+
+\end{stylekey}
+
+
+\begin{stylekey}{/pgf/decoration/text effects/text along path}
+
+ This style automatically sets the \tikzname\ keys
+ |transform shape| (to make the character slope with the path),
+ |anchor=baseline| (to make the baseline of the characters `sit' on
+ the path) and |inner xsep=0pt| (to horizontally fit each node to the character
+ it contains, reducing the spacing between characters).
+
+\begin{codeexample}[]
+\begin{tikzpicture}[decoration={text effects along path,
+ text={text effects along path!}}]
+
+\path [draw=red, dotted, postaction={decorate}]
+ (0,0) .. controls ++(1,0) and ++(-1,0) .. (3,2);
+\path [draw=blue, dotted, yshift=1cm, postaction={decorate},
+ text effects={text along path}]
+ (0,0) .. controls ++(1,0) and ++(-1,0) .. (3,2);
+\end{tikzpicture}
+\end{codeexample}
+\end{stylekey}
+
+
+\begin{key}{/pgf/decoration/text effects/characters=\marg{effects}}
+
+ Shorthand for the |every character|.
+
+\end{key}
+
+\begin{stylekey}{/pgf/decoration/text effects/character \meta{number}}
+
+ Specify additional effects for the character \meta{number}.
+
+\end{stylekey}
+
+
+\begin{stylekey}{/pgf/decoration/text effects/every letter}
+
+ Specify additional effects for every letter (i.e., every character
+ that isn't the word separator) in the decoration text.
+
+\end{stylekey}
+
+\begin{stylekey}{/pgf/decoration/text effects/letter \meta{number}}
+
+ Specify the effects for letter \meta{number} in \emph{every} word.
+
+\end{stylekey}
+
+
+\begin{stylekey}{/pgf/decoration/text effects/every first letter}
+
+ Specify additional effects for the first letter in \emph{every} word.
+
+\end{stylekey}
+
+
+\begin{stylekey}{/pgf/decoration/text effects/every last letter}
+
+ Specify additional effects for the last letter in \emph{every} word.
+
+\end{stylekey}
+
+
+\begin{stylekey}{/pgf/decoration/text effects/every word}
+
+ Specify additional effects for every word in the decoration text.
+
+\end{stylekey}
+
+
+
+\begin{stylekey}{/pgf/decoration/text effects/word \meta{number}}
+
+ Specify additional effects for word \meta{number} in the decoration text.
+
+\end{stylekey}
+
+
+
+\begin{stylekey}{/pgf/decoration/text effects/word \meta{m} letter \meta{n}}
+
+ Specify additional effects for letter \meta{n} in word \meta{m} in the decoration text.
+
+\end{stylekey}
+
+
+
+\begin{stylekey}{/pgf/decoration/text effects/every word separator}
+
+ Specify additional effects for every character that is a word separator.
+
+\end{stylekey}
+
+
+
+\begin{key}{/pgf/decoration/text effects/word separator=\meta{character} (initially space)}
+
+ Specify the character that is to be used as the word separator.
+ This \emph{must} be a single character such as |a| or |-| or
+ the special value |space| (which should be used to indicate that
+ spaces should be used as the separator).
+
+\end{key}
+
+ By default, the width for each character is calculated according
+ to the bounding box of the node in which it is contained.
+ However, if the node is rotated or slanted, or has a substantial
+ |inner sep|, this bounding box
+ will be quite big. The following key enables different effects
+ to be applied to the node that is used to calculate the
+ width.
+
+
+
+
+\begin{stylekey}{/pgf/decoration/text effects/every character width}
+
+ This style is 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}}
+
+ Shorthand for the |every character width| style.
+
+\begin{codeexample}[]
+\begin{tikzpicture}[decoration={text effects along path,
+ text={text effects along path!}, text align=center,
+ text effects/.cd,
+ character count=\i,
+ characters={xslant=0.5, text along path, name=c-\i}}]
+
+\path [decorate] (0,0) -- (3,2);
+\path [decorate,
+ text effects={character widths={inner xsep=0pt, xslant=0}}]
+ (0,1) -- (3,3);
+\end{tikzpicture}
+\end{codeexample}
+\end{key}
+
+ It is possible to 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}.
+
+\begin{codeexample}[]
+\begin{tikzpicture}[decoration={text effects along path,
+ text={text effects along path!},
+ text effects/.cd,
+ path from text,
+ character count=\i, every word separator/.style={fill=red!30},
+ characters={text along path, shape=circle, fill=gray!50}}]
+
+\path [decorate, text effects={characters/.append={label=above:\footnotesize\i}}] (0,0);
+\end{tikzpicture}
+\end{codeexample}
+
+\end{key}
+
+\begin{key}{/pgf/decoration/text effects/character total=\meta{macro}}
+ Store the total number of the characters in the decoration text
+ in \meta{macro}.
+ This key can be used with the |character count| key to produce
+ some quite pleasing effects:
+
+\begin{codeexample}[]
+\begin{tikzpicture}[decoration={text effects along path,
+ text={text effects along path!},
+ text effects/.cd,
+ character count=\i, character total=\n,
+ characters={text along path, evaluate={\c=\i/\n*100;},
+ text=orange!\c!blue, scale=\i/\n+0.5}}]
+
+\path [decorate]
+ (0,0) .. controls ++(1,0) and ++(-1,0) .. (3,2);
+\end{tikzpicture}
+\end{codeexample}
+
+\end{key}
+
+\begin{key}{/pgf/decoration/text effects/letter count=\meta{macro}}
+
+ Store the number of letter being typeset (i.e., the position of the character
+ in the word) in \meta{macro}. Numbering starts at |1| and
+ the character acting as a word separator is numbered |0|.
+
+\begin{codeexample}[]
+\begin{tikzpicture}[decoration={text effects along path,
+ text={text effects along path!},
+ text effects/.cd,
+ path from text, letter count=\i, every word separator/.style={fill=red!30},
+ characters={text along path, shape=circle, fill=gray!50}}]
+
+\path [decorate, text effects={characters/.append={label=above:\footnotesize\i}}] (0,0);
+\end{tikzpicture}
+\end{codeexample}
+
+\end{key}
+
+\begin{key}{/pgf/decoration/text/effetcs/letter total=\meta{macro}}
+
+ Store the number of letters in the current word in \meta{macro}.
+ When the character is the word separator, this value is |0|.
+
+\end{key}
+
+\begin{key}{/pgf/decoration/text effects/word count=\meta{macro}}
+ Store the number of words in the decoration text in \meta{macro}.
+ Numbering starts at |1|.
+ When the character is the word separator, \meta{macro}
+ takes the number of the previous word. If the decoration text
+ starts with a word separator \meta{macro} will be |0|.
+
+\begin{codeexample}[]
+\begin{tikzpicture}[decoration={text effects along path,
+ text={text effects along path!},
+ text effects/.cd,
+ path from text, word count=\i, every word separator/.style={fill=red!30},
+ characters={text along path, shape=circle, fill=gray!50}}]
+
+ \path [decorate, text effects={characters/.append={label=above:\footnotesize\i}}] (0,0);
+\end{tikzpicture}
+\end{codeexample}
+\end{key}
+
+\begin{key}{/pgf/decoration/text effects/word total=\meta{macro}}
+
+ Store the total number of words in the decoration text in \meta{macro}.
+
+\end{key}
+
+
+ It is also possible to apply effects to specific
+ characters such as coloring every instance of the
+ character |a|,
+ or changing the font of every |T| in the decoration text:
+
+\begin{key}{/pgf/decoration/text effects/style characters=\marg{characters} with \marg{effects}}
+
+ This key enables \meta{effects} to be applied to every character
+ in the decoration text that is specified in \meta{characters}.
+
+\begin{codeexample}[]
+\begin{tikzpicture}[decoration={text effects along path,
+ text={Falsches {\"U}ben von Xylophonmusik qu{\"a}lt jeden gr{\"o}{\ss}eren Zwerg},
+ text effects/.cd,
+ path from text,
+ style characters=aeiou{\"U}{\"a}{\"o} with {text=blue},
+ characters={text along path}}]
+
+\path [decorate] (0,0);
+\end{tikzpicture}
+\end{codeexample}
+
+\end{key}
+
+\begin{key}{/pgf/decoration/text effects/path from text=\opt{\marg{true or false}} (default true)}
+ When this key is set to |true| and the decorated path
+ consists only of a single point, the decoration will calculate
+ the width of the decoration text using all the specified parameters
+ as if the decorated path was actually a straight line
+ starting from the given point. This `virtual'
+ straight line is then decorated with the text.
+
+\begin{codeexample}[]
+\begin{tikzpicture}[decoration={text effects along path,
+ text={text effects along path!},
+ text effects/.cd,
+ path from text,
+ character count=\i, character total=\n,
+ characters={text along path, scale=\i/\n+0.5}}]
+
+\path [decorate] (0,0);
+\end{tikzpicture}
+\end{codeexample}
+
+\end{key}
+
+
+
+\begin{key}{/pgf/decoration/text effects/path from text angle=\meta{angle}}
+
+ When used in conjunction with the |path from text| key,
+ the straight line that is used as the decorated path
+ is rotated by \meta{angle} around the starting point.
+
+\begin{codeexample}[]
+\begin{tikzpicture}[decoration={text effects along path,
+ text={text effects along path!},
+ text effects/.cd,
+ path from text, path from text angle=60,
+ character count=\i, character total=\n,
+ characters={text along path, scale=\i/\n+0.5}}]
+
+\path [decorate] (0,0);
+\end{tikzpicture}
+\end{codeexample}
+
+\end{key}
+
+
+\begin{key}{/pgf/decoration/text effects/fit text to path=\opt{\meta{true or false}} (default true)}
+
+ This key will make the decoration increase the space between
+ characters so that the entire path is used by the decoration.
+
+\begin{codeexample}[]
+\begin{tikzpicture}[decoration={text effects along path,
+ text={text effects along path!},
+ text effects/every character/.style={text along path}}]
+
+\path [draw=gray, postaction={decorate}, rotate=90]
+ (0,0) .. controls ++(2,0) and ++(-1,0) .. (5,-1);
+\path [draw=gray, postaction={decorate}, rotate=90, yshift=-1cm,
+ text effects={fit text to path}]
+ (0,0) .. controls ++(2,0) and ++(-1,0) .. (5,-1);
+\end{tikzpicture}
+\end{codeexample}
+\end{key}
+
+
+\begin{key}{/pgf/decoration/text effects/scale text to path=\opt{\meta{true or false}} (default true)}
+
+ This key will make the decoration scale the text
+ so that the entire path is used by the decoration.
+
+\begin{codeexample}[]
+\begin{tikzpicture}[decoration={text effects along path,
+ text={text effects along path!},
+ text effects/every character/.style={text along path}}]
+
+\path [draw=gray, postaction={decorate}, rotate=90]
+ (0,0) .. controls ++(2,0) and ++(-1,0) .. (5,-1);
+\path [draw=gray, postaction={decorate}, rotate=90, yshift=-1cm,
+ text effects={scale text to path}]
+ (0,0) .. controls ++(2,0) and ++(-1,0) .. (5,-1);
+\end{tikzpicture}
+\end{codeexample}
+\end{key}
+
+
+\begin{key}{/pgf/decoration/text effects/reverse text}
+
+ Reverse the order of the characters in the decoration text.
+ This may be useful if using `right-to-left` languages.
+ Unfortunately, any
+ leading `soft' spaces in the original text will be lost.
+
+\begin{codeexample}[]
+\begin{tikzpicture}[decoration={text effects along path,
+ text={text effects along path!},
+ text effects/.cd,
+ path from text, path from text angle=60,
+ reverse text,
+ character count=\i, character total=\n,
+ characters={text along path, scale=\i/\n+0.5}}]
+
+\path [decorate] (0,0) .. controls ++(1,0) and ++(-1,0) .. (3,2);
+\end{tikzpicture}
+\end{codeexample}
+
+ It is important to note that the |reverse text| key reverses the
+ text \emph{before} doing anything else. This means that the
+ numbering of characters, letters and words will still
+ 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:
+
+\begin{codeexample}[]
+
+\begin{tikzpicture}[decoration={text effects along path,
+ text={text effects along path!},
+ text effects/.cd,
+ path from text, path from text angle=60,
+ character count=\i, character total=\n,
+ characters={text along path, scale=\i/\n+0.5}}]
+
+\path [decorate, text effects={reverse text}] (0,0);
+\path [blue, decorate, decoration={reverse path},
+ text effects={characters/.append={scale=-1}}] (1,0);
+\end{tikzpicture}
+\end{codeexample}
+\end{key}
+
+\begin{key}{/pgf/decoration/text effects/group letters}
+
+ Group sequences of letters together so they are treated
+ as a single `character'.
+
+\begin{codeexample}[]
+\begin{tikzpicture}[decoration={text effects along path,
+ text={text effects along path!},
+ text effects/.cd,
+ path from text, path from text angle=60,
+ every word separator/.style={fill=none},
+ character count=\i, character total=\n,
+ characters={text along path, fill=gray!50, scale=\i/\n+0.5}}]
+
+\path [decorate] (0,0);
+\path [decorate, text effects={group letters,
+ characters/.append={fill=red!20}}]
+ (1,0);
+\end{tikzpicture}
+\end{codeexample}
+
+\end{key}
+
+ The order in which the |reverse text| and |group letters| keys
+ are applied is important:
+
+\begin{codeexample}[]
+\begin{tikzpicture}[decoration={text effects along path,
+ text={text effects along path!},
+ text effects/.cd,
+ path from text, path from text angle=60,
+ every word separator/.style={fill=none},
+ character count=\i, character total=\n,
+ characters={text along path, fill=gray!50, scale=\i/\n+0.5}}]
+
+\path [decorate, text effects={reverse text, group letters}] (0,0);
+\path [decorate, text effects={group letters, reverse text,
+ characters/.append={fill=red!20}}] (1,0);
+\end{tikzpicture}
+\end{codeexample}
+
+\begin{key}{/pgf/decoration/text effects/repeat text=\opt{\meta{times}}}
+
+ Usually, when the decoration runs out of text, it simply stops.
+ This key will make the decoration repeat the decoration text
+ for the specified number of \meta{times}. If no value is given
+ the text will be repeated until the path is finished.
+ There are two points to remember however.
+ Firstly the numbering of characters, letters and words
+ will be restarted each time the text is repeated.
+ Secondly, the options for alignment, scaling or fitting
+ the text to the path, fitting the path to the text,
+ and so on, are computed using the decoration text before the
+ decoration starts. If any of these options are given
+ the 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!\ },
+ text effects/.cd,
+ repeat text,
+ character count=\m, character total=\n,
+ characters={text along path, scale=0.5+\m/\n/2}}]
+
+\path [draw=gray, ultra thin, postaction=decorate]
+ (180:2) \foreach \a in {0,...,12}{ arc (180-\a*90:90-\a*90:1.5-\a/10) };
+\end{tikzpicture}
+\end{codeexample}
+\end{key}
+
+\begin{key}{/pgf/decoration/text effects/character command=\meta{macro}}
+
+ This key specifies a command that is executed when
+ each character is placed in the node. The \meta{macro} should
+ be an ordinary \TeX\ macro which takes one argument. The
+ argument will be a macro which when expanded will
+ contain the current character.
+
+\begin{codeexample}[]
+\def\mycommand#1{#1$_\n$}
+\begin{tikzpicture}[decoration={text effects along path,
+ text={text effects along path!},
+ text effects/.cd,
+ path from text, path from text angle=60, group letters,
+ word count=\n,
+ every word/.style={character command=\mycommand},
+ characters={text along path}}]
+
+\path [decorate] (0,0);
+\end{tikzpicture}
+\end{codeexample}
+\end{key}
+
+
+\begin{key}{/pgf/decoration/text effects/replace characters=\meta{characters} with \marg{code}}
+
+ Replace the node for each character in \meta{characters} with \meta{code}.
+ The \meta{code} can be thought of as describing
+ a little picture or marking which will be
+ used instead of the character node.
+ The origin will be the current point along the
+ decoration path.
+ Any transformations associated with
+ the \meta{characters} (e.g., applied with the |every character|
+ or |every letter| styles) will also be applied to \meta{code}.
+
+\begin{codeexample}[]
+\begin{tikzpicture}[decoration={text effects along path,
+ text={text effects along path!},
+ text effects/.cd,
+ path from text, path from text angle=60,
+ replace characters=e with {\fill [red!20] (0,1mm) circle [radius=1mm];},
+ replace characters=a with {\fill [black!20] (0,1mm) circle [radius=1mm];},
+ character count=\i, character total=\n,
+ characters={text along path, scale=\i/\n+0.5}}]
+
+\path [decorate] (0,0);
+\end{tikzpicture}
+\end{codeexample}
+
+\end{key}
+\end{decoration}
+
+
+
\subsection{Fractal Decorations}
\begin{pgflibrary}{decorations.fractals}
@@ -1613,7 +2272,7 @@ reasons, using the |markings| library is usually preferable.
\begin{decoration}{Koch snowflake}
This decoration replaces a straight line by a ``line with a spike.''
- Koch's snowflake's Hausdorff dimension is $\log 4/\log 3$.
+ 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) };
@@ -1625,7 +2284,7 @@ reasons, using the |markings| library is usually preferable.
\end{decoration}
\begin{decoration}{Cantor set}
- This decoration replaces a straight line by a ``line with a whole in
+ 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}[]