summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-decorations.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-decorations.tex')
-rw-r--r--Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-decorations.tex1310
1 files changed, 639 insertions, 671 deletions
diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-decorations.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-decorations.tex
index 92da9d37342..b51d5373162 100644
--- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-decorations.tex
+++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-decorations.tex
@@ -1,4 +1,4 @@
- % Copyright 2008 by Till Tantau and Mark Wibrow
+% Copyright 2008 by Till Tantau and Mark Wibrow
%
% This file may be distributed and/or modified
%
@@ -7,29 +7,29 @@
%
% See the file doc/generic/pgf/licenses/LICENSE for more details.
+
\section{Decorations}
\label{section-base-decorations}
-
\begin{pgfmodule}{decorations}
- The commands for creating decorations are defined in this
- module, so you need to load this module to use decorations. This
- module is automatically loaded by the different decoration
- libraries.
+ The commands for creating decorations are defined in this module, so you
+ need to load this module to use decorations. This module is automatically
+ loaded by the different decoration libraries.
\end{pgfmodule}
\subsection{Overview}
-Decorations are a general way of creating graphics by ``moving along''
-a path and, while doing so, either drawing something or constructing a
-new path. This could be as simple as extending a path with a
-``zigzagged'' line\ldots
-
+Decorations are a general way of creating graphics by ``moving along'' a path
+and, while doing so, either drawing something or constructing a new path. This
+could be as simple as extending a path with a ``zigzagged'' line\ldots
+%
\begin{codeexample}[]
\tikz \draw decorate[decoration=zigzag] {(0,0) -- (3,0)};
\end{codeexample}
+%
\ldots but could also be as complex as typesetting text along a path:
+%
{\catcode`\|12
\begin{codeexample}[]
\tikz \path decorate [decoration={text along path,
@@ -39,237 +39,222 @@ new path. This could be as simple as extending a path with a
}
The workflow for using decorations is the following:
+%
\begin{enumerate}
-\item You define a decoration using the |\pgfdeclaredecoration|
- command. Different useful decorations are already declared in
- libraries like |decorations.shapes|.
-\item You use normal path construction commands like |\pgfpathlineto|
- to construct a path. Let us call this path the
- \emph{to-be-decorated} path.
-\item You place the path construction commands inside the environment
- |{pgfdecoration}|. This environment takes the name of a previously
- declared decoration as a parameter. It will then start ``walking
- along'' the to-be-decorated path. As it does this, a special finite
- automaton called a \emph{decoration automaton} produces new path commands as its output (or even other outputs). These
- outputs replace the to-be-decorated path; indeed, after the
- to-be-decorated path has been fully walked along it is thrown away,
- only the output of the automaton persists.
+ \item You define a decoration using the |\pgfdeclaredecoration| command.
+ Different useful decorations are already declared in libraries like
+ |decorations.shapes|.
+ \item You use normal path construction commands like |\pgfpathlineto| to
+ construct a path. Let us call this path the \emph{to-be-decorated}
+ path.
+ \item You place the path construction commands inside the environment
+ |{pgfdecoration}|. This environment takes the name of a previously
+ declared decoration as a parameter. It will then start ``walking
+ along'' the to-be-decorated path. As it does this, a special finite
+ automaton called a \emph{decoration automaton} produces new path
+ commands as its output (or even other outputs). These outputs replace
+ the to-be-decorated path; indeed, after the to-be-decorated path has
+ been fully walked along it is thrown away, only the output of the
+ automaton persists.
\end{enumerate}
-In the present section the process of how decoration automata work is
-explained first. Then the command(s) for declaring decoration automata
-and for using them are covered.
-
+In the present section the process of how decoration automata work is explained
+first. Then the command(s) for declaring decoration automata and for using them
+are covered.
\subsection{Decoration Automata}
-Decoration automata (and the closely related meta-decoration automata)
-are a general concept for creating graphics ``along paths.'' For
-straight lines, this idea was first proposed by Till Tantau in an
-earlier version of \pgfname, the idea to extend this to arbitrary path
-was proposed and implemented by Mark Wibrow. Further versatility is
-provided by ``meta-decorations''. These are automata that decorate a
-path with decorations.
-
-In the present subsection the different ideas underlying decoration
-automata are presented.
+Decoration automata (and the closely related meta-decoration automata) are a
+general concept for creating graphics ``along paths''. For straight lines, this
+idea was first proposed by Till Tantau in an earlier version of \pgfname, the
+idea to extend this to arbitrary path was proposed and implemented by Mark
+Wibrow. Further versatility is provided by ``meta-decorations''. These are
+automata that decorate a path with decorations.
+In the present subsection the different ideas underlying decoration automata
+are presented.
\subsubsection{The Different Paths}
-In order to prevent confusion with different types of paths, such
-as those that are extended, those that are decorated and those that
-are created, the following conventions will be used:
-
+In order to prevent confusion with different types of paths, such as those that
+are extended, those that are decorated and those that are created, the
+following conventions will be used:
+%
\begin{itemize}
-\item
- The \emph{preexisting} path refers to the current path in existence
- before a decoration environment. (Possibly this path has been
- created by another decoration used earlier, but we will still call
- this path the preexisting path also in this case.)
-\item
- The \emph{input} path refers to the to-be-decorated path that the
- decoration automaton moves along. The input path may consist of many
- line and curve input segments (for example, a circle or an ellipse
- consists of four curves). It is specified inside the decoration
- environment.
-\item
- The \emph{output} path refers to the path that the decoration
- creates. Depending on the decoration, this path may or may not be
- empty (a decoration can also choose to use side-effects instead of
- producing an output path). The input path is always consumed by the
- decoration automaton, that is, it is no longer available in any way
- after the decoration automaton has finished.
+ \item The \emph{preexisting} path refers to the current path in existence
+ before a decoration environment. (Possibly this path has been created
+ by another decoration used earlier, but we will still call this path
+ the preexisting path also in this case.)
+ \item The \emph{input} path refers to the to-be-decorated path that the
+ decoration automaton moves along. The input path may consist of many
+ line and curve input segments (for example, a circle or an ellipse
+ consists of four curves). It is specified inside the decoration
+ environment.
+ \item The \emph{output} path refers to the path that the decoration
+ creates. Depending on the decoration, this path may or may not be empty
+ (a decoration can also choose to use side-effects instead of producing
+ an output path). The input path is always consumed by the decoration
+ automaton, that is, it is no longer available in any way after the
+ decoration automaton has finished.
\end{itemize}
-The effect of a decoration environment is the following: The input
-path, which is specified inside the environment, is constructed and
-stored. This process does not alter the preexisting path in any
-way. Then the decoration automaton is started (as described later) and
-it produces an output path (possibly empty). Whenever part of the
-output path is produced, it is concatenated with the preexisting
-path. After the environment, the current path will equal the original
-preexisting path followed by the output path.
-
-It is permissible that a decoration issues a |\pgfusepath|
-command. As usual, this causes the current path to be
-filled or stroked or some other action to be taken and the current
-path is set to the empty path. As described above, when the decoration
-automaton starts, the current path is the preexisting path and as the
-automaton progresses, the current path is constantly being extended by
-the output path. This means that first time a |\pgfusepath| command is
-used on a decoration, the preexisting path is part of the path this
-command operates on; in subsequent calls only the part of the output
-path constructed since the last |\pgfusepath| command will be used.
-
-You can use this mechanism to stroke or fill different parts of the
-output path in different colors, line widths, fills and shades; all
-within the same decoration. Alternatively, a decoration can choose to
-produce no output path at all: the |text| decoration simply typesets
-text along a path.
+The effect of a decoration environment is the following: The input path, which
+is specified inside the environment, is constructed and stored. This process
+does not alter the preexisting path in any way. Then the decoration automaton
+is started (as described later) and it produces an output path (possibly
+empty). Whenever part of the output path is produced, it is concatenated with
+the preexisting path. After the environment, the current path will equal the
+original preexisting path followed by the output path.
+
+It is permissible that a decoration issues a |\pgfusepath| command. As usual,
+this causes the current path to be filled or stroked or some other action to be
+taken and the current path is set to the empty path. As described above, when
+the decoration automaton starts, the current path is the preexisting path and
+as the automaton progresses, the current path is constantly being extended by
+the output path. This means that first time a |\pgfusepath| command is used on
+a decoration, the preexisting path is part of the path this command operates
+on; in subsequent calls only the part of the output path constructed since the
+last |\pgfusepath| command will be used.
+
+You can use this mechanism to stroke or fill different parts of the output path
+in different colors, line widths, fills and shades; all within the same
+decoration. Alternatively, a decoration can choose to produce no output path at
+all: the |text| decoration simply typesets text along a path.
\subsubsection{Segments and States}
-The most common use of a decoration is to ``repeat something along a
-path'' (for example, the |zigzag| decoration
-repeats \tikz\draw decorate[decoration=zigzag]
-{(0,0)--(\pgfdecorationsegmentlength,0)}; along a path). However, it
-not necessarily the case that only one thing is repeated: a decoration
-can consist of different parts, or \emph{segments}, repeated in a
-particular order.
-
-When you declare a decoration, you provide a description
-of how their different segments will be rendered. The description of
-each segment should be given in a way as if the ``$x$-axis'' of the
-segment is the tangent to the path at a particular point,
-and that point is the origin of the segment.
-Thus, for example, the segment of the |zigzag| decoration might be
-defined using the following code:
+The most common use of a decoration is to ``repeat something along a path''
+(for example, the |zigzag| decoration repeats
+%
+\tikz\draw decorate[decoration=zigzag] {(0,0)--(\pgfdecorationsegmentlength,0)};
+%
+along a path). However, it not necessarily the case that only one thing is
+repeated: a decoration can consist of different parts, or \emph{segments},
+repeated in a particular order.
+
+When you declare a decoration, you provide a description of how their different
+segments will be rendered. The description of each segment should be given in a
+way as if the ``$x$-axis'' of the segment is the tangent to the path at a
+particular point, and that point is the origin of the segment. Thus, for
+example, the segment of the |zigzag| decoration might be defined using the
+following code:
+%
\begin{codeexample}[code only]
\pgfpathlineto{\pgfpoint{5pt}{5pt}}
\pgfpathlineto{\pgfpoint{15pt}{-5pt}}
\pgfpathlineto{\pgfpoint{20pt}{0pt}}
\end{codeexample}
-\pgfname\ will ensure that an appropriate coordinate transformation
-is in place when the segment is rendered such that
-the segment actually points in the right direction. Also,
-subsequent segments will be transformed such that they are
-``further along the path'' toward the end of the path.
-All transformations are set up automatically.
-
-Note that we did not use a |\pgfpathmoveto{\pgfpointorigin}| at the
-beginning of the segment code. Doing so would subdivide the path into
-numerous subpaths. Rather, we assume that the previous segment caused
-the current point to be at the origin.
-
-The width of a segment can (and must) be specified
-explicitly. \pgfname\ will use this width to find out the start point
-of the next segment and the correct rotation. The width the you
-provide need not be the ``real'' width of the segment, which allows
-decoration segments to overlap or to be spaced far apart.
-
-The |zigzag| decoration only has one segment that is repeated again and
-again. However, we might also like to have \emph{different} segments
-and use rules to describe which segment should be used where. For
-example, we might have special segments at the start and at the end.
-
-Decorations use a mechanism known in theoretical in computer science
-as \emph{finite state automata} to describe which segment is used at a
-particular point. The idea is the following: For the first segment we
-start in a special \emph{state} called the \emph{initial state}. In
-this state, and also in all other states later, \pgfname\ first
-computes how much space is left on the input path. That is, \pgfname\ keeps
-track of the distance to the end of the input path. Attached to each state
-there is a set of rules of the following form: ``If the remaining
-distance on the input path is less than $x$, switch to state~$q$.''
-\pgfname\ checks for each of these rules whether it applies and, if
-so, immediately switches to state~$q$.
-
-Only if none of the rules tell us to switch to another
-state, \pgfname\ will execute the state's code. This code will
-(typically) add a segment to the output path. In addition to the rules
-there is also a width parameter attached to each state. \pgfname\ then
-translates the coordinate system by this width and reduces the
-remaining distance on the input path. Then, \pgfname\ either stays in
-the current state or switches to another state, depending on yet
+\pgfname\ will ensure that an appropriate coordinate transformation is in place
+when the segment is rendered such that the segment actually points in the right
+direction. Also, subsequent segments will be transformed such that they are
+``further along the path'' toward the end of the path. All transformations are
+set up automatically.
+
+Note that we did not use a |\pgfpathmoveto{\pgfpointorigin}| at the beginning
+of the segment code. Doing so would subdivide the path into numerous subpaths.
+Rather, we assume that the previous segment caused the current point to be at
+the origin.
+
+The width of a segment can (and must) be specified explicitly. \pgfname\ will
+use this width to find out the start point of the next segment and the correct
+rotation. The width the you provide need not be the ``real'' width of the
+segment, which allows decoration segments to overlap or to be spaced far apart.
+
+The |zigzag| decoration only has one segment that is repeated again and again.
+However, we might also like to have \emph{different} segments and use rules to
+describe which segment should be used where. For example, we might have special
+segments at the start and at the end.
+
+Decorations use a mechanism known in theoretical in computer science as
+\emph{finite state automata} to describe which segment is used at a particular
+point. The idea is the following: For the first segment we start in a special
+\emph{state} called the \emph{initial state}. In this state, and also in all
+other states later, \pgfname\ first computes how much space is left on the
+input path. That is, \pgfname\ keeps track of the distance to the end of the
+input path. Attached to each state there is a set of rules of the following
+form: ``If the remaining distance on the input path is less than $x$, switch to
+state~$q$.'' \pgfname\ checks for each of these rules whether it applies and,
+if so, immediately switches to state~$q$.
+
+Only if none of the rules tell us to switch to another state, \pgfname\ will
+execute the state's code. This code will (typically) add a segment to the
+output path. In addition to the rules there is also a width parameter attached
+to each state. \pgfname\ then translates the coordinate system by this width
+and reduces the remaining distance on the input path. Then, \pgfname\ either
+stays in the current state or switches to another state, depending on yet
another property attached of the state.
-The whole process stops when a special state called |final| is
-reached. The segment of this state is immediately added to the output
-path (it is often empty, though) and the process ends.
-
-
+The whole process stops when a special state called |final| is reached. The
+segment of this state is immediately added to the output path (it is often
+empty, though) and the process ends.
\subsection{Declaring Decorations}
-The following command is used to declare a decoration. Essentially,
-this command describes the decoration automaton.
-
-
-\begin{command}{\pgfdeclaredecoration\marg{name}\marg{initial
- state}\marg{states}}
- This command declares a new decoration called \meta{name}. The
- \meta{states} argument contains a description of the decoration
- automaton's states and the transitions between them. The
- \meta{initial state} is the state in which the automaton starts.
-
- When the automaton is later applied to an input path, it keeps track
- of a certain position on the input path. This current point
- will ``travel along the path,'' each time being moved along by a
- certain distance. This will also work if the path is not a straight
- line. That is, it is permissible that the path curves are veers at a
- sharp angle. It is also permissible that while traveling along the
- input path, the current input segment ends and a new input segment starts. In this
- case, the remaining distance on the first input segment is subtracted
- from the \meta{dimension} and then we travel along the second
- input segment for the remaining distance. This input segment may also end
- early, in which case we travel along the next input segment, and so
- on. Note that it cannot happen that we travel past the end of the
- input path since this would have caused an immediate switch to
- the |final| state.
-
- Note that the computation of the path lengths has only a low
- accuracy because of \TeX's small math capabilities. Do not
- expect high accuracy alignments when using decorations (unless the
- input path consists only of horizontal and vertical lines).
-
- The \meta{states} argument should consist of |\state| commands, one
- for each state of the decoration automaton. The |\state| command is
- defined only when the \meta{states} argument is executed.
-
- \begin{command}{\state\marg{name}\oarg{options}\marg{code}}
- This command declares a new state inside the current decoration
- automaton. The state is named \meta{name}.
-
- When the decoration automaton is in state \meta{name}, the following things
- happen:
- \begin{enumerate}
- \item
- The \meta{options} are parsed. This may lead to a
- state switch, see below. When this happens, the following steps are not
- executed. The \meta{options} are executed one after the other in
- the given order. If an option causes a state switch, the switch
- is immediate, even if later options might cause a different
- state switch.
- \item
- The \meta{code} is executed in a \TeX-group with the current
- transformation matrix set up in such a way that the origin is on
- the input path at the current point (the point at the distance
- traveled up to now) and the coordinate system is rotated in
- such a way that the positive $x$-axis points in the direction of
- the tangent to the input path at the current point, while the
- positive $y$-axis points to the left of this tangent.
-
- As described earlier, the \meta{code} can have two different
- effects: If it just contains path construction commands, the
- decoration will produce an output path, that is, it extends the
- preexisting path. Here is an example:
-
+The following command is used to declare a decoration. Essentially, this
+command describes the decoration automaton.
+
+\begin{command}{\pgfdeclaredecoration\marg{name}\marg{initial state}\marg{states}}
+ This command declares a new decoration called \meta{name}. The
+ \meta{states} argument contains a description of the decoration automaton's
+ states and the transitions between them. The \meta{initial state} is the
+ state in which the automaton starts.
+
+ When the automaton is later applied to an input path, it keeps track of a
+ certain position on the input path. This current point will ``travel along
+ the path'', each time being moved along by a certain distance. This will
+ also work if the path is not a straight line. That is, it is permissible
+ that the path curves are veers at a sharp angle. It is also permissible
+ that while traveling along the input path, the current input segment ends
+ and a new input segment starts. In this case, the remaining distance on the
+ first input segment is subtracted from the \meta{dimension} and then we
+ travel along the second input segment for the remaining distance. This
+ input segment may also end early, in which case we travel along the next
+ input segment, and so on. Note that it cannot happen that we travel past
+ the end of the input path since this would have caused an immediate switch
+ to the |final| state.
+
+ Note that the computation of the path lengths has only a low accuracy
+ because of \TeX's small math capabilities. Do not expect high accuracy
+ alignments when using decorations (unless the input path consists only of
+ horizontal and vertical lines).
+
+ The \meta{states} argument should consist of |\state| commands, one for
+ each state of the decoration automaton. The |\state| command is defined
+ only when the \meta{states} argument is executed.
+
+ \begin{command}{\state\marg{name}\oarg{options}\marg{code}}
+ This command declares a new state inside the current decoration
+ automaton. The state is named \meta{name}.
+
+ When the decoration automaton is in state \meta{name}, the following
+ things happen:
+ %
+ \begin{enumerate}
+ \item The \meta{options} are parsed. This may lead to a state
+ switch, see below. When this happens, the following steps are
+ not executed. The \meta{options} are executed one after the
+ other in the given order. If an option causes a state switch,
+ the switch is immediate, even if later options might cause a
+ different state switch.
+ \item The \meta{code} is executed in a \TeX-group with the current
+ transformation matrix set up in such a way that the origin is
+ on the input path at the current point (the point at the
+ distance traveled up to now) and the coordinate system is
+ rotated in such a way that the positive $x$-axis points in the
+ direction of the tangent to the input path at the current
+ point, while the positive $y$-axis points to the left of this
+ tangent.
+
+ As described earlier, the \meta{code} can have two different
+ effects: If it just contains path construction commands, the
+ decoration will produce an output path, that is, it extends the
+ preexisting path. Here is an example:
+ %
\begin{codeexample}[]
\pgfdeclaredecoration{example}{initial}
{
@@ -293,13 +278,13 @@ this command describes the decoration automaton.
}
\end{codeexample}
- Alternatively, the \meta{code} can also contain the
- |\pgfusepath| command. This will use the path in the usual manner,
- where ``the path'' is the preexisting path plus a part of the
- output path for the first invocation and the different parts of
- the rest of the output path for the following invocation. Here is
- an example:
-
+ Alternatively, the \meta{code} can also contain the
+ |\pgfusepath| command. This will use the path in the usual
+ manner, where ``the path'' is the preexisting path plus a part
+ of the output path for the first invocation and the different
+ parts of the rest of the output path for the following
+ invocation. Here is an example:
+ %
\begin{codeexample}[]
\pgfdeclaredecoration{stars}{initial}{
\state{initial}[width=15pt]
@@ -320,171 +305,175 @@ this command describes the decoration automaton.
.. controls (3,-3) and (0,0) .. (0,-3)
.. controls (0,-5) and (3,-5) .. (3,-3);
\end{codeexample}
-
- \item
- After the \meta{code} has been executed (possibly more than
- once, if the |repeat state| option is used), the state switches to
- whatever state has been specified inside the \meta{options}
- using the |next state| option. If no |next state| has been
- specified, the state stays the same.
- \end{enumerate}
-
- The \meta{options} are executed with the key path set to
- |/pgf/decoration automaton|. The following keys are defined:
- \begin{key}{/pgf/decoration automaton/switch if less than=\meta{dimension}\texttt{ to }\meta{new state}}
- When this key is encountered, \pgfname\ checks whether the
- remaining distance to the end of the input path is less than
- \meta{dimension}. If so, an immediate state switch to \meta{new
- state} occurs.
- \end{key}
- \begin{key}{/pgf/decoration automaton/switch if input segment less than=\\\meta{dimension}\texttt{ to }\meta{new state}}
- When this key is encountered, \pgfname\ checks whether the
- remaining distance to the end of the current input segment of the
- input path is less than \meta{dimension}. If so, an immediate
- state switch to \meta{new state} occurs.
- \end{key}
- \begin{key}{/pgf/decoration automaton/width=\meta{dimension}}
- First, this option causes an immediate switch to the
- state |final| if the remaining distance on the input path is
- less than \meta{dimension}. The effect is the same as if you had
- said |switch if less than=|\meta{dimension}| to final| just
- before the |width| option.
-
- If no switch occurs, this option tells \pgfname\ the width of
- the segment. The current point will travel along the input path
- (as described earlier) by this distance.
- \end{key}
- \begin{key}{/pgf/decoration automaton/repeat state=\meta{repetitions} (initially 0)}
- Tells \pgfname\ how long the automaton stays ``normally'' in the
- current state. This count is reset to \meta{repetitions} each
- time one of the |switch if| keys causes a state switch. If no
- state switches occur, the \meta{code} is executed and the
- repetition counter is decreased. Then, there is once more a
- chance of a state change caused by any of the \meta{options}. If
- no repetition occurs, the \meta{code} is executed
- once more and the counter is decreased once more. When the
- counter reaches zero, the \meta{code} is executed once more,
- but, then, a different state is entered, as specified by the
- |next state| option.
-
- Note, that the maximum number of times the state will be executed
- is $\meta{repetitions}+1$.
- \end{key}
- \begin{key}{/pgf/decoration automaton/next state=\meta{new state}}
- After the \meta{code} for state has been executed for the last
- time, a state switch to \meta{new state} is performed. If this
- option is not given, the next state is the same as the current state.
- \end{key}
-
- \begin{key}{/pgf/decoration automaton/if input segment is closepath=\meta{options}}
- This key checks whether the current input segment is a closepath
- operation. If so, the \meta{options} get executed; otherwise
- nothing happens. You can use this option to handle a closepath
- in some special way, for instance, switching to a new state in
- which |\pgfpathclose| is executed.
- \end{key}
-
- \begin{key}{/pgf/decoration automaton/auto end on length=\meta{dimension}}
- This key is just included for convenience, it does nothing that
- cannot be achieved using the previous options. The effect is the
- following: If the remaining input path's length is at most
- \meta{dimension}, the decorated path is ended with a straight
- line to the end of the input path and, possibly, it is closed,
- namely if the input path ended with a closepath
- operation. Otherwise, it is checked whether the current input
- segment is a closepath segment and whether the remaining
- distance on the current input segment is at most
- \meta{distance}. If so, then a closepath operation is used to
- close the decorated path and the automaton continues with the
- next subpath, remaining in the current state.
-
- In all other cases, nothing happens.
- \end{key}
-
- \begin{key}{/pgf/decoration automaton/auto corner on length=\meta{dimension}}
- This key has the following effect: Firstly, in case the \TeX-if
- |\ifpgfdecoratepathhascorners| is false, nothing
- happens. Otherwise, it is tested whether the remaining distance
- on the current input segment is at most \meta{dimension}. If so,
- a |lineto| operation is used to reach the end of this input
- segment and the automaton continues with the next input segment,
- but remains in the current state.
-
- The main idea behind this option is to avoid having decoration
- segments ``overshoot'' past a corner.
- \end{key}
-
- You may sometimes wish to do computations outside the
- transformational \TeX-group of the current segment,
- so that these results of these computations are available in the
- next state. For this, the following two options are useful:
-
- \begin{key}{/pgf/decoration automaton/persistent precomputation=\meta{precode}}
- If the \meta{code} of the state is executed, the \meta{precode} is
- executed first and it is executed outside the \TeX-group of the
- \meta{code}. Note that when the \meta{precode} is executed, the
- transformation matrix is not set up.
- \end{key}
-
- \begin{key}{/pgf/decoration automaton/persistent postcomputation=\meta{postcode}}
- Works like the |persistent precomputation| option, only the
- \meta{postcode} is executed after (and also outside) the
- \TeX-group of the main \meta{code}.
- \end{key}
-
- There are a number of macros and dimensions which may be useful
- inside a decoration automaton. The following macros are available:
-
- \begin{command}{\pgfdecoratedpathlength}
- The length of the input path. If the input path consists of
- several input segments, this number is the sum of the lengths of the
- input segments.
- \end{command}
-
- \begin{command}{\pgfdecoratedinputsegmentlength}
- The length of the current input segment of the input path. ``Current
- input segment'' refers to the input segment on which the current point
- lies.
- \end{command}
-
- \begin{command}{\pgfpointdecoratedpathlast}
- The final point of the input path.
- \end{command}
-
- \begin{command}{\pgfpointdecoratedinputsegmentlast}
- The final point of the current input segment of the input path.
- \end{command}
-
- \begin{command}{\pgfdecoratedangle}
- The angle of the tangent to the decorated path at the \emph{origin}
- of the current segment. The transformation matrix applied at
- the beginning of a state includes a rotation equivalent to
- this angle.
- \end{command}
-
- The following \TeX\ dimension registers are also available inside the
- automaton:
-
- \begin{command}{\pgfdecoratedremainingdistance}
- The remaining distance on the input path.
- \end{command}
-
- \begin{command}{\pgfdecoratedcompleteddistance}
- The completed distance on the input path.
- \end{command}
-
- \begin{command}{\pgfdecoratedinputsegmentremainingdistance}
- The remaining distance on the current input segment of the input path.
- \end{command}
-
- \begin{command}{\pgfdecoratedinputsegmentcompleteddistance}
- The completed distance on the current input segment of the input path.
- \end{command}
-
- Further keys and macros are defined and used by the decoration
- libraries, see Section~\ref{section-library-decorations}.
-
- The following example shows how these options can be used:
+ %
+
+ \item After the \meta{code} has been executed (possibly more than
+ once, if the |repeat state| option is used), the state switches
+ to whatever state has been specified inside the \meta{options}
+ using the |next state| option. If no |next state| has been
+ specified, the state stays the same.
+ \end{enumerate}
+
+ The \meta{options} are executed with the key path set to
+ |/pgf/decoration automaton|. The following keys are defined:
+ %
+ \begin{key}{/pgf/decoration automaton/switch if less than=\meta{dimension}\texttt{ to }\meta{new state}}
+ When this key is encountered, \pgfname\ checks whether the
+ remaining distance to the end of the input path is less than
+ \meta{dimension}. If so, an immediate state switch to \meta{new
+ state} occurs.
+ \end{key}
+ %
+ \begin{key}{/pgf/decoration automaton/switch if input segment less than=\\\meta{dimension}\texttt{ to }\meta{new state}}
+ When this key is encountered, \pgfname\ checks whether the
+ remaining distance to the end of the current input segment of the
+ input path is less than \meta{dimension}. If so, an immediate state
+ switch to \meta{new state} occurs.
+ \end{key}
+ %
+ \begin{key}{/pgf/decoration automaton/width=\meta{dimension}}
+ First, this option causes an immediate switch to the state |final|
+ if the remaining distance on the input path is less than
+ \meta{dimension}. The effect is the same as if you had said |switch
+ if less than=|\meta{dimension}| to final| just before the |width|
+ option.
+
+ If no switch occurs, this option tells \pgfname\ the width of the
+ segment. The current point will travel along the input path (as
+ described earlier) by this distance.
+ \end{key}
+ %
+ \begin{key}{/pgf/decoration automaton/repeat state=\meta{repetitions} (initially 0)}
+ Tells \pgfname\ how long the automaton stays ``normally'' in the
+ current state. This count is reset to \meta{repetitions} each time
+ one of the |switch if| keys causes a state switch. If no state
+ switches occur, the \meta{code} is executed and the repetition
+ counter is decreased. Then, there is once more a chance of a state
+ change caused by any of the \meta{options}. If no repetition
+ occurs, the \meta{code} is executed once more and the counter is
+ decreased once more. When the counter reaches zero, the \meta{code}
+ is executed once more, but, then, a different state is entered, as
+ specified by the |next state| option.
+
+ Note, that the maximum number of times the state will be executed
+ is $\meta{repetitions}+1$.
+ \end{key}
+ %
+ \begin{key}{/pgf/decoration automaton/next state=\meta{new state}}
+ After the \meta{code} for state has been executed for the last
+ time, a state switch to \meta{new state} is performed. If this
+ option is not given, the next state is the same as the current
+ state.
+ \end{key}
+
+ \begin{key}{/pgf/decoration automaton/if input segment is closepath=\meta{options}}
+ This key checks whether the current input segment is a closepath
+ operation. If so, the \meta{options} get executed; otherwise
+ nothing happens. You can use this option to handle a closepath in
+ some special way, for instance, switching to a new state in which
+ |\pgfpathclose| is executed.
+ \end{key}
+
+ \begin{key}{/pgf/decoration automaton/auto end on length=\meta{dimension}}
+ This key is just included for convenience, it does nothing that
+ cannot be achieved using the previous options. The effect is the
+ following: If the remaining input path's length is at most
+ \meta{dimension}, the decorated path is ended with a straight line
+ to the end of the input path and, possibly, it is closed, namely if
+ the input path ended with a closepath operation. Otherwise, it is
+ checked whether the current input segment is a closepath segment
+ and whether the remaining distance on the current input segment is
+ at most \meta{distance}. If so, then a closepath operation is used
+ to close the decorated path and the automaton continues with the
+ next subpath, remaining in the current state.
+
+ In all other cases, nothing happens.
+ \end{key}
+
+ \begin{key}{/pgf/decoration automaton/auto corner on length=\meta{dimension}}
+ This key has the following effect: Firstly, in case the \TeX-if
+ |\ifpgfdecoratepathhascorners| is false, nothing happens.
+ Otherwise, it is tested whether the remaining distance on the
+ current input segment is at most \meta{dimension}. If so, a
+ |lineto| operation is used to reach the end of this input segment
+ and the automaton continues with the next input segment, but
+ remains in the current state.
+
+ The main idea behind this option is to avoid having decoration
+ segments ``overshoot'' past a corner.
+ \end{key}
+
+ You may sometimes wish to do computations outside the transformational
+ \TeX-group of the current segment, so that these results of these
+ computations are available in the next state. For this, the following
+ two options are useful:
+
+ \begin{key}{/pgf/decoration automaton/persistent precomputation=\meta{precode}}
+ If the \meta{code} of the state is executed, the \meta{precode} is
+ executed first and it is executed outside the \TeX-group of the
+ \meta{code}. Note that when the \meta{precode} is executed, the
+ transformation matrix is not set up.
+ \end{key}
+
+ \begin{key}{/pgf/decoration automaton/persistent postcomputation=\meta{postcode}}
+ Works like the |persistent precomputation| option, only the
+ \meta{postcode} is executed after (and also outside) the \TeX-group
+ of the main \meta{code}.
+ \end{key}
+
+ There are a number of macros and dimensions which may be useful inside
+ a decoration automaton. The following macros are available:
+
+ \begin{command}{\pgfdecoratedpathlength}
+ The length of the input path. If the input path consists of several
+ input segments, this number is the sum of the lengths of the input
+ segments.
+ \end{command}
+
+ \begin{command}{\pgfdecoratedinputsegmentlength}
+ The length of the current input segment of the input path.
+ ``Current input segment'' refers to the input segment on which the
+ current point lies.
+ \end{command}
+
+ \begin{command}{\pgfpointdecoratedpathlast}
+ The final point of the input path.
+ \end{command}
+
+ \begin{command}{\pgfpointdecoratedinputsegmentlast}
+ The final point of the current input segment of the input path.
+ \end{command}
+
+ \begin{command}{\pgfdecoratedangle}
+ The angle of the tangent to the decorated path at the \emph{origin}
+ of the current segment. The transformation matrix applied at the
+ beginning of a state includes a rotation equivalent to this angle.
+ \end{command}
+
+ The following \TeX\ dimension registers are also available inside the
+ automaton:
+
+ \begin{command}{\pgfdecoratedremainingdistance}
+ The remaining distance on the input path.
+ \end{command}
+
+ \begin{command}{\pgfdecoratedcompleteddistance}
+ The completed distance on the input path.
+ \end{command}
+
+ \begin{command}{\pgfdecoratedinputsegmentremainingdistance}
+ The remaining distance on the current input segment of the input path.
+ \end{command}
+
+ \begin{command}{\pgfdecoratedinputsegmentcompleteddistance}
+ The completed distance on the current input segment of the input path.
+ \end{command}
+
+ Further keys and macros are defined and used by the decoration
+ libraries, see Section~\ref{section-library-decorations}.
+
+ The following example shows how these options can be used:
+ %
\begin{codeexample}[]
\pgfdeclaredecoration{complicated example decoration}{initial}
{
@@ -530,19 +519,16 @@ this command describes the decoration automaton.
decorate {(.5,-2) -- ++(2.5,-2.5)} -- (3,-5) -| (0,-2) -- cycle;
\end{tikzpicture}
\end{codeexample}
- \end{command}
+ \end{command}
\end{command}
-
\subsubsection{Predefined Decorations}
-The three decorations |moveto|, |lineto|, and |curveto| are predefined
-and ``always available.'' They are mostly useful in conjunction with
+The three decorations |moveto|, |lineto|, and |curveto| are predefined and
+``always available''. They are mostly useful in conjunction with
meta-decorations. They are documented in
-Section~\ref{section-library-decorations} alongside the other
-decorations.
-
+Section~\ref{section-library-decorations} alongside the other decorations.
\subsection{Using Decorations}
@@ -550,85 +536,74 @@ decorations.
Once a decoration has been declared, it can be used.
\begin{environment}{{pgfdecoration}\marg{decoration list}}
- The \meta{environment contents} should contain commands for creating
- an path. This path is the basis for the \emph{input paths}
- for the decorations in the \meta{decoration list}. In detail, the
- following happens:
- \begin{enumerate}
- \item
- The preexisting unused path is saved.
- \item
- The path commands specified in \meta{environment contents} are
- executed and this resulting path is saved. The path is then
- divided into different \emph{input paths} as follows:
- The format for each item in \marg{decoration list} is
- \begin{quote}
- \marg{decoration}\marg{length}\opt{\marg{before code}\marg{after code}}
- \end{quote}
- The \meta{before code} and the \meta{after code} are optional. The
- input path is divided into input paths as follows: The first input
- path consists of the first lines of the path specified in the
- \meta{environment contents} until the \meta{length} of the first
- element of the \meta{decoration list} is reached. If this length
- is reached in the middle of a line, the line is broken up at this
- exact position. Then the second input path has the \meta{length}
- of the second element in the \meta{decoration list} and consists
- of the lines making up the following \meta{length} part of the
- path in the \meta{environment contents}, and so on.
-
- If the lengths in the \meta{decoration list}
- do not add up to the total length of the path in the
- \meta{environment contents}, either some decorations are dropped
- (if their lengths add up to more than the length of the
- \meta{environment contents}) or
- the input path is not fully used (if their lengths add up to less).
- \item
- The preexisting path is reinstalled.
- \item
- The decoration automata move along the input paths, thus creating
- (and possibly using) the output paths. These output paths extend
- the current path (unless they are used).
- \end{enumerate}
-
- Some important points should be noted regarding the use of this
- environment:
-
- \begin{itemize}
- \item
- If \meta{environment contents} does not begin with
- |\pgfpathmoveto|, the last known point on the preexisting path is
- assumed as the starting point.
- \item
- All except the last of any sequence of consecutive move-to commands
- in \meta{environment contents} are discarded.
- \item
- Any move-to commands at the end of \meta{environment contents} are
- ignored.
- \item
- Any close-path commands on the input path are interpreted as
- straight lines.
- Internally, something a little more complicated is going on,
- however, a closed path on the input path has no effect on the
- output path, other than causing the automaton to travel in a
- straight line towards the location of the last move-to command on
- the input path.
- \item
- Although tangent computations for the input path work with the
- last point on the preexisting path, no automatic move-to
- operations are issued for the output path.
- If an output path starts with a line-to or curve-to when the
- existing path is empty, an appropriate move-to command should be
- inserted before the decoration starts.
- \item
- If a decoration uses its own path, the first time this happens the
- preexisting path is part of the path that is used at this point.
- \end{itemize}
-
-Before the automata start to "work on" their respective inputs paths,
- \meta{before code} is
- executed. After the decoration automaton has finished, \meta{after
- code} is executed.
+ The \meta{environment contents} should contain commands for creating an
+ path. This path is the basis for the \emph{input paths} for the decorations
+ in the \meta{decoration list}. In detail, the following happens:
+ %
+ \begin{enumerate}
+ \item The preexisting unused path is saved.
+ \item The path commands specified in \meta{environment contents} are
+ executed and this resulting path is saved. The path is then divided
+ into different \emph{input paths} as follows: The format for each
+ item in \marg{decoration list} is
+ %
+ \begin{quote}
+ \marg{decoration}\marg{length}\opt{\marg{before code}\marg{after code}}
+ \end{quote}
+ %
+ The \meta{before code} and the \meta{after code} are optional. The
+ input path is divided into input paths as follows: The first input
+ path consists of the first lines of the path specified in the
+ \meta{environment contents} until the \meta{length} of the first
+ element of the \meta{decoration list} is reached. If this length is
+ reached in the middle of a line, the line is broken up at this
+ exact position. Then the second input path has the \meta{length} of
+ the second element in the \meta{decoration list} and consists of
+ the lines making up the following \meta{length} part of the path in
+ the \meta{environment contents}, and so on.
+
+ If the lengths in the \meta{decoration list} do not add up to the
+ total length of the path in the \meta{environment contents}, either
+ some decorations are dropped (if their lengths add up to more than
+ the length of the \meta{environment contents}) or the input path is
+ not fully used (if their lengths add up to less).
+ \item The preexisting path is reinstalled.
+ \item The decoration automata move along the input paths, thus creating
+ (and possibly using) the output paths. These output paths extend
+ the current path (unless they are used).
+ \end{enumerate}
+ Some important points should be noted regarding the use of this
+ environment:
+ %
+ \begin{itemize}
+ \item If \meta{environment contents} does not begin with
+ |\pgfpathmoveto|, the last known point on the preexisting path is
+ assumed as the starting point.
+ \item All except the last of any sequence of consecutive move-to
+ commands in \meta{environment contents} are discarded.
+ \item Any move-to commands at the end of \meta{environment contents}
+ are ignored.
+ \item Any close-path commands on the input path are interpreted as
+ straight lines. Internally, something a little more complicated is
+ going on, however, a closed path on the input path has no effect on
+ the output path, other than causing the automaton to travel in a
+ straight line towards the location of the last move-to command on
+ the input path.
+ \item Although tangent computations for the input path work with the
+ last point on the preexisting path, no automatic move-to operations
+ are issued for the output path. If an output path starts with a
+ line-to or curve-to when the existing path is empty, an appropriate
+ move-to command should be inserted before the decoration starts.
+ \item If a decoration uses its own path, the first time this happens
+ the preexisting path is part of the path that is used at this
+ point.
+ \end{itemize}
+
+ Before the automata start to "work on" their respective inputs paths,
+ \meta{before code} is executed. After the decoration automaton has
+ finished, \meta{after code} is executed.
+ %
\begin{codeexample}[]
\begin{tikzpicture}[decoration={segment length=5pt}]
\draw [help lines] grid (3,2);
@@ -641,12 +616,12 @@ Before the automata start to "work on" their respective inputs paths,
\end{tikzpicture}
\end{codeexample}
- When the lengths are evaluated, the dimension
- |\pgfdecoratedremainingdistance| holds the remaining distance on
- the entire decorated path, and |\pgfdecoratedpathlength| holds the
- total length of the path. Thus, it is possible to specify lengths
- like |\pgfdecoratedpathlength/3|.
-
+ When the lengths are evaluated, the dimension
+ |\pgfdecoratedremainingdistance| holds the remaining distance on the entire
+ decorated path, and |\pgfdecoratedpathlength| holds the total length of the
+ path. Thus, it is possible to specify lengths like
+ |\pgfdecoratedpathlength/3|.
+ %
\begin{codeexample}[]
\begin{tikzpicture}[decoration={segment length=5pt}]
\draw [help lines] grid (3,2);
@@ -663,20 +638,21 @@ Before the automata start to "work on" their respective inputs paths,
\end{tikzpicture}
\end{codeexample}
- When \meta{before code} is executed, the following macro is useful:
- \begin{command}{\pgfpointdecoratedpathfirst}
- Returns the point corresponding to the start of the current
- input path.
- \end{command}
- When \meta{after code} is executed, the following macro can be used:
- \begin{command}{\pgfpointdecoratedpathlast}
- Returns the point corresponding to the end of the current input
- path.
- \end{command}
- This means that if decorations do not use their own path, it is
- possible to do something with them and continue from the
- correct place.
-
+ When \meta{before code} is executed, the following macro is useful:
+ %
+ \begin{command}{\pgfpointdecoratedpathfirst}
+ Returns the point corresponding to the start of the current input path.
+ \end{command}
+ %
+ When \meta{after code} is executed, the following macro can be used:
+ %
+ \begin{command}{\pgfpointdecoratedpathlast}
+ Returns the point corresponding to the end of the current input path.
+ \end{command}
+ %
+ This means that if decorations do not use their own path, it is possible to
+ do something with them and continue from the correct place.
+ %
\begin{codeexample}[]
\begin{tikzpicture}
\draw [help lines] grid (3,2);
@@ -706,88 +682,88 @@ Before the automata start to "work on" their respective inputs paths,
\pgfusepath{stroke}
\end{tikzpicture}
\end{codeexample}
-
- After the |{decoration}| environment has finished, the following
- macros are available:
-
- \begin{command}{\pgfdecorateexistingpath}
- The preexisting path before the environment was entered.
- \end{command}
-
- \begin{command}{\pgfdecoratedpath}
- The (total) input path (that is, the path created by the environment contents).
- \end{command}
-
- \begin{command}{\pgfdecorationpath}
- The output path. If the path is used, this macro contains only the
- last unused part of the output path.
- \end{command}
-
- \begin{command}{\pgfpointdecoratedpathlast}
- The final point of the input path.
- \end{command}
-
- \begin{command}{\pgfpointdecorationpathlast}
- The final point of the output path.
- \end{command}
-
- The following style is executed each time a decoration is used. You
- may use it to set up default options for decorations.
- \begin{stylekey}{/pgf/every decoration (initially \normalfont empty)}
- This style is executed for every decoration.
- \end{stylekey}
+
+ After the |{decoration}| environment has finished, the following macros are
+ available:
+
+ \begin{command}{\pgfdecorateexistingpath}
+ The preexisting path before the environment was entered.
+ \end{command}
+
+ \begin{command}{\pgfdecoratedpath}
+ The (total) input path (that is, the path created by the environment
+ contents).
+ \end{command}
+
+ \begin{command}{\pgfdecorationpath}
+ The output path. If the path is used, this macro contains only the last
+ unused part of the output path.
+ \end{command}
+
+ \begin{command}{\pgfpointdecoratedpathlast}
+ The final point of the input path.
+ \end{command}
+
+ \begin{command}{\pgfpointdecorationpathlast}
+ The final point of the output path.
+ \end{command}
+
+ The following style is executed each time a decoration is used. You may use
+ it to set up default options for decorations.
+ %
+ \begin{stylekey}{/pgf/every decoration (initially \normalfont empty)}
+ This style is executed for every decoration.
+ \end{stylekey}
\end{environment}
\begin{plainenvironment}{{pgfdecoration}\marg{name}}
- The plain-\TeX{} version of the |{pgfdecorate}| environment. % TODOsp: `pgfdecorate' right or `pgfdecoration'? really no idea
+ The plain-\TeX{} version of the |{pgfdecorate}| environment.
+ \todosp{`pgfdecorate' right or `pgfdecoration'? really no idea}
\end{plainenvironment}
\begin{contextenvironment}{{pgfdecoration}\marg{name}}
- The Con\TeX t version of the |{pgfdecoration}| environment.
+ The Con\TeX t version of the |{pgfdecoration}| environment.
\end{contextenvironment}
-For convenience, the following macros provide a ``shorthand''
-for decorations (internally, they all use the |{pgfdecoration}|
-environment).
+For convenience, the following macros provide a ``shorthand'' for decorations
+(internally, they all use the |{pgfdecoration}| environment).
\begin{command}{\pgfdecoratepath\marg{name}\marg{path commands}}
- Decorate the path described by \meta{path commands} with the
- decoration \meta{name}. This is equivalent to
+ Decorate the path described by \meta{path commands} with the decoration
+ \meta{name}. This is equivalent to
+ %
\begin{codeexample}[code only]
\pgfdecorate{{name}{\pgfdecoratedpathlength}
{\pgfdecoratebeforecode}{\pgfdecorateaftercode}}
// the path commands.
\endpgfdecorate
\end{codeexample}
+ %
\end{command}
\begin{command}{\pgfdecoratecurrentpath\marg{name}}
- Decorate the preexisting path with the decoration \meta{name}.
+ Decorate the preexisting path with the decoration \meta{name}.
\end{command}
-Both the above commands use the current definitions of the following
-macros:
+Both the above commands use the current definitions of the following macros:
\begin{command}{\pgfdecoratebeforecode}
- Code executed as \meta{before code}, see the description of
- |\pgfdecorate|.
+ Code executed as \meta{before code}, see the description of |\pgfdecorate|.
\end{command}
\begin{command}{\pgfdecorateaftercode}
- Code executed as \meta{after code}, see the description of
- |\pgfdecorate|.
+ Code executed as \meta{after code}, see the description of |\pgfdecorate|.
\end{command}
-It may sometimes be useful to add an additional transformation
-for each segment of a decoration. The following command allows
-you to define such a ``last minute transformation.''
+It may sometimes be useful to add an additional transformation for each segment
+of a decoration. The following command allows you to define such a ``last
+minute transformation''.
\begin{command}{\pgfsetdecorationsegmenttransformation\marg{code}}
- The \meta{code} will be executed at the very beginning of each
- segment. Note when applying multiple decorations, this will
- be reset between decorations, so it needs to be specified for
- each segment.
-
+ The \meta{code} will be executed at the very beginning of each segment.
+ Note when applying multiple decorations, this will be reset between
+ decorations, so it needs to be specified for each segment.
+ %
\begin{codeexample}[]
\begin{tikzpicture}
\draw [help lines] grid (3,2);
@@ -807,141 +783,133 @@ you to define such a ``last minute transformation.''
\pgfusepath{stroke}
\end{tikzpicture}
\end{codeexample}
+ %
\end{command}
-
-
\subsection{Meta-Decorations}
-
\label{section-base-meta-decorations}
-A meta-decoration provides an alternative way to decorate a path with
-multiple decorations. It is, in essence, an automaton that decorates
-an input path with decoration automatons. In general, however, the end
-effect is still that a path is decorated with other paths, and the input
-path should be thought of as being divided into sub-input-paths, each with
-their own decoration. Like ordinary decorations, a meta-decoration must be declared before it can be used.
+A meta-decoration provides an alternative way to decorate a path with multiple
+decorations. It is, in essence, an automaton that decorates an input path with
+decoration automatons. In general, however, the end effect is still that a path
+is decorated with other paths, and the input path should be thought of as being
+divided into sub-input-paths, each with their own decoration. Like ordinary
+decorations, a meta-decoration must be declared before it can be used.
+
\subsubsection{Declaring Meta-Decorations}
\begin{command}{\pgfdeclaremetadecorate\marg{name}\marg{initial state}\marg{states}}
-
- This command declares a new meta-decoration called \meta{name}. The
- \meta{states} argument contains a description of the meta-decoration
- automaton's states and the transitions between them. The
- \meta{initial state} is the state in which the automaton starts.
-
- The |\state| command is similar to the one found in
- decoration declarations, and takes the same form:
-
- \begin{command}{\state\marg{name}\oarg{options}\marg{code}}
- Declares the state \meta{name} inside the current meta-decoration
- automaton. Unlike decorations, states in meta-decorations are not
- executed within a group, which makes the persistent computation
- options superfluous. Consider using an initial state with
- |width=0pt| to do precalculations that could speed the execution
- of the meta-decoration.
-
- The \meta{options} are executed with the key path set to
- |/pgf/meta-decorations automaton/|, and the following keys are defined for
- this path:
-
- \begin{key}{/pgf/meta-decoration automaton/switch if less than=\meta{dimension}| to |\meta{new state}}
- This causes \pgfname\ to check whether the
- remaining distance to the end of the input path is less than
- \meta{dimension}, and, if so, to immediately switch to the state
- \meta{new state}. When this key is evaluated, the macro
- |\pgfmetadecoratedpathlength| will be defined as the total length of
- the decoration path, allowing for values such as
- |\pgfmetadecoratedpathlength/8|.
- \end{key}
-
- \begin{key}{/pgf/meta-decoration automaton/width=\meta{dimension}}
- As always, this option will cause an immediate switch to the
- state |final| if the remaining distance on the input path is less than
- \meta{dimension}.
-
- Otherwise, this option tells \pgfname\ the width of the
- ``meta-segment'', that is, the length of the sub-input-path
- which the decoration automaton specified in \meta{code} will decorate.
- \end{key}
-
- \begin{key}{/pgf/meta-decoration automaton/next state=\meta{new state}}
- After the code for a state has been executed, a state switch to
- \meta{new state} is performed. If this option is not given, the
- next state is the same as the current state.
- \end{key}
-
- The code in \meta{code} is quite different from the code in a
- decoration state. In almost all cases only the following three
- macros will be required:
-
- \begin{command}{\decoration\marg{name}}
- This sets the decoration for the current state to \meta{name}.
- If this command is omitted, the |moveto| decoration will be
- used.
- \end{command}
-
- \begin{command}{\beforedecoration\marg{before code}}
- Defines \meta{before code} as (typically) \pgfname{} commands to be
- executed before the decoration is applied to the current segment.
- This command can be omitted.
- If you wish to set up some decoration specific parameters
- such as segment length, or segment amplitude, then they
- can be set in \meta{before code}.
+ This command declares a new meta-decoration called \meta{name}. The
+ \meta{states} argument contains a description of the meta-decoration
+ automaton's states and the transitions between them. The \meta{initial
+ state} is the state in which the automaton starts.
+
+ The |\state| command is similar to the one found in decoration
+ declarations, and takes the same form:
+
+ \begin{command}{\state\marg{name}\oarg{options}\marg{code}} Declares the
+ state \meta{name} inside the current meta-decoration automaton. Unlike
+ decorations, states in meta-decorations are not executed within a
+ group, which makes the persistent computation options superfluous.
+ Consider using an initial state with |width=0pt| to do precalculations
+ that could speed the execution of the meta-decoration.
+
+ The \meta{options} are executed with the key path set to
+ |/pgf/meta-decorations automaton/|, and the following keys are defined
+ for this path:
+
+ \begin{key}{/pgf/meta-decoration automaton/switch if less than=\meta{dimension}| to |\meta{new state}}
+ This causes \pgfname\ to check whether the remaining distance to
+ the end of the input path is less than \meta{dimension}, and, if
+ so, to immediately switch to the state \meta{new state}. When this
+ key is evaluated, the macro |\pgfmetadecoratedpathlength| will be
+ defined as the total length of the decoration path, allowing for
+ values such as |\pgfmetadecoratedpathlength/8|.
+ \end{key}
+
+ \begin{key}{/pgf/meta-decoration automaton/width=\meta{dimension}}
+ As always, this option will cause an immediate switch to the state
+ |final| if the remaining distance on the input path is less than
+ \meta{dimension}.
+
+ Otherwise, this option tells \pgfname\ the width of the
+ ``meta-segment'', that is, the length of the sub-input-path which
+ the decoration automaton specified in \meta{code} will decorate.
+ \end{key}
+
+ \begin{key}{/pgf/meta-decoration automaton/next state=\meta{new state}}
+ After the code for a state has been executed, a state switch to
+ \meta{new state} is performed. If this option is not given, the
+ next state is the same as the current state.
+ \end{key}
+
+ The code in \meta{code} is quite different from the code in a
+ decoration state. In almost all cases only the following three macros
+ will be required:
+
+ \begin{command}{\decoration\marg{name}}
+ This sets the decoration for the current state to \meta{name}. If
+ this command is omitted, the |moveto| decoration will be used.
+ \end{command}
+
+ \begin{command}{\beforedecoration\marg{before code}}
+ Defines \meta{before code} as (typically) \pgfname{} commands to be
+ executed before the decoration is applied to the current segment.
+ This command can be omitted. If you wish to set up some decoration
+ specific parameters such as segment length, or segment amplitude,
+ then they can be set in \meta{before code}.
+ \end{command}
+
+ \begin{command}{\afterdecoration\marg{after code}}
+ Defines \meta{after code} as commands to be executed after the
+ decoration has been applied to the current segment. This command
+ can be omitted.
+ \end{command}
+
+ There are some macros that may be useful when creating meta-decorations
+ (note that they are all macros):
+
+ \begin{command}{\pgfpointmetadecoratedpathfirst}
+ When the \meta{before code} is executed, this macro stores the
+ first point on the current sub-input-path.
+ \end{command}
+
+ \begin{command}{\pgfpointmetadecoratedpathlast}
+ When the \meta{after code} is executed, this macro stores the last
+ point on the current sub-input-path.
+ \end{command}
+
+ \begin{command}{\pgfmetadecoratedpathlength}
+ The entire length of the entire input path.
+ \end{command}
+
+ \begin{command}{\pgfmetadecoratedcompleteddistance}
+ The completed distance on the entire input path.
+ \end{command}
+
+ \begin{command}{\pgfmetadecoratedremainingdistance}
+ The remaining distance on the entire input path.
+ \end{command}
+
+ \begin{command}{\pgfmetadecoratedinputsegmentcompleteddistance}
+ The completed distance on the current input segment of the entire
+ input path.
+ \end{command}
+
+ \begin{command}{\pgfmetadecoratedinputsegmentremainingdistance}
+ The remaining distance on the current input segment of the entire
+ input path.
+ \end{command}
\end{command}
- \begin{command}{\afterdecoration\marg{after code}}
- Defines \meta{after code} as commands to be executed after the
- decoration has been applied to the current segment.
- This command can be omitted.
- \end{command}
-
- There are some macros that may be useful when creating
- meta-decorations (note that they are all macros):
-
- \begin{command}{\pgfpointmetadecoratedpathfirst}
- When the \meta{before code} is executed,
- this macro stores the first point on the current
- sub-input-path.
- \end{command}
-
- \begin{command}{\pgfpointmetadecoratedpathlast}
- When the \meta{after code} is executed,
- this macro stores the last point on the current
- sub-input-path.
- \end{command}
-
- \begin{command}{\pgfmetadecoratedpathlength}
- The entire length of the entire input path.
- \end{command}
-
- \begin{command}{\pgfmetadecoratedcompleteddistance}
- The completed distance on the entire input path.
- \end{command}
-
- \begin{command}{\pgfmetadecoratedremainingdistance}
- The remaining distance on the entire input path.
- \end{command}
-
- \begin{command}{\pgfmetadecoratedinputsegmentcompleteddistance}
- The completed distance on the current input segment of the entire
- input path.
- \end{command}
-
- \begin{command}{\pgfmetadecoratedinputsegmentremainingdistance}
- The remaining distance on the current input segment of the entire
- input path.
- \end{command}
- \end{command}
-
- Here is a complete example of a meta-decoration:
-
+ Here is a complete example of a meta-decoration:
+ %
\begin{codeexample}[]
\pgfdeclaremetadecoration{arrows}{initial}{
\state{initial}[width=0pt, next state=arrow]
- {
+ {
\pgfmathdivide{100}{\pgfmetadecoratedpathlength}
\let\factor\pgfmathresult
\pgfsetlinewidth{1pt}
@@ -958,20 +926,20 @@ their own decoration. Like ordinary decorations, a meta-decoration must be decla
\pgfmathparse{\pgfmetadecoratedcompleteddistance*\factor}
\pgfsetcolor{red!\pgfmathresult!yellow}
\pgfpathmoveto{\pgfpointmetadecoratedpathfirst}
- }
+ }
}
\state{zigzag}[width=\pgfmetadecorationsegmentlength/3, next state=end arrow]
{
- \decoration{zigzag}
+ \decoration{zigzag}
}
\state{end arrow}[width=\pgfmetadecorationsegmentlength/3, next state=move]
{
\decoration{curveto}
\beforedecoration{\pgfpathmoveto{\pgfpointmetadecoratedpathfirst}}
\afterdecoration
- {
+ {
\pgfsetarrowsend{to}
- \pgfusepath{stroke}
+ \pgfusepath{stroke}
}
}
\state{move}[width=\pgfmetadecorationsegmentlength/2, next state=arrow]{}
@@ -984,7 +952,7 @@ their own decoration. Like ordinary decorations, a meta-decoration must be decla
.. controls (0,-6) and (3,-6) .. (3,-8)
.. controls (3,-10) and (0,-10) .. (0,-8);
\end{codeexample}
-
+ %
\end{command}
@@ -995,18 +963,18 @@ There are no predefined meta-decorations loaded with \pgfname{}.
\subsubsection{Using Meta-Decorations}
-Using meta-decorations is ``simpler'' than using decorations, because
-you can only use one meta-decoration per path.
+Using meta-decorations is ``simpler'' than using decorations, because you can
+only use one meta-decoration per path.
\begin{environment}{{pgfmetadecoration}\marg{name}}
- This environment decorates the input path described in
- \meta{environment contents}, with the meta-decoration \meta{name}.
+ This environment decorates the input path described in \meta{environment
+ contents}, with the meta-decoration \meta{name}.
\end{environment}
\begin{plainenvironment}{{pgfmetadecoration}\marg{name}}
- The plain \TeX{} version of the |{pgfmetadecoration}| environment.
+ The plain \TeX{} version of the |{pgfmetadecoration}| environment.
\end{plainenvironment}
\begin{contextenvironment}{{pgfmetadecoration}\marg{name}}
- The Con\TeX t version of the |{pgfmetadecoration}| environment.
+ The Con\TeX t version of the |{pgfmetadecoration}| environment.
\end{contextenvironment}