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.tex1053
1 files changed, 731 insertions, 322 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 eeef79c6ee8..bb0e6cadad9 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
@@ -16,11 +16,11 @@
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
+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.
+decorations can be defined.
The decorations are influenced by a number of parameters that can be
set using the |decoration| option. These parameters are
@@ -35,32 +35,32 @@ 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
+ 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 set the \TeX-dimension |\pgfdecorationsegmentamplitude|.
+ This key set 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 set 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.
+ the desired length of such segments.
- This key set the \TeX-dimension |\pgfdecorationsegmentlength|.
+ This key set 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 set 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 set 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 set the \TeX-macro |\pgfdecorationsegmentaspect|.
\end{key}
\begin{key}{/pgf/decoration/start radius=\meta{dimension} (initially 2.5pt)}
@@ -100,7 +100,7 @@ stored in \TeX\ dimension registers while others are stored in macros.
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 segements are approached ``more carefully'' than
+ 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
@@ -118,7 +118,7 @@ stored in \TeX\ dimension registers while others are stored in macros.
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
- subpath.
+ subpath.
\end{pgflibrary}
@@ -146,13 +146,13 @@ the paths.
\begin{decoration}{straight zigzag}
- This (meta-)decoration decorates the path by alternating between
+ 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 zig-zag lines raises above and falls below
+ determines how much the zigzag lines raises above and falls below
a straight line to the target point.
\item |segment length|
determines the length of a complete ``up-down'' cycle.
@@ -213,11 +213,11 @@ the paths.
\begin{decoration}{zigzag}
- This decoration looks like a zig-zag line. The following parameters
+ This decoration looks like a zigzag line. The following parameters
influence the decoration:
\begin{itemize}
\item |amplitude|
- determines how much the zig-zag lines raises above and falls below
+ determines how much the zigzag lines raises above and falls below
a straight line to the target point.
\item |segment length|
determines the length of a complete ``up-down'' cycle.
@@ -238,12 +238,12 @@ 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|
- (an amplitude of zero gives a straight line).
+ (an amplitude of zero gives a straight line).
\begin{itemize}
\item |amplitude|
determines the amplitude of the bent.
\item |aspect|
- determines how tight the bent is. A good value is around |0.3|.
+ determines how tight the bent 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.
@@ -267,7 +267,7 @@ the paths.
\begin{decoration}{bumps}
This decoration replaces the path by little half ellipses. The
- following parameters influence itL
+ following parameters influence it.
\begin{itemize}
\item |amplitude|
determines the height of the half ellipse.
@@ -290,7 +290,7 @@ the paths.
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:
+ coil. The following parameters influence the decoration:
\begin{itemize}
\item |amplitude|
determines how much the coil rises above the path and falls below
@@ -298,11 +298,11 @@ the paths.
\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.
+ 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.''
+ default, means ``look more from the front.''
\end{itemize}
\begin{codeexample}[]
\begin{tikzpicture}[decoration=coil]
@@ -350,7 +350,7 @@ the paths.
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:
+ the snake:
\begin{itemize}
\item |amplitude|
determines the sine wave's amplitude.
@@ -368,7 +368,7 @@ the paths.
-
+
\subsection{Path Replacing Decorations}
\begin{pgflibrary}{decorations.pathreplacing}
@@ -385,14 +385,14 @@ the paths.
This decoration adds straight lines 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
- parameters influence the decoration:
+ 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.
+ determines the angle between the ticks and the line of the path.
\end{itemize}
\begin{codeexample}[]
\begin{tikzpicture}[decoration=border]
@@ -414,7 +414,7 @@ the paths.
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.
+ part'' of the brace will be.
\end{itemize}
\begin{codeexample}[]
\begin{tikzpicture}[decoration=brace]
@@ -445,10 +445,20 @@ the paths.
\end{decoration}
+\begin{decoration}{moveto}
+ This decoration simply jumps to the end of the path using a move-to
+ path operation. It is mainly useful as |pre=moveto| or |post=moveto|
+ decorations.
+
+ This decoration is actually always defined when the decoration
+ module is loaded, but it is documented here for consistency.
+\end{decoration}
+
+
\begin{decoration}{ticks}
This decoration replaces the path by straight lines that are
orthogonal to the path. The following parameters influence the
- decoration:
+ decoration:
\begin{itemize}
\item |segment length|
determines the distance between consecutive ticks.
@@ -467,7 +477,7 @@ the paths.
\begin{decoration}{waves}
This decoration replaces the path by arcs that have a constant
- size. The following parameters influence the decoration:
+ size. The following parameters influence the decoration:
\begin{itemize}
\item |segment length|
determines the distance between consecutive arcs.
@@ -488,13 +498,548 @@ the paths.
-\subsection{Decorations with Shapes}
+\begin{decoration}{show path construction}
+ This decoration allows ``something different'' to be done
+ for each \emph{type} of input segment (i.e., moveto, lineto,
+ curveto or closepath). Typically, each segment will be replaced
+ with another path, but this need not necessarily be the case.
+
+\begin{codeexample}[]
+\begin{tikzpicture}[>=stealth, every node/.style={midway, sloped, font=\tiny},
+ decoration={show path construction,
+ moveto code={
+ \fill [red] (\tikzinputsegmentfirst) circle (2pt)
+ node [fill=none, below] {moveto};},
+ lineto code={
+ \draw [blue,->] (\tikzinputsegmentfirst) -- (\tikzinputsegmentlast)
+ node [above] {lineto};
+ },
+ curveto code={
+ \draw [green!75!black,->] (\tikzinputsegmentfirst) .. controls
+ (\tikzinputsegmentsupporta) and (\tikzinputsegmentsupportb)
+ ..(\tikzinputsegmentlast) node [above] {curveto};
+ },
+ closepath code={
+ \draw [orange,->] (\tikzinputsegmentfirst) -- (\tikzinputsegmentlast)
+ node [above] {closepath};}
+ }]
+ \draw [help lines] grid (3,2);
+ \path [decorate] (0,0) -- (3,1) arc (0:180:1.5 and 1) -- cycle;
+\end{tikzpicture}
+\end{codeexample}
+
+
+ The following keys can be used to specify the code to execute
+ for each type of input segment.
+
+\begin{key}{/pgf/decoration/moveto code=\meta{code} (initially \char`\{\char`\})}
+ Set the code to be executed for every moveto input segment.
+ It is important to remember that the transformations applied
+ by the decoration automaton are turned \emph{off} when \meta{code}
+ is executed.
+\end{key}
+
+\begin{key}{/pgf/decoration/lineto code=\meta{code} (initially \char`\{\char`\})}
+ Set the code to be executed for every lineto input segment.
+\end{key}
+
+\begin{key}{/pgf/decoration/curveto code=\meta{code} (initially \char`\{\char`\})}
+ Set the code to be executed for every curveto input segment.
+\end{key}
+
+\begin{key}{/pgf/decoration/closepath code=\meta{code} (initially \char`\{\char`\})}
+ Set the code to be executed for every closepath input segment.
+\end{key}
+
+Within \meta{code} the first and last
+points on the current input segment can be accessed using
+|\pgfpointdecoratedinputsegmentfirst| and
+|\pgfpointdecoratedinputsegmentlast|. For curves, the
+control (support) points can be accessed using
+|\pgfpointdecoratedinputsegmentsupporta| and
+|\pgfpointdecoratedinputsegmentsupportb|.
+
+In \tikzname, you can use the following macros
+inside a \tikzname{} coordinate.
+
+\begin{command}{\tikzinputsegmentfirst}
+ The first point on the current input segment path.
+\end{command}
+
+\begin{command}{\tikzinputsegmentlast}
+ The last point on the current input segment path.
+\end{command}
+
+\begin{command}{\tikzinputsegmentsupporta}
+ The first support on the curveto input segment path.
+\end{command}
+
+\begin{command}{\tikzinputsegmentsupportb}
+ The second support on the curveto input segment path.
+\end{command}
+
+{\tikzexternaldisable
+\begin{codeexample}[]
+\tikzset{
+ show curve controls/.style={
+ decoration={
+ show path construction,
+ curveto code={
+ \draw [blue, dashed]
+ (\tikzinputsegmentfirst) -- (\tikzinputsegmentsupporta)
+ node [at end, cross out, draw, solid, red, inner sep=2pt]{};
+ \draw [blue, dashed]
+ (\tikzinputsegmentsupportb) -- (\tikzinputsegmentlast)
+ node [at start, cross out, draw, solid, red, inner sep=2pt]{};
+ }
+ },decorate
+ }
+}
+
+\tikzpicture
+ \draw [postaction=show curve controls, thick]
+ (0,2) .. controls (2.5,1.5) and (0.5,0.5) .. (3,0);
+\endtikzpicture
+\end{codeexample}
+}%
+\end{decoration}
+
+
+
+
+\subsection{Marking Decorations}
+
+\subsubsection{Overview}
+
+A \emph{marking on a path} is any kind of graphic that is placed on a
+specific position on a path. Markings are useful in rather diverse
+situations: you can use them to, say, place little ``footsteps'' along
+a path as if someone where walking along the path; to place arrow tips
+on the middle of a path to indicate the ``direction'' in which
+something is flowing; or you can use them to place informative
+information at certain positions of a path.
+
+For historical reasons there are three different libraries for placing
+marks on a path. They differ in what kind of markings can be added to
+a path. We start with the most general and most useful of these libraries.
+
+
+
+\subsection{Arbitrary Markings}
+
+\begin{pgflibrary}{decorations.markings}
+ Markings are arbitrary ``marks'' that can be put on a path. Marks
+ can be arrow tips or nodes or even whole pictures.
+\end{pgflibrary}
+
+\begin{decoration}{markings}
+ A \emph{marking} can be thought of a ``little picture'' or more
+ precisely of ``some scope contents'' that is placed ``on'' a path at
+ a certain position. Suppose the marking should be a simple cross. We
+ can produce this with the following code:
+\begin{codeexample}[code only]
+\draw (-2pt,-2pt) -- (2pt,2pt);
+\draw (2pt,-2pt) -- (-2pt,2pt);
+\end{codeexample}
+ If we use this code as a marking at position |2cm| on a path, then
+ the following happens: \pgfname\ determines the position on the path
+ that is 2cm along the path. Then is translates the coordinate system
+ to this position and rotates it such that the positive $x$-axis is
+ tangent to the path. Then a protective scope is created, inside
+ which the above code is executed -- resulting in a little cross on
+ the path.
+
+ The |markings| decoration allows you to place one or more such
+ markings on a path. The decoration destroys the input path (except
+ in certain cases, detailed later), which means that it uses the path
+ for determining positions on the path, but after the decoration is
+ done this path is gone. You typically need to use a |postaction| to
+ add markings.
+
+ Let us start with the above example in real code:
+\begin{codeexample}[]
+\begin{tikzpicture}[decoration={
+ markings,% switch on markings
+ mark=% actually add a mark
+ at position 2cm
+ with
+ {
+ \draw (-2pt,-2pt) -- (2pt,2pt);
+ \draw (2pt,-2pt) -- (-2pt,2pt);
+ }
+ }
+ ]
+ \draw [help lines] grid (3,2);
+ \draw [postaction={decorate}] (0,0) -- (3,1) arc (0:180:1.5 and 1);
+\end{tikzpicture}
+\end{codeexample}
+
+ We can also add the cross repeatedly:
+\begin{codeexample}[]
+\begin{tikzpicture}[decoration={
+ markings,% switch on markings
+ mark=% actually add a mark
+ between positions 0 and 1 step 5mm
+ with
+ {
+ \draw (-2pt,-2pt) -- (2pt,2pt);
+ \draw (2pt,-2pt) -- (-2pt,2pt);
+ }
+ }
+ ]
+ \draw [help lines] grid (3,2);
+ \draw [postaction={decorate}] (0,0) -- (3,1) arc (0:180:1.5 and 1);
+\end{tikzpicture}
+\end{codeexample}
+
+ The |mark| decoration option is used to specify a marking. It comes
+ in two version:
+ \begin{key}{/pgf/decoration/mark=|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 removed 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
+ 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 contains 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
+ mark=at position 1cm with \node[red]{1cm};,
+ mark=at position .5 with \node[green]{mid};,
+ mark=at position -1cm with {\node[blue,transform shape]{1cm from end};}}
+ ]
+ \draw [help lines] grid (3,2);
+ \draw [postaction={decorate}] (0,0) -- (3,1) arc (0:180:1.5 and 1);
+\end{tikzpicture}
+\end{codeexample}
+
+ Here is an example that shows how markings can be used to place text
+ on plots:
+\begin{codeexample}[]
+\begin{tikzpicture}[domain=0:4,label/.style={postaction={
+ decorate,
+ decoration={
+ markings,
+ mark=at position .75 with \node #1;}}}]
+ \draw[very thin,color=gray] (-0.1,-1.1) grid (3.9,3.9);
+
+ \draw[->] (-0.2,0) -- (4.2,0) node[right] {$x$};
+ \draw[->] (0,-1.2) -- (0,4.2) node[above] {$f(x)$};
+
+ \draw[red,label={[above left]{$f(x)=x$}}] plot (\x,\x);
+ \draw[blue,label={[below left]{$f(x)=\sin x$}}] plot (\x,{sin(\x r)});
+ \draw[orange,label={[right]{$f(x)= \frac{1}{20} \mathrm e^x$}}] plot (\x,{0.05*exp(\x)});
+\end{tikzpicture}
+\end{codeexample}
+
+ When the \meta{code} is begin executed, two special keys will have
+ been setup, whose value may be of interest:
+ \begin{key}{/pgf/decoration/mark info/sequence number}
+ This key can only be read. Its value (which can be obtained
+ using the |\pgfkeysvalueof| command) is a ``sequence number'' of
+ the mark. The first mark that is added to a path has number |1|,
+ the second number |2|, and so on. This key is mainly useful in
+ conjunction with repeated markings (see below).
+ \end{key}
+ \begin{key}{/pgf/decoration/mark info/distance from start}
+ This key can only be read. Its value is the distance of the
+ marking from the start of the path in points. For instance, if
+ the path length is 100pt and the marking is in the middle of the
+ path, the value of this key would be |50.0pt|.
+ \end{key}
+ \end{key}
+
+ A second way to use the |mark| key is the following:
+ \begin{key}{/pgf/decoration/mark=|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
+ with { \draw (-2pt,-2pt) -- (2pt,2pt);
+ \draw (2pt,-2pt) -- (-2pt,2pt); }} ]
+ \draw [help lines] grid (3,2);
+ \draw [postaction={decorate}] (0,0) -- (3,1) arc (0:180:1.5 and 1);
+\end{tikzpicture}
+\end{codeexample}
+
+ In the next example we place arrow shapes on the path instead of
+ crosses. Note the use of the |transform shape| option to ensure
+ that the nodes are actually rotated.
+\begin{codeexample}[]
+\begin{tikzpicture}[decoration={markings,
+ mark=between positions 0 and 1 step 1cm
+ with { \node [single arrow,fill=red,
+ single arrow head extend=3pt,transform shape] {};}}]
+ \draw [help lines] grid (3,2);
+ \draw [postaction={decorate}] (0,0) -- (3,1) arc (0:180:1.5 and 1);
+\end{tikzpicture}
+\end{codeexample}
+
+ Using the key |sequence number| we can also ``number'' the nodes
+ and even refer to them later on.
+\begin{codeexample}[]
+\begin{tikzpicture}[decoration={markings,
+ mark=between positions 0 and 1 step 1cm with {
+ \node [draw,
+ name=mark-\pgfkeysvalueof{/pgf/decoration/mark info/sequence number},
+ transform shape]
+ {\pgfkeysvalueof{/pgf/decoration/mark info/sequence number}};}}]
+ \draw [help lines] grid (3,2);
+ \draw [postaction={decorate}] (0,0) -- (3,1) arc (0:180:1.5 and 1);
+ \draw [red,->] (mark-3) -- (mark-7);
+\end{tikzpicture}
+\end{codeexample}
+
+ In the following example we use the distance info to place
+ ``length information'' on a path:
+\begin{codeexample}[]
+\begin{tikzpicture}[decoration={markings,
+ % Main marks
+ mark=between positions 0 and 1 step 40pt with
+ { \draw [help lines] (0,0) -- (0,0.5)
+ node[above,font=\tiny]{
+ \pgfkeysvalueof{/pgf/decoration/mark info/distance from start}}; },
+ mark=at position -0.1pt with
+ { \draw [help lines] (0,0) -- (0,0.5)
+ node[above,font=\tiny]{
+ \pgfkeysvalueof{/pgf/decoration/mark info/distance from start}}; }}]
+ \draw [help lines] grid (5,3);
+ \draw [postaction={decorate}] (0,0) .. controls (8,3) and (0,3) .. (5,0) ;
+\end{tikzpicture}
+\end{codeexample}
+ \end{key}
+
+ \begin{key}{/pgf/decoration/reset marks}
+ Since |mark| options accumulate, there needs to be a way to
+ ``reset'' things, so that any |mark| options set in an enclosing
+ scope do not interfere. This option does exactly this. Note that
+ when the \meta{code} of a marking is executed, the markings are
+ automatically reset.
+ \end{key}
+
+ As mentioned earlier, the decoration usually destroys the
+ path. However, this is no longer the case when the following key is
+ set:
+ \begin{key}{/pgf/decoration/mark connection node=\meta{node name} (initially empty)}
+ When this key is set to a nonempty \meta{node name} while the
+ decoration is being processed, the following happens: The marking
+ code should, among possibly other things, define 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,
+ mark=at position .5 with
+ {\node [draw,blue,transform shape] (my node) {my node};}}]
+ \draw [help lines] grid (3,2);
+ \draw decorate { (0,0) -- (3,2) };
+\end{tikzpicture}
+\end{codeexample}
+
+\begin{codeexample}[]
+\begin{tikzpicture}[decoration={markings,
+ mark connection node=my node,
+ mark=at position .25 with
+ {\node [draw,red] (my node) {my node};}}]
+ \draw [help lines] grid (3,2);
+ \draw decorate { (0,0) -- (3,2) };
+\end{tikzpicture}
+\end{codeexample}
+
+ \end{key}
+\end{decoration}
+
+
+\subsubsection{Arrow Tip Markings}
+
+Frequent markings that are hard to create correctly are arrow
+tips. For them, two special commands are available when the \meta{code} of
+a |mark| option is execute. (They are only defined in this code):
+
+\begin{command}{\arrow\opt{\oarg{options}}\marg{arrow end tip}}
+ This command simply draws the \meta{arrow end tip} at the origin,
+ pointing right. This is exactly what you need when you want to
+ draw an arrow tip as a marking.
+
+ The \meta{options} can only be given when \tikzname\ is used. In
+ this case, they are executed in a scope that contains the arrow
+ tip.
+\begin{codeexample}[]
+\begin{tikzpicture}[decoration={
+ markings,% switch on markings
+ mark=at position 1cm with {\node[red]{1cm};},
+ mark=at position .75 with {\arrow[blue,line width=2mm]{>}},
+ mark=at position -1cm with {\arrowreversed[black]{stealth};}}
+ ]
+ \draw [help lines] grid (3,2);
+ \draw [postaction={decorate}] (0,0) -- (3,1) arc (0:180:1.5 and 1);
+\end{tikzpicture}
+\end{codeexample}
+
+ Here is a more useful example:
+\begin{codeexample}[]
+\begin{tikzpicture}[decoration={
+ markings,% switch on markings
+ mark=between positions 0 and .75 step 4mm with {\arrow{stealth}},
+ mark=between positions .75 and 1 step 4mm with {\arrowreversed{stealth}}}
+ ]
+ \draw [help lines] grid (3,2);
+ \draw [postaction={decorate}] (0,0) -- (3,1) arc (0:180:1.5 and 1);
+\end{tikzpicture}
+\end{codeexample}
+\end{command}
+
+\begin{command}{\arrowreversed\opt{\oarg{options}}\marg{arrow end tip}}
+ As above, only the arrow end tip is flipped and points in the
+ other direction.
+\end{command}
+
+
+\subsubsection{Footprint Markings}
+
+\begin{pgflibrary}{decorations.footprints}
+ The decorations of this library can be used to decorate a path with
+ little footprints, as if someone had ``walked'' along the path.
+\end{pgflibrary}
+
+\begin{decoration}{footprints}
+ The footprint decoration adds little footprints around the
+ path. They start with the left foot.
+\begin{codeexample}[]
+\begin{tikzpicture}[decoration={footprints,foot length=5pt,stride length=10pt}]
+ \draw [help lines] grid (3,3);
+ \fill [decorate] (0,0) -- (3,2) arc (0:180:1.5 and 1);
+\end{tikzpicture}
+\end{codeexample}
+ You can influence the way this decoration looks using the following
+ options:
+ \begin{key}{/pgf/decoration/foot length (initially 10pt)}
+ The length or size of the footprint itself. A larger value makes
+ the footprint larger, but does not change the stride length.
+\begin{codeexample}[]
+\begin{tikzpicture}[decoration={footprints,foot length=20pt}]
+ \fill [decorate] (0,0) -- (3,0);
+\end{tikzpicture}
+\end{codeexample}
+ \end{key}
+ \begin{key}{/pgf/decoration/stride length (initially 30pt)}
+ The length of strides. This is the distance between the beginnings
+ of left footprints along the path.
+\begin{codeexample}[]
+\begin{tikzpicture}[decoration={footprints,stride length=50pt}]
+ \fill [decorate] (0,0) -- (3,0);
+\end{tikzpicture}
+\end{codeexample}
+ \end{key}
+ \begin{key}{/pgf/decoration/foot sep (initially 4pt)}
+ The separation in the middle between the footprints. The
+ footprints are moved away from the path by half this amount.
+\begin{codeexample}[]
+\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 rotate 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{decoration}
+
+
+
+
+\subsubsection{Shape Background Markings}
+
+The third library for adding markings uses the background paths of
+certain shapes. This library is included mostly for historical
+reasons, using the |markings| library is usually preferable.
\begin{pgflibrary}{decorations.shapes}
This library defines decorations that use shapes or shape-like
drawings to decorate a path. The following options are common
options used by the decorations in this library:
-
+
\begin{key}{/pgf/decoration/shape width=\meta{dimension} (initially 2.5pt)}
The desired width of the shapes. For decorations that support
varying shape sizes, this key sets both the start and end width
@@ -517,7 +1062,7 @@ the paths.
\begin{decoration}{crosses}
This decoration replaces the path by (diagonal) crosses. The
- following parameters influence the decoration:
+ following parameters influence the decoration:
\begin{itemize}
\item |segment length|
determines the distance between (the centers of) consecutive crosses.
@@ -536,7 +1081,7 @@ the paths.
\begin{decoration}{triangles}
This decoration replaces the path by triangles that point along the
- path. The following parameters influence the decoration:
+ path. The following parameters influence the decoration:
\begin{itemize}
\item |segment length|
determines the distance between consecutive triangles.
@@ -555,15 +1100,19 @@ the paths.
\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 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}. You cannot have text inside the shapes of this path, you
- cannot name them, or refer to them.
+ 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
+ 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}]
@@ -593,7 +1142,7 @@ the paths.
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.
+ of the path.
\begin{codeexample}[]
\begin{tikzpicture}[decoration={
@@ -605,7 +1154,7 @@ the paths.
\end{tikzpicture}
\end{codeexample}
- Keys for cusomizing specific shapes can be specified (e.g.,
+ 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
@@ -616,7 +1165,7 @@ the paths.
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},
@@ -631,17 +1180,17 @@ the paths.
\end{codeexample}
There are various keys to control the drawing of the shape
- decoration.
-
+ decoration.
+
\begin{key}{/pgf/decoration/shape=\meta{shape name} (initially circle)}
The shape whose background path is used.
\end{key}
-
- \begin{key}{/pgf/decorations/shape sep=\meta{spacing} (initially {.25cm, between centers})}
- Set the spacing between the shapes on the decorationd 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
+
+ \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.
@@ -660,19 +1209,19 @@ the paths.
\end{tikzpicture}
\end{codeexample}
\end{key}
-
+
\begin{key}{/pgf/decoration/shape evenly spread=\meta{number}}
- This key overides 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.
+ 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),
+ 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 noticable effect if the shapes sizes
+ 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},
@@ -684,7 +1233,7 @@ the paths.
\fill [paint=green,spreading={5, by borders},
decoration={shape scaled}] (0,2) -- (3,2);
\fill [paint=blue,spreading={5, by centers},
- decoration={shape scaled}] (0,1.5) -- (3,1.5);
+ decoration={shape scaled}] (0,1.5) -- (3,1.5);
\fill [paint=red, spreading=5] (0,1) -- (3,1);
\fill [paint=orange, spreading=4] (0,.5) -- (3,.5);
\fill [paint=gray, spreading=1] (0,0) -- (3,0);
@@ -693,8 +1242,8 @@ the paths.
\end{key}
\begin{key}{/pgf/decoration/shape sloped=\opt{\meta{boolean}} (initially true)}
- By default, shapes are rotated to the slope of the decorationd path. If
- \meta{boolean} is the value |false|, then this rotation is turned
+ 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.
@@ -705,7 +1254,7 @@ the paths.
\begin{tikzpicture}[decoration={
shape width=.65cm, shape height=.45cm,
shape=isosceles triangle, shape sep=.75cm,
- shape backgrounds}]
+ shape backgrounds}]
\draw [help lines] grid (3,2);
\draw [paint=red,decorate] (0,0) -- (2,2);
\draw [paint=blue,decorate,decoration={shape sloped=false}]
@@ -715,7 +1264,7 @@ the paths.
\end{key}%
It is possible to scale the width and height of the shapes across the
- length of the decorationd path. The shapes are scaled between the starting
+ 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:
@@ -746,9 +1295,9 @@ the paths.
\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}}
- Set both the the start height and start width simultaneously.
+ Set both the start height and start width simultaneously.
\end{stylekey}%
\begin{key}{/pgf/decoration/shape end width=\meta{length} (initially 2.5pt)}
@@ -757,7 +1306,7 @@ the paths.
of the path.
-\begin{codeexample}[]
+\begin{codeexample}[]
\tikzset{
bigger/.style={decoration={shape start size=.25cm, shape end size=1cm}},
smaller/.style={decoration={shape start size=1cm, shape end size=.25cm}},
@@ -767,13 +1316,13 @@ the paths.
\begin{tikzpicture}
\draw [help lines] grid (3,2);
\fill [decorate,bigger,
- decoration={shape sep={.25cm, between borders}}, blue!50]
+ decoration={shape sep={.25cm, between borders}}, blue!50]
(0,1.5) -- (3,1.5);
\fill [decorate,smaller,
- decoration={shape sep={1cm, between centers}}, red!50]
+ decoration={shape sep={1cm, between centers}}, red!50]
(0,.5) -- (3,.5);
- \draw [gray, dotted] (0,1.625) -- (3,2) (0,1.375) -- (3,1)
- (0,1) -- (3,.625) (0,0) -- (3,.375);
+ \draw [gray, dotted] (0,1.625) -- (3,2) (0,1.375) -- (3,1)
+ (0,1) -- (3,.625) (0,0) -- (3,.375);
\end{tikzpicture}
\end{codeexample}
\end{key}%
@@ -783,7 +1332,7 @@ the paths.
\end{key}%
\begin{stylekey}{/pgf/decoration/shape end size=\meta{length}}
- Set both the the end height and end width simultaneously.
+ Set both the end height and end width simultaneously.
\end{stylekey}
\end{decoration}
@@ -795,7 +1344,7 @@ the paths.
\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.
+ text. This can be used to draw text that follows a curve.
\end{pgflibrary}
\begin{decoration}{text along path}
@@ -808,7 +1357,7 @@ the paths.
\begin{codeexample}[]
\catcode`\|12
\begin{tikzpicture}[decoration={text along path,
- text={Some long text along a ridiculously long curve that}}]
+ text={Some long text along a ridiculously long curve that}}]
\draw [help lines] grid (3,2);
\draw [decorate] (0,0) -- (3,1) arc (0:180:1.5 and 1);
\end{tikzpicture}
@@ -820,44 +1369,44 @@ the paths.
\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|.
+ 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 vertcally (relative to the path), the additional
+ 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\textdegree{}
(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
+ 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 sucessful along a path (or even desirable).
+ 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 case by case basis by individually kerning the offending
+ at input segment boundaries. This can (unfortunately) only be solved
+ on 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.
- Consecutive spaces are ignored, so |\ | (or |\space| in \LaTeX)
+ Set 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 formating commands, such as |\it|, |\bf|
- and |\color|, within customisable delimiters. Initially these
- delimiters are both {\tt\char`\|} (however, care will be needed
- regarding the category codes of delimiters --- see below).
+ 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}[]
@@ -865,13 +1414,13 @@ the paths.
\begin{tikzpicture}
\draw [help lines] grid (3,2);
\path [decorate,decoration={text along path,
- text={a big |\color{green}|green|| juicy apple.}}]
+ text={a big |\color{green}|green|| juicy apple.}}]
(0,0) .. controls (0,2) and (3,0) .. (3,2);
\end{tikzpicture}
\end{codeexample}
}
By following the first delimiter
- with |+|, the formatting commands are added to any exisiting
+ with |+|, the formatting commands are added to any existing
formatting.
{\catcode`\|12
@@ -879,16 +1428,16 @@ the paths.
\begin{tikzpicture}
\draw [help lines] grid (3,2);
\path [decorate,decoration={text along path,
- text={a |\large|big |+\bf\color{red}|red|| juicy apple.}}]
+ text={a |\large|big |+\bf\color{red}|red|| juicy apple.}}]
(0,0) .. controls (0,2) and (3,0) .. (3,2);
\end{tikzpicture}
\end{codeexample}
}
- Internally, the text is stored in the macro |\pgfdecorationtext|.
- Any characters that have not been typeset when the end of the
+ 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
@@ -896,21 +1445,21 @@ the paths.
\catcode`\|13
- Set the characters that the text decoration will use to parse
- formatting commands.
+ 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 specifed format commands
- are added to any exisiting ones, you should avoid using |+| as
- a delimiter.
+ 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);
- \path [decorate, decoration={text along path,text format delimiters={[}{]},
- text={A big [\color{red}]red[] and [\color{green}]green[] apple.}}]
+ \path [decorate, decoration={text along path,text format delimiters={[}{]},
+ text={A big [\color{red}]red[] and [\color{green}]green[] apple.}}]
(0,0) .. controls (0,2) and (3,0) .. (3,2);
\end{tikzpicture}
\end{codeexample}
@@ -920,170 +1469,107 @@ the paths.
\begin{key}{/pgf/decoration/text color=\meta{color} (initially black)}
The color of the text.
\end{key}
-\end{decoration}
-
+\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.
-\subsection{Mark Decorations: Adding Arrow Tips and Nodes on a Path}
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \draw [help lines] grid (3,2);
+ \draw [gray, ->]
+ [postaction={decoration={text along path,
+ text={a big juicy apple}, text color=red}, decorate}]
+ [postaction={decoration={text along path,
+ text={a big juicy apple}, text color=blue, reverse path}, decorate}]
+ (3,0) .. controls (3,2) and (0,2) .. (0,0);
+\end{tikzpicture}
+\end{codeexample}
-\begin{pgflibrary}{decorations.markings}
- Markings are arbitrary ``marks'' that can be put on a path. Marks
- can be arrow tips or nodes or even whole pictures.
-\end{pgflibrary}
+\end{key}
-\begin{decoration}{markings}
- A \emph{marking} can be thought of a ``little picture'' or a 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 coordiante 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.
+\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}
- The |markings| decoration allows you to place one or more such
- markings on a path. The decoration destroys the input path, 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.
+\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|.
- Let us start with the above example in real code:
\begin{codeexample}[]
-\begin{tikzpicture}[decoration={
- markings,% switch on markings
- mark=% actually add a mark
- at position 2cm
- with
- {
- \draw (-2pt,-2pt) -- (2pt,2pt);
- \draw (2pt,-2pt) -- (-2pt,2pt);
- }
- }
- ]
+\begin{tikzpicture}
\draw [help lines] grid (3,2);
- \draw [postaction={decorate}] (0,0) -- (3,1) arc (0:180:1.5 and 1);
+ \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{codeexample}
- The |mark| decoration option is used to specify a marking. It has
- the following syntax:
- \begin{key}{/pgf/decoration/mark=|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}.
+\end{key}
- 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 removed from the start.
- \item It can be a negative dimesion 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
- 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 lenght. 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}
+\begin{stylekey}{/pgf/decoration/text align/left}
+ Aligns the text to the left end of the path.
- 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 contains all sorts of
- graphic drawing commands, including (even named) nodes.
+\end{stylekey}
- If the position position lies past the end of the path (for
- instance if \meta{pos} is set to |1.2|), the marking will not be
- drawn.
+\begin{stylekey}{/pgf/decoration/text align/right}
+ Aligns the text to the right end of the path.
+\end{stylekey}
- 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{stylekey}{/pgf/decoration/text align/center}
+ Aligns the text to the center of the path.
+\end{stylekey}
-\begin{codeexample}[]
-\begin{tikzpicture}[decoration={
- markings,% switch on markings
- mark=at position 1cm with \node[red]{1cm};,
- mark=at position .5 with \node[green]{mid};,
- mark=at position -1cm with {\node[blue,transform shape]{1cm from end};}}
- ]
- \draw [help lines] grid (3,2);
- \draw [postaction={decorate}] (0,0) -- (3,1) arc (0:180:1.5 and 1);
-\end{tikzpicture}
-\end{codeexample}
+\begin{key}{/pgf/decoration/text align/left indent=\meta{length} (initially 0pt)}
+ Specify 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
+ 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.
- 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,
- decoration={
- markings,
- mark=at position .75 with \node #1;}}}]
- \draw[very thin,color=gray] (-0.1,-1.1) grid (3.9,3.9);
-
- \draw[->] (-0.2,0) -- (4.2,0) node[right] {$x$};
- \draw[->] (0,-1.2) -- (0,4.2) node[above] {$f(x)$};
-
- \draw[red,label={[above left]{$f(x)=x$}}] plot (\x,\x);
- \draw[blue,label={[below left]{$f(x)=\sin x$}}] plot (\x,{sin(\x r)});
- \draw[orange,label={[right]{$f(x)= \frac{1}{20} \mathrm e^x$}}] plot (\x,{0.05*exp(\x)});
+\begin{tikzpicture}
+ \draw [help lines] grid (3,2);
+ \draw [red, dashed]
+ [postaction={decoration={text along path, text={a big juicy apple},
+ text align=fit to path}, decorate}]
+ (0,0) .. controls (0,2) and (3,2) .. (3,0);
\end{tikzpicture}
\end{codeexample}
- Frequent markings that are hard to create correctly are arrow
- tips. For them, inside the \meta{code} two special commands can be
- useful, which are only defined in this code:
- \begin{command}{\arrow\opt{\oarg{options}}\marg{arrow end tip}}
- This command simply draws the \meta{arrow end tip} at the origin,
- pointing right. This is exactly what you need when you want to
- draw an arrow tip as a marking.
-
- The \meta{options} can only be given when \tikzname\ is used. In
- this case, they are executed in a scope that contains the arrow
- tip.
+\end{key}
+
+\begin{key}{/pgf/decoration/text align/fit to path stretching spaces=\meta{boolean} (initially false)}
+ This key works like the previous key except the automaton
+ shifts forward only for space characters (including |\space|, but
+ \emph{excluding} |\ |).
+
\begin{codeexample}[]
-\begin{tikzpicture}[decoration={
- markings,% switch on markings
- mark=at position 1cm with {\node[red]{1cm};},
- mark=at position .75 with {\arrow[blue,line width=2mm]{>}},
- mark=at position -1cm with {\arrowreversed[black]{stealth};}}
- ]
+\begin{tikzpicture}
\draw [help lines] grid (3,2);
- \draw [postaction={decorate}] (0,0) -- (3,1) arc (0:180:1.5 and 1);
+ \draw [red, dashed]
+ [postaction={decoration={text along path, text={a big juicy apple},
+ text align={fit to path stretching spaces}}, decorate}]
+ (0,0) .. controls (0,2) and (3,2) .. (3,0);
\end{tikzpicture}
-\end{codeexample}
- \end{command}
- \begin{command}{\arrowreversed\opt{\oarg{options}}\marg{arrow end tip}}
- As above, only the arrow end tip is flipped and points in the
- other direction.
- \end{command}
- \end{key}
+\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}
\end{decoration}
@@ -1141,7 +1627,7 @@ the paths.
\begin{decoration}{Cantor set}
This decoration replaces a straight line by a ``line with a whole in
the middle.'' The Hausdorff dimension of the Cantor set is $\log
- 2/\log 3$.
+ 2/\log 3$.
\begin{codeexample}[]
\begin{tikzpicture}[decoration=Cantor set,very thick]
\draw decorate{ (0,0) -- (3,0) };
@@ -1155,82 +1641,5 @@ the paths.
-\subsection{Footprint Decorations}
-
-
-\begin{pgflibrary}{decorations.footprints}
- The decorations of this library can be used to decorate a path with
- little footprints, as if someone had ``walked'' along the path.
-\end{pgflibrary}
-
-
-\begin{decoration}{footprints}
- The footprint decoration adds little footprints around the
- path. They start with the left foot.
-\begin{codeexample}[]
-\begin{tikzpicture}[decoration={footprints,foot length=5pt,stride length=10pt}]
- \draw [help lines] grid (3,3);
- \fill [decorate] (0,0) -- (3,2) arc (0:180:1.5 and 1);
-\end{tikzpicture}
-\end{codeexample}
- You can influence the way this decoration looks using the following
- options:
- \begin{key}{/pgf/decoration/foot length (initially 10pt)}
- The length or size of the footprint itself. A larger value makes
- the footprint larger, but does not change the stride length.
-\begin{codeexample}[]
-\begin{tikzpicture}[decoration={footprints,foot length=20pt}]
- \fill [decorate] (0,0) -- (3,0);
-\end{tikzpicture}
-\end{codeexample}
- \end{key}
- \begin{key}{/pgf/decoration/stride length (initially 30pt)}
- The length of strides. This is the distance between the beginnings
- of left footprints along the path.
-\begin{codeexample}[]
-\begin{tikzpicture}[decoration={footprints,stride length=50pt}]
- \fill [decorate] (0,0) -- (3,0);
-\end{tikzpicture}
-\end{codeexample}
- \end{key}
- \begin{key}{/pgf/decoration/foot sep (initially 4pt)}
- The separation in the middle between the footprints. The
- footprints are moved away from the path by half this amount.
-\begin{codeexample}[]
-\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 rotate 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{decoration}
-
-
\endinput
-
-
-