summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-paths.tex
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2019-01-05 22:40:38 +0000
committerKarl Berry <karl@freefriends.org>2019-01-05 22:40:38 +0000
commit22536bb2b5257046d271b1eaa11b4a275d5ec041 (patch)
tree2500eaf5c26b11e00ebd33a64fccfa332cd5a66c /Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-paths.tex
parentcf794f0e2db6857972a9d48d4466a4f03a7057a0 (diff)
pgf (5jan19)
git-svn-id: svn://tug.org/texlive/trunk@49607 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-paths.tex')
-rw-r--r--Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-paths.tex1598
1 files changed, 820 insertions, 778 deletions
diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-paths.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-paths.tex
index 02456c9c869..340a5cef081 100644
--- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-paths.tex
+++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-paths.tex
@@ -7,104 +7,111 @@
%
% See the file doc/generic/pgf/licenses/LICENSE for more details.
+
\section{Syntax for Path Specifications}
\label{section-paths}
-A \emph{path} is a series of straight and curved line segments. It is
-specified following a |\path| command and the specification must
-follow a special syntax, which is described in the subsections of the
-present section.
-
+A \emph{path} is a series of straight and curved line segments. It is specified
+following a |\path| command and the specification must follow a special syntax,
+which is described in the subsections of the present section.
\begin{command}{\path\meta{specification}|;|}
- This command is available only inside a |{tikzpicture}| environment.
-
- The \meta{specification} is a long stream of \emph{path
- operations}. Most of these path operations tell \tikzname\ how the path
- is built. For example, when you write |--(0,0)|, you use a
- \emph{line-to operation} and it means ``continue the path from
- wherever you are to the origin.''
-
- At any point where \tikzname\ expects a path operation, you can also
- give some graphic options, which is a list of options in brackets,
- such as |[rounded corners]|. These options can have different
- effects:
- \begin{enumerate}
- \item
- Some options take ``immediate'' effect and apply to all subsequent
- path operations on the path. For example, the |rounded corners|
- option will round all following corners, but not the corners
- ``before'' and if the |sharp corners| is given later on the path
- (in a new set of brackets), the rounding effect will end.
-
+ This command is available only inside a |{tikzpicture}| environment.
+
+ The \meta{specification} is a long stream of \emph{path operations}. Most
+ of these path operations tell \tikzname\ how the path is built. For
+ example, when you write |--(0,0)|, you use a \emph{line-to operation} and
+ it means ``continue the path from wherever you are to the origin''.
+
+ At any point where \tikzname\ expects a path operation, you can also give
+ some graphic options, which is a list of options in brackets, such as
+ |[rounded corners]|. These options can have different effects:
+ %
+ \begin{enumerate}
+ \item Some options take ``immediate'' effect and apply to all
+ subsequent path operations on the path. For example, the
+ |rounded corners| option will round all following corners, but not
+ the corners ``before'' and if the |sharp corners| is given later on
+ the path (in a new set of brackets), the rounding effect will end.
+ %
\begin{codeexample}[]
\tikz \draw (0,0) -- (1,1)
[rounded corners] -- (2,0) -- (3,1)
[sharp corners] -- (3,0) -- (2,1);
\end{codeexample}
- Another example are the transformation options, which also apply
- only to subsequent coordinates.
- \item
- The options that have immediate effect can be ``scoped'' by
- putting part of a path in curly braces. For example, the above
- example could also be written as follows:
-
+ %
+ Another example are the transformation options, which also apply
+ only to subsequent coordinates.
+ \item The options that have immediate effect can be ``scoped'' by
+ putting part of a path in curly braces. For example, the above
+ example could also be written as follows:
+ %
\begin{codeexample}[]
\tikz \draw (0,0) -- (1,1)
{[rounded corners] -- (2,0) -- (3,1)}
-- (3,0) -- (2,1);
\end{codeexample}
- \item
- Some options only apply to the path as a whole. For example, the
- |color=| option for determining the color used for, say, drawing
- the path always applies to all parts of the path. If several
- different colors are given for different parts of the path, only
- the last one (on the outermost scope) ``wins'':
-
+ %
+ \item Some options only apply to the path as a whole. For example,
+ the |color=| option for determining the color used for, say,
+ drawing the path always applies to all parts of the path. If
+ several different colors are given for different parts of the
+ path, only the last one (on the outermost scope) ``wins'':
+ %
\begin{codeexample}[]
\tikz \draw (0,0) -- (1,1)
[color=red] -- (2,0) -- (3,1)
[color=blue] -- (3,0) -- (2,1);
\end{codeexample}
- Most options are of this type. In the above example, we would have
- had to ``split up'' the path into several |\path| commands:
+ Most options are of this type. In the above example, we would
+ have had to ``split up'' the path into several |\path| commands:
+ %
\begin{codeexample}[]
\tikz{\draw (0,0) -- (1,1);
\draw [color=red] (2,0) -- (3,1);
\draw [color=blue] (3,0) -- (2,1);}
\end{codeexample}
- \end{enumerate}
-
- By default, the |\path| command does ``nothing'' with the
- path, it just ``throws it away.'' Thus, if you write
- |\path(0,0)--(1,1);|, nothing is drawn
- in your picture. The only effect is that the area occupied by the
- picture is (possibly) enlarged so that the path fits inside the
- area. To actually ``do'' something with the path, an option like
- |draw| or |fill| must be given somewhere on the path. Commands like
- |\draw| do this implicitly.
-
- Finally, it is also possible to give \emph{node specifications} on a
- path. Such specifications can come at different locations, but they
- are always allowed when a normal path operation could follow. A node
- specification starts with |node|. Basically, the effect is to
- typeset the node's text as normal \TeX\ text and to place
- it at the ``current location'' on the path. The details are explained
- in Section~\ref{section-nodes}.
-
- Note, however, that the nodes are \emph{not} part of the path in any
- way. Rather, after everything has been done with the path what is
- specified by the path options (like filling and drawing the path due
- to a |fill| and a |draw| option somewhere in the
- \meta{specification}), the nodes are added in a post-processing
- step.
-
- The following style influences scopes:
- \begin{stylekey}{/tikz/every path (initially \normalfont empty)}
- This style is installed at the beginning of every path. This can
- be useful for (temporarily) adding, say, the |draw| option to
- everything in a scope.
+ \end{enumerate}
+
+ By default, the |\path| command does ``nothing'' with the path, it just
+ ``throws it away''. Thus, if you write |\path(0,0)--(1,1);|, nothing is
+ drawn in your picture. The only effect is that the area occupied by the
+ picture is (possibly) enlarged so that the path fits inside the area. To
+ actually ``do'' something with the path, an option like |draw| or |fill|
+ must be given somewhere on the path. Commands like |\draw| do this
+ implicitly.
+
+ Finally, it is also possible to give \emph{node specifications} on a path.
+ Such specifications can come at different locations, but they are always
+ allowed when a normal path operation could follow. A node specification
+ starts with |node|. Basically, the effect is to typeset the node's text as
+ normal \TeX\ text and to place it at the ``current location'' on the path.
+ The details are explained in Section~\ref{section-nodes}.
+
+ Note, however, that the nodes are \emph{not} part of the path in any way.
+ Rather, after everything has been done with the path what is specified by
+ the path options (like filling and drawing the path due to a |fill| and a
+ |draw| option somewhere in the \meta{specification}), the nodes are added
+ in a post-processing step.
+
+ \begin{key}{/tikz/name=\meta{path name}}
+ Assigns a name to the path for reference (specifically, for reference
+ in animations; for reference in intersections, use the |name path|
+ command, which has a different purpose, see the |intersections| library
+ for details). Since the name is a ``high-level'' name (drivers never
+ know of it), you can use spaces, number, letters, or whatever you like
+ when naming a path, but the name may \emph{not} contain any punctuation
+ like a dot, a comma, or a colon.
+ \end{key}
+
+ The following style influences scopes:
+ %
+ \begin{stylekey}{/tikz/every path (initially \normalfont empty)}
+ This style is installed at the beginning of every path. This can be
+ useful for (temporarily) adding, say, the |draw| option to everything
+ in a scope.
+ %
\begin{codeexample}[]
\begin{tikzpicture}
[fill=yellow!80!black, % only sets the color
@@ -113,92 +120,89 @@ present section.
\shade (2,0) rectangle +(1,1);
\end{tikzpicture}
\end{codeexample}
- \end{stylekey}
-
+ \end{stylekey}
\end{command}
-
\begin{key}{/tikz/insert path=\meta{path}}
- This key can be used inside an option to add something to the
- current path. This is mostly useful for defining styles that create
- graphic contents. This option should be used with care, for instance
- it should not be used as an argument of, say, a |node|. In the
- following example, we use a style to add little circles to a path.
+ This key can be used inside an option to add something to the current path.
+ This is mostly useful for defining styles that create graphic contents.
+ This option should be used with care, for instance it should not be used as
+ an argument of, say, a |node|. In the following example, we use a style to
+ add little circles to a path.
+ %
\begin{codeexample}[]
\tikz [c/.style={insert path={circle[radius=2pt]}}]
\draw (0,0) -- (1,1) [c] -- (3,2) [c];
\end{codeexample}
- The effect is the same as of
- |(0,0) -- (1,1) circle[radius=2pt] -- (3,2) circle[radius=2pt]|.
+ %
+ The effect is the same as of
+ |(0,0) -- (1,1) circle[radius=2pt] -- (3,2) circle[radius=2pt]|.
\end{key}
The following options are for experts only:
\begin{key}{/tikz/append after command=\meta{path}}
- Some of the path commands described in the following sections take
- optional arguments. For these commands, when you use this key inside
- these options, the \meta{path} will be inserted \emph{after} the
- path command is done. For instance, when you give this command in
- the option list of a node, the \meta{path} will be added after the
- node. This is used by, for instance, the |label| option to allow you
- to specify a label in the option list of a node, but have this
- |label| cause a node to be added after another node.
+ Some of the path commands described in the following sections take optional
+ arguments. For these commands, when you use this key inside these options,
+ the \meta{path} will be inserted \emph{after} the path command is done. For
+ instance, when you give this command in the option list of a node, the
+ \meta{path} will be added after the node. This is used by, for instance,
+ the |label| option to allow you to specify a label in the option list of a
+ node, but have this |label| cause a node to be added after another node.
+ %
\begin{codeexample}[]
\tikz \draw node [append after command={(foo)--(1,1)},draw] (foo){foo};
\end{codeexample}
- If this key is called multiple times, the effects accumulate, that
- is, all of the paths are added in the order to keys were found.
+ %
+ If this key is called multiple times, the effects accumulate, that is, all
+ of the paths are added in the order to keys were found.
\end{key}
\begin{key}{/tikz/prefix after command=\meta{path}}
- Works like |append after command|, only the accumulation order is
- inverse: The \meta{path} is added before any earlier paths added
- using either |append after command| or |prefix after command|.
+ Works like |append after command|, only the accumulation order is inverse:
+ The \meta{path} is added before any earlier paths added using either
+ |append after command| or |prefix after command|.
\end{key}
-
\subsection{The Move-To Operation}
-The perhaps simplest operation is the move-to operation, which is
-specified by just giving a coordinate where a path operation is
-expected.
+The perhaps simplest operation is the move-to operation, which is specified by
+just giving a coordinate where a path operation is expected.
\begin{pathoperation}[noindex]{}{\meta{coordinate}}
- \index{empty@\protect\meta{empty} path operation}%
- \index{Path operations!empty@\protect\texttt{\meta{empty}}}%
- The move-to operation normally starts a path at a certain
- point. This does not cause a line segment to be created, but it
- specifies the starting point of the next segment. If a path is
- already under construction, that is, if several segments have
- already been created, a move-to operation will start a new part of the
- path that is not connected to any of the previous segments.
-
+ \index{empty@\protect\meta{empty} path operation}%
+ \index{Path operations!empty@\protect\texttt{\meta{empty}}}%
+ The move-to operation normally starts a path at a certain point. This does
+ not cause a line segment to be created, but it specifies the starting point
+ of the next segment. If a path is already under construction, that is, if
+ several segments have already been created, a move-to operation will start
+ a new part of the path that is not connected to any of the previous
+ segments.
+ %
\begin{codeexample}[]
\begin{tikzpicture}
\draw (0,0) --(2,0) (0,1) --(2,1);
\end{tikzpicture}
\end{codeexample}
- In the specification |(0,0) --(2,0) (0,1) --(2,1)| two move-to
- operations are specified: |(0,0)| and |(0,1)|. The other two
- operations, namely |--(2,0)| and |--(2,1)| are line-to operations,
- described next.
+ In the specification |(0,0) --(2,0) (0,1) --(2,1)| two move-to operations
+ are specified: |(0,0)| and |(0,1)|. The other two operations, namely
+ |--(2,0)| and |--(2,1)| are line-to operations, described next.
\end{pathoperation}
-There is special coordinate called |current subpath start| that is
-always at the position of the last move-to operation on the current
-path.
-
+There is special coordinate called |current subpath start| that is always at
+the position of the last move-to operation on the current path.
+%
\begin{codeexample}[]
\tikz [line width=2mm]
\draw (0,0) -- (1,0) -- (1,1)
-- (0,1) -- (current subpath start);
\end{codeexample}
-Note how in the above example the path is not closed (as |--cycle|
-would do). Rather, the line just starts and ends at the origin without
-being a closed path.
+Note how in the above example the path is not closed (as |--cycle| would do).
+Rather, the line just starts and ends at the origin without being a closed
+path.
\subsection{The Line-To Operation}
@@ -206,20 +210,20 @@ being a closed path.
\subsubsection{Straight Lines}
\begin{pathoperation}{--}{\meta{coordinate or cycle}}
- The line-to operation extends the current path from the current
- point in a straight line to the given \meta{coordinate} (the ``or
- cycle'' part is explained in a moment). The ``current
- point'' is the endpoint of the previous drawing operation or the point
- specified by a prior move-to operation.
-
- When a line-to operation is used and some path segment has just been
- constructed, for example by another line-to operation, the two line
- segments become joined. This means that if they are drawn, the point
- where they meet is ``joined'' smoothly. To appreciate the difference,
- consider the following two examples: In the left example, the path
- consists of two path segments that are not joined, but they happen to
- share a point, while in the right example a smooth join is shown.
-
+ The line-to operation extends the current path from the current point in a
+ straight line to the given \meta{coordinate} (the ``or cycle'' part is
+ explained in a moment). The ``current point'' is the endpoint of the
+ previous drawing operation or the point specified by a prior move-to
+ operation.
+
+ When a line-to operation is used and some path segment has just been
+ constructed, for example by another line-to operation, the two line
+ segments become joined. This means that if they are drawn, the point where
+ they meet is ``joined'' smoothly. To appreciate the difference, consider
+ the following two examples: In the left example, the path consists of two
+ path segments that are not joined, but they happen to share a point, while
+ in the right example a smooth join is shown.
+ %
\begin{codeexample}[]
\begin{tikzpicture}[line width=10pt]
\draw (0,0) --(1,1) (1,1) --(2,0);
@@ -228,18 +232,17 @@ being a closed path.
\end{tikzpicture}
\end{codeexample}
- Instead of a coordinate following the two minus signs, you can also
- use the text |cycle|. This causes the straight line from the current
- point to go to the last point specified by a move-to operation. Note
- that this need not be the beginning of the path. Furthermore, a
- smooth join is created between the first segment created after the
- last move-to operation and the straight line appended by the cycle
- operation.
-
- Consider the following example. In the left example, two triangles are
- created using three straight lines, but they are not joined at the
- ends. In the second example cycle operations are used.
-
+ Instead of a coordinate following the two minus signs, you can also use the
+ text |cycle|. This causes the straight line from the current point to go to
+ the last point specified by a move-to operation. Note that this need not be
+ the beginning of the path. Furthermore, a smooth join is created between
+ the first segment created after the last move-to operation and the straight
+ line appended by the cycle operation.
+
+ Consider the following example. In the left example, two triangles are
+ created using three straight lines, but they are not joined at the ends. In
+ the second example cycle operations are used.
+ %
\begin{codeexample}[]
\begin{tikzpicture}[line width=10pt]
\draw (0,0) -- (1,1) -- (1,0) -- (0,0) (2,0) -- (3,1) -- (3,0) -- (2,0);
@@ -247,31 +250,31 @@ being a closed path.
\useasboundingbox (0,1.5); % make bounding box higher
\end{tikzpicture}
\end{codeexample}
+ %
\end{pathoperation}
-Writing |cycle| instead of a coordinate at the end of a path operation
-is possible with all path operations that end with a coordinate (such
-as |--| or |..| or |sin| or |grid|, but not |graph| or |plot|).
-In all cases, the effect is that the coordinate of the last moveto is
-used as the coordinate expected by the path operation and that a
-smooth join is added. (What actually happens that the text |cycle|
-used with any path operation other than |--| gets replaced by
+Writing |cycle| instead of a coordinate at the end of a path operation is
+possible with all path operations that end with a coordinate (such as |--| or
+|..| or |sin| or |grid|, but not |graph| or |plot|). In all cases, the effect
+is that the coordinate of the last moveto is used as the coordinate expected by
+the path operation and that a smooth join is added. (What actually happens that
+the text |cycle| used with any path operation other than |--| gets replaced by
|(current subpath start)--cycle|.)
\subsubsection{Horizontal and Vertical Lines}
-Sometimes you want to connect two points via straight lines that are
-only horizontal and vertical. For this, you can use two path
-construction operations.
+Sometimes you want to connect two points via straight lines that are only
+horizontal and vertical. For this, you can use two path construction
+operations.
{\catcode`\|=12
\begin{pathoperation}[noindex]{-|}{\meta{coordinate or cycle}}
- \index{--1@\protect\texttt{-\protect\pgfmanualbar} path operation}%
- \index{Path operations!--1@\protect\texttt{-\protect\pgfmanualbar}}%
- \pgfmanualpdflabel[\catcode`\|=12 ]{-|}{}%
- This operation means ``first horizontal, then vertical.''
-
+ \index{--1@\protect\texttt{-\protect\pgfmanualbar} path operation}%
+ \index{Path operations!--1@\protect\texttt{-\protect\pgfmanualbar}}%
+ \pgfmanualpdflabel[\catcode`\|=12 ]{-|}{}%
+ This operation means ``first horizontal, then vertical''.
+ %
\begin{codeexample}[]
\begin{tikzpicture}
\draw (0,0) node(a) [draw] {A} (1,1) node(b) [draw] {B};
@@ -279,44 +282,44 @@ construction operations.
\draw[color=red] (a.east) -| (2,1.5) -| (b.north);
\end{tikzpicture}
\end{codeexample}
- Instead of a coordinate you can also write \verb!cycle! to close the
- path:
+ %
+ Instead of a coordinate you can also write \verb!cycle! to close the path:
+ %
\begin{codeexample}[]
\begin{tikzpicture}[ultra thick]
\draw (0,0) -- (1,1) -| cycle;
\end{tikzpicture}
\end{codeexample}
\end{pathoperation}
+
\begin{pathoperation}[noindex]{|-}{\meta{coordinate or cycle}}
- \index{--2@\protect\texttt{\protect\pgfmanualbar-} path operation}%
- \index{Path operations!--2@\protect\texttt{\protect\pgfmanualbar-}}%
- \pgfmanualpdflabel[\catcode`\|=12 ]{|-}{}%
- This operations means ``first vertical, then horizontal.''
+ \index{--2@\protect\texttt{\protect\pgfmanualbar-} path operation}%
+ \index{Path operations!--2@\protect\texttt{\protect\pgfmanualbar-}}%
+ \pgfmanualpdflabel[\catcode`\|=12 ]{|-}{}%
+ This operations means ``first vertical, then horizontal''.
\end{pathoperation}
}
\subsection{The Curve-To Operation}
-The curve-to operation allows you to extend a path using a B\'ezier
-curve.
+The curve-to operation allows you to extend a path using a Bézier curve.
\begin{pathoperation}{..}{\declare{|controls|}\meta{c}\opt{|and|\meta{d}}\declare{|..|\meta{y or cycle}}}
- This operation extends the current path from the current
- point, let us call it $x$, via a curve to a point~$y$ (if, instead
- of a coordinate you say |cycle| at the end, $y$ will be the
- coordinate of the last move-to operation).
- The curve is a cubic B\'ezier curve. For such a curve,
- apart from $y$, you also specify two control points $c$ and $d$. The
- idea is that the curve starts at $x$, ``heading'' in the direction
- of~$c$. Mathematically spoken, the tangent of the curve at $x$ goes
- through $c$. Similarly, the curve ends at $y$, ``coming from'' the
- other control point,~$d$. The larger the distance between $x$ and~$c$
- and between $d$ and~$y$, the larger the curve will be.
-
- If the ``|and|\meta{d}'' part is not given, $d$ is assumed to be
- equal to $c$.
-
+ This operation extends the current path from the current point, let us call
+ it $x$, via a curve to a point~$y$ (if, instead of a coordinate you say
+ |cycle| at the end, $y$ will be the coordinate of the last move-to
+ operation). The curve is a cubic Bézier curve. For such a curve, apart
+ from $y$, you also specify two control points $c$ and $d$. The idea is that
+ the curve starts at $x$, ``heading'' in the direction of~$c$.
+ Mathematically spoken, the tangent of the curve at $x$ goes through $c$.
+ Similarly, the curve ends at $y$, ``coming from'' the other control
+ point,~$d$. The larger the distance between $x$ and~$c$ and between $d$
+ and~$y$, the larger the curve will be.
+
+ If the ``|and|\meta{d}'' part is not given, $d$ is assumed to be equal to
+ $c$.
+ %
\begin{codeexample}[]
\begin{tikzpicture}
\draw[line width=10pt] (0,0) .. controls (1,1) .. (4,0)
@@ -331,10 +334,10 @@ curve.
\end{tikzpicture}
\end{codeexample}
- As with the line-to operation, it makes a difference whether two curves
- are joined because they resulted from consecutive curve-to or line-to
- operations, or whether they just happen to have a common (end) point:
-
+ As with the line-to operation, it makes a difference whether two curves are
+ joined because they resulted from consecutive curve-to or line-to
+ operations, or whether they just happen to have a common (end) point:
+ %
\begin{codeexample}[]
\begin{tikzpicture}[line width=10pt]
\draw (0,0) -- (1,1) (1,1) .. controls (1,0) and (2,0) .. (2,0);
@@ -342,21 +345,20 @@ curve.
(0,0) -- (1,1) .. controls (1,0) and (2,0) .. (2,0);
\end{tikzpicture}
\end{codeexample}
+ %
\end{pathoperation}
-
\subsection{The Rectangle Operation}
-A rectangle can obviously be created using four straight lines and a
-cycle operation. However, since rectangles are needed so often, a
-special syntax is available for them.
+A rectangle can obviously be created using four straight lines and a cycle
+operation. However, since rectangles are needed so often, a special syntax is
+available for them.
\begin{pathoperation}{rectangle}{\meta{corner or cycle}}
- When this operation is used, one corner will be the current point,
- another corner is given by \meta{corner}, which becomes the new
- current point.
-
+ When this operation is used, one corner will be the current point, another
+ corner is given by \meta{corner}, which becomes the new current point.
+ %
\begin{codeexample}[]
\begin{tikzpicture}
\draw (0,0) rectangle (1,1);
@@ -364,29 +366,30 @@ special syntax is available for them.
\end{tikzpicture}
\end{codeexample}
- Just for consistency, you can also use |cycle| instead of a
- coordinate, but it is a bit unclear what use this might have.
+ Just for consistency, you can also use |cycle| instead of a coordinate, but
+ it is a bit unclear what use this might have.
\end{pathoperation}
\subsection{Rounding Corners}
-All of the path construction operations mentioned up to now are
-influenced by the following option:
-\begin{key}{/tikz/rounded corners=\meta{inset} (default 4pt)}
- When this option is in force, all corners (places where a line is
- continued either via line-to or a curve-to operation) are replaced by
- little arcs so that the corner becomes smooth.
+All of the path construction operations mentioned up to now are influenced by
+the following option:
+\begin{key}{/tikz/rounded corners=\meta{inset} (default 4pt)}
+ When this option is in force, all corners (places where a line is continued
+ either via line-to or a curve-to operation) are replaced by little arcs so
+ that the corner becomes smooth.
+ %
\begin{codeexample}[]
\tikz \draw [rounded corners] (0,0) -- (1,1)
-- (2,0) .. controls (3,1) .. (4,0);
\end{codeexample}
- The \meta{inset} describes how big the corner is. Note that the
- \meta{inset} is \emph{not} scaled along if you use a scaling option
- like |scale=2|.
-
+ The \meta{inset} describes how big the corner is. Note that the
+ \meta{inset} is \emph{not} scaled along if you use a scaling option like
+ |scale=2|.
+ %
\begin{codeexample}[]
\begin{tikzpicture}
\draw[color=gray,very thin] (10pt,15pt) circle[radius=10pt];
@@ -394,10 +397,9 @@ influenced by the following option:
\end{tikzpicture}
\end{codeexample}
- You can switch the rounded corners on and off ``in the middle of
- path'' and different corners in the same path can have different
- corner radii:
-
+ You can switch the rounded corners on and off ``in the middle of path'' and
+ different corners in the same path can have different corner radii:
+ %
\begin{codeexample}[]
\begin{tikzpicture}
\draw (0,0) [rounded corners=10pt] -- (1,1) -- (2,1)
@@ -406,65 +408,66 @@ influenced by the following option:
\end{tikzpicture}
\end{codeexample}
-Here is a rectangle with rounded corners:
+ Here is a rectangle with rounded corners:
+ %
\begin{codeexample}[]
\tikz \draw[rounded corners=1ex] (0,0) rectangle (20pt,2ex);
\end{codeexample}
- You should be aware, that there are several pitfalls when using this
- option. First, the rounded corner will only be an arc (part of a
- circle) if the angle is $90^\circ$. In other cases, the rounded
- corner will still be round, but ``not as nice.''
+ You should be aware, that there are several pitfalls when using this
+ option. First, the rounded corner will only be an arc (part of a circle) if
+ the angle is $90^\circ$. In other cases, the rounded corner will still be
+ round, but ``not as nice''.
- Second, if there are very short line segments in a path, the
- ``rounding'' may cause inadvertent effects. In such case it may be
- necessary to temporarily switch off the rounding using
- |sharp corners|.
+ Second, if there are very short line segments in a path, the ``rounding''
+ may cause inadvertent effects. In such case it may be necessary to
+ temporarily switch off the rounding using |sharp corners|.
\end{key}
\begin{key}{/tikz/sharp corners}
- This options switches off any rounding on subsequent corners of the
- path.
+ This options switches off any rounding on subsequent corners of the path.
\end{key}
-
\subsection{The Circle and Ellipse Operations}
-Circles and ellipses are common path elements for which there is a
-special path operation.
+Circles and ellipses are common path elements for which there is a special path
+operation.
\begin{pathoperation}{circle}{\opt{|[|\meta{options}|]|}}
- This command adds a circle to the current path where the center of
- the circle is the current point by default, but you can use the |at|
- option to change this. The new current point of the path
- will be (typically just remain) the center of the circle.
-
- The radius of the circle is specified using the following options:
- \begin{key}{/tikz/x radius=\meta{value}}
- Sets the horizontal radius of the circle (which, when this value
- is different form the vertical radius, is actually an
- ellipse). The \meta{value} may either be a dimension or a
- dimensionless number. In the latter case, the number is
- interpreted in the $xy$-coordinate system (if the $x$-unit is set
- to, say, |2cm|, then |x radius=3| will have the same effect as
- |x radius=6cm|).
- \end{key}
- \begin{key}{/tikz/y radius=\meta{value}}
- Works like the |x radius|.
- \end{key}
- \begin{key}{/tikz/radius=\meta{value}}
- Sets the |x radius| and |y radius| simultaneously.
- \end{key}
- \begin{key}{/tikz/at=\meta{coordinate}}
- If this option is explicitly set inside the \meta{options} (or
- indirectly via the |every circle| style), the \meta{coordinate} is
- used as the center of the circle instead of the current
- point. Setting |at| to some value in an enclosing scope has no
- effect.
- \end{key}
- The \meta{options} may also contain additional options like, say, a
- |rotate| or |scale|, that will only have an effect on the circle.
+ This command adds a circle to the current path where the center of the
+ circle is the current point by default, but you can use the |at| option to
+ change this. The new current point of the path will be (typically just
+ remain) the center of the circle.
+
+ The radius of the circle is specified using the following options:
+ %
+ \begin{key}{/tikz/x radius=\meta{value}}
+ Sets the horizontal radius of the circle (which, when this value is
+ different form the vertical radius, is actually an ellipse). The
+ \meta{value} may either be a dimension or a dimensionless number. In
+ the latter case, the number is interpreted in the $xy$-coordinate
+ system (if the $x$-unit is set to, say, |2cm|, then |x radius=3| will
+ have the same effect as |x radius=6cm|).
+ \end{key}
+ %
+ \begin{key}{/tikz/y radius=\meta{value}}
+ Works like the |x radius|.
+ \end{key}
+ %
+ \begin{key}{/tikz/radius=\meta{value}}
+ Sets the |x radius| and |y radius| simultaneously.
+ \end{key}
+ %
+ \begin{key}{/tikz/at=\meta{coordinate}}
+ If this option is explicitly set inside the \meta{options} (or
+ indirectly via the |every circle| style), the \meta{coordinate} is used
+ as the center of the circle instead of the current point. Setting |at|
+ to some value in an enclosing scope has no effect.
+ \end{key}
+ The \meta{options} may also contain additional options like, say, a
+ |rotate| or |scale|, that will only have an effect on the circle.
+ %
\begin{codeexample}[]
\begin{tikzpicture}
\draw (1,0) circle [radius=1.5];
@@ -472,88 +475,92 @@ special path operation.
\end{tikzpicture}
\end{codeexample}
- It is possible to set the |radius| also in some enclosing scope, in
- this case the options can be left out (but see the note below on
- what may follow):
+ It is possible to set the |radius| also in some enclosing scope, in this
+ case the options can be left out (but see the note below on what may
+ follow):
+ %
\begin{codeexample}[]
\begin{tikzpicture}[radius=2pt]
\draw (0,0) circle -- (1,1) circle -- ++(0,1) circle;
\end{tikzpicture}
\end{codeexample}
- The following style is used with every circle:
- \begin{stylekey}{/tikz/every circle}
- You can use this key to set up, say, a default radius for every
- circle. The key will also be used with the |ellipse| operation.
- \end{stylekey}
+ The following style is used with every circle:
+ %
+ \begin{stylekey}{/tikz/every circle}
+ You can use this key to set up, say, a default radius for every circle.
+ The key will also be used with the |ellipse| operation.
+ \end{stylekey}
- In case you feel that the names |radius| and |x radius| are too long
- for your taste, you can easily created shorter aliases:
+ In case you feel that the names |radius| and |x radius| are too long for
+ your taste, you can easily created shorter aliases:
+ %
\begin{codeexample}[code only]
\tikzset{r/.style={radius=#1},rx/.style={x radius=#1},ry/.style={y radius=#1}}
\end{codeexample}
- You can then say |circle [r=1cm]| or |circle [rx=1,ry=1.5]|. The
- reason \tikzname\ uses the longer names by default is that it
- encourages people to write more readable code.
-
- \emph{Note:} There also exists an older syntax for circles, where
- the radius of the circle is given in parentheses right after the
- |circle| command as in |circle (1pt)|. Although this syntax is a bit
- more succinct, it is harder to understand for readers of the code
- and the use of parentheses for something other than a coordinate is
- ill-chosen.
-
- \tikzname\ will use the following rule to determine whether the old
- or the normal syntax is used: If |circle| is directly followed by
- something that (expands to) an opening parenthesis, then the old
- syntax is used and inside these following parentheses there must be
- a single number or dimension representing a radius. In all other
- cases the new syntax is used.
+ %
+ You can then say |circle [r=1cm]| or |circle [rx=1,ry=1.5]|. The reason
+ \tikzname\ uses the longer names by default is that it encourages people to
+ write more readable code.
+
+ \emph{Note:} There also exists an older syntax for circles, where the
+ radius of the circle is given in parentheses right after the |circle|
+ command as in |circle (1pt)|. Although this syntax is a bit more succinct,
+ it is harder to understand for readers of the code and the use of
+ parentheses for something other than a coordinate is ill-chosen.
+
+ \tikzname\ will use the following rule to determine whether the old or the
+ normal syntax is used: If |circle| is directly followed by something that
+ (expands to) an opening parenthesis, then the old syntax is used and inside
+ these following parentheses there must be a single number or dimension
+ representing a radius. In all other cases the new syntax is used.
\end{pathoperation}
\begin{pathoperation}{ellipse}{|[|\meta{options}|]|}
- This command has exactly the same effect as |circle|. The older
- syntax for this command is |ellipse (|\meta{x radius} |and| \meta{y
- radius}|)|. As for the |circle| command, this syntax is not as
- good as the standard syntax.
+ This command has exactly the same effect as |circle|. The older syntax for
+ this command is |ellipse (|\meta{x radius} |and| \meta{y radius}|)|. As for
+ the |circle| command, this syntax is not as good as the standard syntax.
+ %
\begin{codeexample}[]
\begin{tikzpicture}
\draw [help lines] (0,0) grid (3,2);
\draw (1,1) ellipse [x radius=1cm,y radius=.5cm];
\end{tikzpicture}
\end{codeexample}
+ %
\end{pathoperation}
-
\subsection{The Arc Operation}
-The \emph{arc operation} allows you to add an arc to the current
-path.
+The \emph{arc operation} allows you to add an arc to the current path.
+%
\begin{pathoperation}{arc}{\oarg{options}}
- The |arc| operation adds a part of an ellipse to the current
- path. The radii of the ellipse are given by the values of |x radius|
- and |y radius|, which should be set in the \meta{options}. The arc
- will start at the current point and will end at the end of the
- arc. The arc will start and end at angles computed from the three
- keys |start angle|, |end angle|, and |delta angle|. Normally, the
- first two keys specify the start and end angle. However, in case one
- of them is empty, it is computed from the other key plus or minus
- the |delta angle|. In detail, if |end angle| is empty, it is set to
- the start angle plus the delta angle. If the start angle is missing,
- it is set to the end angle minus the delta angle. If all three keys
- are set, the delta angle is ignored.
- \begin{key}{/tikz/start angle=\meta{degrees}}
- Sets the start angle.
- \end{key}
- \begin{key}{/tikz/end angle=\meta{degrees}}
- Sets the end angle.
- \end{key}
- \begin{key}{/tikz/delta angle=\meta{degrees}}
- Sets the delta angle.
- \end{key}
-
- \begin{codeexample}[]
+ The |arc| operation adds a part of an ellipse to the current path. The
+ radii of the ellipse are given by the values of |x radius| and |y radius|,
+ which should be set in the \meta{options}. The arc will start at the
+ current point and will end at the end of the arc. The arc will start and
+ end at angles computed from the three keys |start angle|, |end angle|, and
+ |delta angle|. Normally, the first two keys specify the start and end
+ angle. However, in case one of them is empty, it is computed from the other
+ key plus or minus the |delta angle|. In detail, if |end angle| is empty, it
+ is set to the start angle plus the delta angle. If the start angle is
+ missing, it is set to the end angle minus the delta angle. If all three
+ keys are set, the delta angle is ignored.
+ %
+ \begin{key}{/tikz/start angle=\meta{degrees}}
+ Sets the start angle.
+ \end{key}
+ %
+ \begin{key}{/tikz/end angle=\meta{degrees}}
+ Sets the end angle.
+ \end{key}
+ %
+ \begin{key}{/tikz/delta angle=\meta{degrees}}
+ Sets the delta angle.
+ \end{key}
+
+\begin{codeexample}[]
\begin{tikzpicture}[radius=1cm]
\draw (0,0) arc[start angle=180, end angle=90]
-- (2,.5) arc[start angle=90, delta angle=-90];
@@ -575,49 +582,45 @@ path.
\end{tikzpicture}
\end{codeexample}
- There also exists a shorter syntax for the arc operation, namely
- |arc| begin directly followed by |(|\meta{start angle}|:|\meta{end
- angle}|:|\meta{radius}). However, this syntax is harder to read,
- so the normal syntax should be preferred in general.
+ There also exists a shorter syntax for the arc operation, namely |arc|
+ begin directly followed by
+ |(|\meta{start angle}|:|\meta{end angle}|:|\meta{radius}). However, this
+ syntax is harder to read, so the normal syntax should be preferred in
+ general.
\end{pathoperation}
\subsection{The Grid Operation}
-You can add a grid to the current path using the |grid| path
-operation.
+You can add a grid to the current path using the |grid| path operation.
\begin{pathoperation}{grid}{\opt{\oarg{options}}\meta{corner or cycle}}
- This operations adds a grid filling a rectangle whose two corners
- are given by \meta{corner} and by the previous coordinate. (Instead
- of a coordinate you can also say |cycle| to use the position of the
- last move-to as the corner coordinate, but it not very natural to
- do so.) corner Thus, the
- typical way in which a grid is drawn is |\draw (1,1) grid (3,3);|,
- which yields a grid filling the rectangle whose corners are at
- $(1,1)$ and $(3,3)$. All coordinate transformations apply to the
- grid.
-
+ This operations adds a grid filling a rectangle whose two corners are given
+ by \meta{corner} and by the previous coordinate. (Instead of a coordinate
+ you can also say |cycle| to use the position of the last move-to as the
+ corner coordinate, but it not very natural to do so.) corner Thus, the
+ typical way in which a grid is drawn is |\draw (1,1) grid (3,3);|, which
+ yields a grid filling the rectangle whose corners are at $(1,1)$ and
+ $(3,3)$. All coordinate transformations apply to the grid.
+ %
\begin{codeexample}[]
\tikz[rotate=30] \draw[step=1mm] (0,0) grid (2,2);
\end{codeexample}
- The \meta{options}, which are local to the |grid| operation, can be
- used to influence the appearance of the grid. The stepping of the
- grid is governed by the following options:
-
-\begin{key}{/tikz/step=\meta{number or dimension or coordinate}
- (initially 1cm)}
- Sets the stepping in both the
- $x$ and $y$-direction. If a dimension is provided, this is used
- directly. If a number is provided, this number is interpreted in the
- $xy$-coordinate system. For example, if you provide the number |2|,
- then the $x$-step is twice the $x$-vector and the $y$-step is twice
- the $y$-vector set by the |x=| and |y=| options. Finally, if you
- provide a coordinate, then the $x$-part of this coordinate will be
- used as the $x$-step and the $y$-part will be used as the
- $y$-coordinate.
-
+ The \meta{options}, which are local to the |grid| operation, can be used to
+ influence the appearance of the grid. The stepping of the grid is governed
+ by the following options:
+ %
+ \begin{key}{/tikz/step=\meta{number or dimension or coordinate} (initially 1cm)}
+ Sets the stepping in both the $x$ and $y$-direction. If a dimension is
+ provided, this is used directly. If a number is provided, this number
+ is interpreted in the $xy$-coordinate system. For example, if you
+ provide the number |2|, then the $x$-step is twice the $x$-vector and
+ the $y$-step is twice the $y$-vector set by the |x=| and |y=| options.
+ Finally, if you provide a coordinate, then the $x$-part of this
+ coordinate will be used as the $x$-step and the $y$-part will be used
+ as the $y$-coordinate.
+ %
\begin{codeexample}[]
\begin{tikzpicture}[x=.5cm]
\draw[thick] (0,0) grid [step=1] (3,2);
@@ -629,66 +632,72 @@ operation.
\end{tikzpicture}
\end{codeexample}
- A complication arises when the $x$- and/or $y$-vector do not point
- along the axes. Because of this, the actual rule for computing the
- $x$-step and the $y$-step is the following: As the $x$- and
- $y$-steps we use the $x$- and $y$-components or the following two
- vectors: The first vector is either $(\meta{x-grid-step-number},0)$
- or $(\meta{x-grid-step-dimension},0\mathrm{pt})$, the second vector
- is $(0,\meta{y-grid-step-number})$ or
- $(0\mathrm{pt},\meta{x-grid-step-dimension})$.
-\end{key}
+ A complication arises when the $x$- and/or $y$-vector do not point
+ along the axes. Because of this, the actual rule for computing the
+ $x$-step and the $y$-step is the following: As the $x$- and $y$-steps
+ we use the $x$- and $y$-components or the following two vectors: The
+ first vector is either $(\meta{x-grid-step-number},0)$ or
+ $(\meta{x-grid-step-dimension},0\mathrm{pt})$, the second vector is
+ $(0,\meta{y-grid-step-number})$ or
+ $(0\mathrm{pt},\meta{y-grid-step-dimension})$.
+
+ If the $x$-step or $y$-step is $0$ or negative the corresponding lines
+ are not drawn.
+ \end{key}
-\begin{key}{/tikz/xstep=\meta{dimension or number} (initially 1cm)}
- Sets the stepping in the $x$-direction.
+ \begin{key}{/tikz/xstep=\meta{dimension or number} (initially 1cm)}
+ Sets the stepping in the $x$-direction.
+ %
\begin{codeexample}[]
-\tikz \draw (0,0) grid [xstep=.5,ystep=.75] (3,2);
+\begin{tikzpicture}
+ \draw (0,0) grid [xstep=.5,ystep=.75] (3,2);
+ \draw[ultra thick] (0,0) grid [ystep=0] (3,2);
+\end{tikzpicture}
\end{codeexample}
-\end{key}
+ \end{key}
-\begin{key}{/tikz/ystep=\meta{dimension or number} (initially 1cm)}
- Sets the stepping in the $y$-direction.
-\end{key}
+ \begin{key}{/tikz/ystep=\meta{dimension or number} (initially 1cm)}
+ Sets the stepping in the $y$-direction.
+ \end{key}
- It is important to note that the grid is always ``phased'' such that
- it contains the point $(0,0)$ if that point happens to be inside the
- rectangle. Thus, the grid does \emph{not} always have an intersection
- at the corner points; this occurs only if the corner points are
- multiples of the stepping. Note that due to rounding errors, the
- ``last'' lines of a grid may be omitted. In this case, you have to
- add an epsilon to the corner points.
-
- The following style is useful for drawing grids:
-\begin{stylekey}{/tikz/help lines (initially {line width=0.2pt,gray})}
- This style makes lines ``subdued'' by using thin gray lines for
- them. However, this style is not installed automatically and you
- have to say for example:
+ It is important to note that the grid is always ``phased'' such that it
+ contains the point $(0,0)$ if that point happens to be inside the
+ rectangle. Thus, the grid does \emph{not} always have an intersection at
+ the corner points; this occurs only if the corner points are multiples of
+ the stepping. Note that due to rounding errors, the ``last'' lines of a
+ grid may be omitted. In this case, you have to add an epsilon to the corner
+ points.
+
+ The following style is useful for drawing grids:
+ %
+ \begin{stylekey}{/tikz/help lines (initially {line width=0.2pt,gray})}
+ This style makes lines ``subdued'' by using thin gray lines for them.
+ However, this style is not installed automatically and you have to say
+ for example:
+ %
\begin{codeexample}[]
\tikz \draw[help lines] (0,0) grid (3,3);
\end{codeexample}
-\end{stylekey}
-
+ \end{stylekey}
\end{pathoperation}
-
\subsection{The Parabola Operation}
-The |parabola| path operation continues the current path with a
-parabola. A parabola is a (shifted and scaled) curve defined by the
-equation $f(x) = x^2$ and looks like this: \tikz \draw (-1ex,1.5ex)
-parabola[parabola height=-1.5ex] +(2ex,0ex);.
+The |parabola| path operation continues the current path with a parabola. A
+parabola is a (shifted and scaled) curve defined by the equation $f(x) = x^2$
+and looks like this: \tikz \draw (-1ex,1.5ex) parabola[parabola height=-1.5ex]
++(2ex,0ex);.
\begin{pathoperation}{parabola}{\opt{\oarg{options}|bend|\meta{bend
coordinate}}\meta{coordinate or cycle}}
- This operation adds a parabola through the current point and the
- given \meta{coordinate} or, if |cycle| is used instead of coordinate
- at the end, the \meta{coordinate} is set to the position of the last
- move-to and the path gets closed after the parabola. If the |bend|
- is given, it specifies where
- the bend should go; the \meta{options} can also be used to specify
- where the bend is. By default, the bend is at the old current point.
-
+ This operation adds a parabola through the current point and the given
+ \meta{coordinate} or, if |cycle| is used instead of coordinate at the end,
+ the \meta{coordinate} is set to the position of the last move-to and the
+ path gets closed after the parabola. If the |bend| is given, it specifies
+ where the bend should go; the \meta{options} can also be used to specify
+ where the bend is. By default, the bend is at the old current point.
+ %
\begin{codeexample}[]
\begin{tikzpicture}
\draw (0,0) rectangle (1,1.5)
@@ -697,42 +706,42 @@ parabola[parabola height=-1.5ex] +(2ex,0ex);.
(0,0) parabola[bend at end] (1,1.5);
\draw[xshift=3cm] (0,0) rectangle (1,1.5)
(0,0) parabola bend (.75,1.75) (1,1.5);
-
+
\draw[yshift=-2cm] (1,1.5) --
(0,0) parabola cycle;
\end{tikzpicture}
\end{codeexample}
- The following options influence parabolas:
-\begin{key}{/tikz/bend=\meta{coordinate}}
- Has the same effect as saying |bend|\meta{coordinate} outside the
- \meta{options}. The option specifies that the bend of the parabola
- should be at the given \meta{coordinate}. You have to take care
- yourself that the bend position is a ``valid'' position; which means
- that if there is no parabola of the form $f(x) = a x^2 + b x + c$
- that goes through the old current point, the given bend, and the new
- current point, the result will not be a parabola.
-
- There is one special property of the \meta{coordinate}: When a
- relative coordinate is given like |+(0,0)|, the position relative
- to this coordinate is ``flexible.'' More precisely, this
- position lies somewhere on a line from the old current point to the
- new current point. The exact position depends on the next
- option.
-\end{key}
+ The following options influence parabolas:
+ %
+ \begin{key}{/tikz/bend=\meta{coordinate}}
+ Has the same effect as saying |bend|\meta{coordinate} outside the
+ \meta{options}. The option specifies that the bend of the parabola
+ should be at the given \meta{coordinate}. You have to take care
+ yourself that the bend position is a ``valid'' position; which means
+ that if there is no parabola of the form $f(x) = a x^2 + b x + c$ that
+ goes through the old current point, the given bend, and the new current
+ point, the result will not be a parabola.
+
+ There is one special property of the \meta{coordinate}: When a relative
+ coordinate is given like |+(0,0)|, the position relative to this
+ coordinate is ``flexible''. More precisely, this position lies
+ somewhere on a line from the old current point to the new current
+ point. The exact position depends on the next option.
+ \end{key}
-\begin{key}{/tikz/bend pos=\meta{fraction}}
- Specifies where the ``previous'' point is relative to which the bend
- is calculated. The previous point will be at the \meta{fraction}th
- part of the line from the old current point to the new current
- point.
-
- The idea is the following: If you say |bend pos=0| and
- |bend +(0,0)|, the bend will be at the old current point. If you say
- |bend pos=1| and |bend +(0,0)|, the bend will be at the new current
- point. If you say |bend pos=0.5| and |bend +(0,2cm)| the bend will
- be 2cm above the middle of the line between the start and end
- point. This is most useful in situations such as the following:
+ \begin{key}{/tikz/bend pos=\meta{fraction}}
+ Specifies where the ``previous'' point is relative to which the bend is
+ calculated. The previous point will be at the \meta{fraction}th part of
+ the line from the old current point to the new current point.
+
+ The idea is the following: If you say |bend pos=0| and |bend +(0,0)|,
+ the bend will be at the old current point. If you say |bend pos=1| and
+ |bend +(0,0)|, the bend will be at the new current point. If you say
+ |bend pos=0.5| and |bend +(0,2cm)| the bend will be 2cm above the
+ middle of the line between the start and end point. This is most useful
+ in situations such as the following:
+ %
\begin{codeexample}[]
\begin{tikzpicture}
\draw[help lines] (0,0) grid (3,2);
@@ -740,88 +749,89 @@ parabola[parabola height=-1.5ex] +(2ex,0ex);.
\end{tikzpicture}
\end{codeexample}
- In the above example, the |bend +(0,2)| essentially means ``a
- parabola that is 2cm high'' and |+(3,0)| means ``and 3cm wide.''
- Since this situation arises often, there is a special shortcut
- option:
- \begin{key}{/tikz/parabola height=\meta{dimension}}
- This option has the same effect as
- |[bend pos=0.5,bend={+(0pt,|\meta{dimension}|)}]|.
+ In the above example, the |bend +(0,2)| essentially means ``a parabola
+ that is 2cm high'' and |+(3,0)| means ``and 3cm wide''. Since this
+ situation arises often, there is a special shortcut option:
+ %
+ \begin{key}{/tikz/parabola height=\meta{dimension}}
+ This option has the same effect as
+ |[bend pos=0.5,bend={+(0pt,|\meta{dimension}|)}]|.
+ %
\begin{codeexample}[]
\begin{tikzpicture}
\draw[help lines] (0,0) grid (3,2);
\draw (-1,0) parabola[parabola height=2cm] +(3,0);
\end{tikzpicture}
\end{codeexample}
- \end{key}
-\end{key}
-
-The following styles are useful shortcuts:
-\begin{stylekey}{/tikz/bend at start}
- This places the bend at the start of a
- parabola. It is a shortcut for the following options:
- |bend pos=0,bend={+(0,0)}|.
-\end{stylekey}
+ \end{key}
+ \end{key}
-\begin{stylekey}{/tikz/bend at end}
- This places the bend at the end of a parabola.
-\end{stylekey}
+ The following styles are useful shortcuts:
+ %
+ \begin{stylekey}{/tikz/bend at start}
+ This places the bend at the start of a parabola. It is a shortcut for
+ the following options: |bend pos=0,bend={+(0,0)}|.
+ \end{stylekey}
+ \begin{stylekey}{/tikz/bend at end}
+ This places the bend at the end of a parabola.
+ \end{stylekey}
\end{pathoperation}
\subsection{The Sine and Cosine Operation}
-The |sin| and |cos| operations are similar to the |parabola|
-operation. They, too, can be used to draw (parts of) a sine or cosine
-curve.
+The |sin| and |cos| operations are similar to the |parabola| operation. They,
+too, can be used to draw (parts of) a sine or cosine curve.
\begin{pathoperation}{sin}{\meta{coordinate or cycle}}
- The effect of |sin| is to draw a scaled and shifted version of a sine
- curve in the interval $[0,\pi/2]$. The scaling and shifting is done in
- such a way that the start of the sine curve in the interval is at the
- old current point and that the end of the curve in the interval is at
- \meta{coordinate}. Here is an example that should clarify this:
-
+ The effect of |sin| is to draw a scaled and shifted version of a sine curve
+ in the interval $[0,\pi/2]$. The scaling and shifting is done in such a way
+ that the start of the sine curve in the interval is at the old current
+ point and that the end of the curve in the interval is at
+ \meta{coordinate}. Here is an example that should clarify this:
+ %
\begin{codeexample}[]
\tikz \draw (0,0) rectangle (1,1) (0,0) sin (1,1)
(2,0) rectangle +(1.57,1) (2,0) sin +(1.57,1);
\end{codeexample}
+ %
\end{pathoperation}
\begin{pathoperation}{cos}{\meta{coordinate or cycle}}
- This operation works similarly, only a cosine in the interval
- $[0,\pi/2]$ is drawn. By correctly alternating |sin| and |cos|
- operations, you can create a complete sine or cosine curve:
-
+ This operation works similarly, only a cosine in the interval $[0,\pi/2]$
+ is drawn. By correctly alternating |sin| and |cos| operations, you can
+ create a complete sine or cosine curve:
+ %
\begin{codeexample}[]
\begin{tikzpicture}[xscale=1.57]
\draw (0,0) sin (1,1) cos (2,0) sin (3,-1) cos (4,0) sin (5,1);
\draw[color=red] (0,1.5) cos (1,0) sin (2,-1.5) cos (3,0) sin (4,1.5) cos (5,0);
\end{tikzpicture}
\end{codeexample}
+ %
\end{pathoperation}
-Note that there is no way to (conveniently) draw an interval on a sine
-or cosine curve whose end points are not multiples of $\pi/2$.
+Note that there is no way to (conveniently) draw an interval on a sine or
+cosine curve whose end points are not multiples of $\pi/2$.
\subsection{The SVG Operation}
-The |svg| operation can be used to extend the current path by a path
-given in the \textsc{svg} path data syntax. This syntax is described
-in detail in Section 8.3 of the \textsc{svg 1.1} specification, please
-consult this specification for details.
+The |svg| operation can be used to extend the current path by a path given in
+the \textsc{svg} path data syntax. This syntax is described in detail in
+Section 8.3 of the \textsc{svg 1.1} specification, please consult this
+specification for details.
\begin{pathoperation}{svg}{\opt{\oarg{options}}\marg{path data}}
- This operation adds the path specified in the \meta{path data} in
- \textsc{svg 1.1 path data} syntax to the current path. Unlike the
- \textsc{svg}-specification, it \emph{is} permissible that the path
- data does not start with a move-to command (|m| or |M|), in which
- case the last point of the current path is used as start point.
- The optional \meta{options} apply locally to this path operation,
- typically you will use them to set up, say, some transformations.
-
+ This operation adds the path specified in the \meta{path data} in
+ \textsc{svg 1.1 path data} syntax to the current path. Unlike the
+ \textsc{svg}-specification, it \emph{is} permissible that the path data
+ does not start with a move-to command (|m| or |M|), in which case the last
+ point of the current path is used as start point. The optional
+ \meta{options} apply locally to this path operation, typically you will use
+ them to set up, say, some transformations.
+ %
\begin{codeexample}[]
\begin{tikzpicture}
\filldraw [fill=red!20] (0,1) svg[scale=2] {h 10 v 10 h -10}
@@ -831,70 +841,66 @@ consult this specification for details.
\end{tikzpicture}
\end{codeexample}
- An \textsc{svg} coordinate like |10 20| is always interpreted as
- |(10pt,20pt)|, so the basic unit is always points (|pt|). The
- $xy$-coordinate system is not used. However, you can use scaling to
- (locally) change the basic unit. For instance, |svg[scale=1cm]|
- (yes, this works, although some rather evil magic is involved) will
- cause 1cm to be the basic unit.
+ An \textsc{svg} coordinate like |10 20| is always interpreted as
+ |(10pt,20pt)|, so the basic unit is always points (|pt|). The
+ $xy$-coordinate system is not used. However, you can use scaling to
+ (locally) change the basic unit. For instance, |svg[scale=1cm]| (yes, this
+ works, although some rather evil magic is involved) will cause 1cm to be
+ the basic unit.
- Instead of curly braces, you can also use quotation marks to
- indicate the start and end of the \textsc{svg} path.
+ Instead of curly braces, you can also use quotation marks to indicate the
+ start and end of the \textsc{svg} path.
- \emph{Warning:} The arc operations (|a| and |A|) are numerically
- instable. This means that they will be quite imprecise, except when
- the angle is a multiple of $90^\circ$ (as is, fortunately, most
- often the case).
+ \emph{Warning:} The arc operations (|a| and |A|) are numerically instable.
+ This means that they will be quite imprecise, except when the angle is a
+ multiple of $90^\circ$ (as is, fortunately, most often the case).
\end{pathoperation}
+
\subsection{The Plot Operation}
-The |plot| operation can be used to append a line or curve to the path
-that goes through a large number of coordinates. These coordinates are
-either given in a simple list of coordinates, read from some file, or
-they are computed on the fly.
+The |plot| operation can be used to append a line or curve to the path that
+goes through a large number of coordinates. These coordinates are either given
+in a simple list of coordinates, read from some file, or they are computed on
+the fly.
+
+Since the syntax and the behaviour of this command are a bit complex, they are
+described in the separated Section~\ref{section-tikz-plots}.
-Since the syntax and the behaviour of this command are a bit complex,
-they are described in the separated Section~\ref{section-tikz-plots}.
\subsection{The To Path Operation}
-The |to| operation is used to add a user-defined path
-from the previous coordinate to the following coordinate. When you
-write |(a) to (b)|, a straight line is added from |a|
-to |b|, exactly as if you had written |(a) -- (b)|. However, if you
-write |(a) to [out=135,in=45] (b)| a curve is added to the path,
-which leaves at an angle of 135$^\circ$ at |a| and arrives at an angle
-of 45$^\circ$ at |b|. This is because the options |in| and |out|
-trigger a special path to be used instead of the straight line.
+The |to| operation is used to add a user-defined path from the previous
+coordinate to the following coordinate. When you write |(a) to (b)|, a straight
+line is added from |a| to |b|, exactly as if you had written |(a) -- (b)|.
+However, if you write |(a) to [out=135,in=45] (b)| a curve is added to the
+path, which leaves at an angle of 135$^\circ$ at |a| and arrives at an angle of
+45$^\circ$ at |b|. This is because the options |in| and |out| trigger a special
+path to be used instead of the straight line.
\begin{pathoperation}{to}{\opt{|[|\meta{options}|]|}
- \opt{\meta{nodes}} \meta{coordinate or cycle}}
-
- This path operation inserts the path currently set via the |to path|
- option at the current position. The \meta{options} can be used to
- modify (perhaps implicitly) the |to path| and to set up how the path
- will be rendered.
-
- Before the |to path| is inserted, a number of macros are set up that
- can ``help'' the |to path|. These are |\tikztostart|,
- |\tikztotarget|, and |\tikztonodes|; they are explained in the
- following.
-
- \medskip
- \textbf{Start and Target Coordinates.}\ \
- The |to| operation is always followed by a \meta{coordinate}, called
- the target coordinate, or the text |cycle|, in which case the last
- move-to is used as a coordinate and the path gets closed. The macro
- |\tikztotarget| is set to this coordinate (without its
- parentheses). There is also a \emph{start coordinate}, which is the
- coordinate preceding the |to| operation. This coordinate can be
- accessed via the macro |\tikztostart|. In the following example, for
- the first |to|, the macro |\tikztostart| is |0pt,0pt| and the
- |\tikztotarget| is |0,2|. For the second |to|, the macro
- |\tikztostart| is |10pt,10pt| and |\tikztotarget| is |a|. For the
- third, they are set to |a| and |current subpath start|.
-
+ \opt{\meta{nodes}} \meta{coordinate or cycle}}
+ This path operation inserts the path currently set via the |to path| option
+ at the current position. The \meta{options} can be used to modify (perhaps
+ implicitly) the |to path| and to set up how the path will be rendered.
+
+ Before the |to path| is inserted, a number of macros are set up that can
+ ``help'' the |to path|. These are |\tikztostart|, |\tikztotarget|, and
+ |\tikztonodes|; they are explained in the following.
+
+ \medskip
+ \textbf{Start and Target Coordinates.}\ \
+ The |to| operation is always followed by a \meta{coordinate}, called the
+ target coordinate, or the text |cycle|, in which case the last move-to is
+ used as a coordinate and the path gets closed. The macro |\tikztotarget| is
+ set to this coordinate (without its parentheses). There is also a
+ \emph{start coordinate}, which is the coordinate preceding the |to|
+ operation. This coordinate can be accessed via the macro |\tikztostart|. In
+ the following example, for the first |to|, the macro |\tikztostart| is
+ |0pt,0pt| and the |\tikztotarget| is |0,2|. For the second |to|, the macro
+ |\tikztostart| is |10pt,10pt| and |\tikztotarget| is |a|. For the third,
+ they are set to |a| and |current subpath start|.
+ %
\begin{codeexample}[]
\begin{tikzpicture}
\draw[help lines] (0,0) grid (3,2);
@@ -906,17 +912,15 @@ trigger a special path to be used instead of the straight line.
\end{tikzpicture}
\end{codeexample}
-
- \medskip
- \textbf{Nodes on to--paths.}\ \
- It is possible to add nodes to the paths constructed by a |to|
- operation. To do so, you specify the nodes between the |to|
- keyword and the coordinate (if there are options to the |to|
- operation, these come first). The effect of |(a) to node {x} (b)|
- (typically) is the same as if you had written
- |(a) -- node {x} (b)|, namely that the node is placed on the
- to. This can be used to add labels to tos:
-
+ \medskip
+ \textbf{Nodes on to--paths.}\ \
+ It is possible to add nodes to the paths constructed by a |to| operation.
+ To do so, you specify the nodes between the |to| keyword and the coordinate
+ (if there are options to the |to| operation, these come first). The effect
+ of |(a) to node {x} (b)| (typically) is the same as if you had written
+ |(a) -- node {x} (b)|, namely that the node is placed on the to. This can
+ be used to add labels to tos:
+ %
\begin{codeexample}[]
\begin{tikzpicture}
\draw (0,0) to node [sloped,above] {x} (3,2);
@@ -925,15 +929,15 @@ trigger a special path to be used instead of the straight line.
\end{tikzpicture}
\end{codeexample}
- Instead of writing the node between the |to| keyword and the
- target coordinate, you may also use the following keys to create
- such nodes:
- \begin{key}{/tikz/edge node=\meta{node specification}}
- This key can be used inside the \meta{options} of a |to| path
- command. It will add the \meta{node specification} to the list of
- nodes to be placed on the connecting line, just as if you had
- written the \meta{node specification} directly after the |to|
- keyword:
+ Instead of writing the node between the |to| keyword and the target
+ coordinate, you may also use the following keys to create such nodes:
+ %
+ \begin{key}{/tikz/edge node=\meta{node specification}}
+ This key can be used inside the \meta{options} of a |to| path command.
+ It will add the \meta{node specification} to the list of nodes to be
+ placed on the connecting line, just as if you had written the
+ \meta{node specification} directly after the |to| keyword:
+ %
\begin{codeexample}[]
\begin{tikzpicture}
\draw (0,0) to [edge node={node [sloped,above] {x}}] (3,2);
@@ -942,102 +946,120 @@ trigger a special path to be used instead of the straight line.
edge node={node [sloped,above] {x}}] (3,2);
\end{tikzpicture}
\end{codeexample}
- This key is mostly useful to create labels automatically using
- other keys.
- \end{key}
- \begin{key}{/tikz/edge label=\meta{text}}
- A shorthand for |edge node={node[auto]{|\meta{text}|}}|.
+ %
+ This key is mostly useful to create labels automatically using other
+ keys.
+ \end{key}
+ %
+ \begin{key}{/tikz/edge label=\meta{text}}
+ A shorthand for |edge node={node[auto]{|\meta{text}|}}|.
+ %
\begin{codeexample}[]
\tikz \draw (0,0) to [edge label=x] (3,2);
\end{codeexample}
- \end{key}
- \begin{key}{/tikz/edge label'=\meta{text}}
- A shorthand for |edge node={node[auto,swap]{|\meta{text}|}}|.
+ \end{key}
+ %
+ \begin{key}{/tikz/edge label'=\meta{text}}
+ A shorthand for |edge node={node[auto,swap]{|\meta{text}|}}|.
+ %
\begin{codeexample}[]
\tikz \draw (0,0) to [edge label=x, edge label'=y] (3,2);
\end{codeexample}
- \end{key}
-
- When the |quotes| library is loaded, additional ways of specifying
- nodes on to--paths become available, see Section~\ref{section-edge-quotes}.
-
- \medskip
- \textbf{Styles for to-paths.}\ \
- In addition to the \meta{options} given after the |to| operation,
- the following style is also set at the beginning of the to path:
- \begin{stylekey}{/tikz/every to (initially \normalfont empty)}
- This style is installed at the beginning of every to.
+ \end{key}
+
+ When the |quotes| library is loaded, additional ways of specifying nodes on
+ to--paths become available, see Section~\ref{section-edge-quotes}.
+
+ \medskip
+ \textbf{Styles for to-paths.}\ \
+ In addition to the \meta{options} given after the |to| operation, the
+ following style is also set at the beginning of the to path:
+ %
+ \begin{stylekey}{/tikz/every to (initially \normalfont empty)}
+ This style is installed at the beginning of every to.
+ %
\begin{codeexample}[]
\tikz[every to/.style={bend left}]
\draw (0,0) to (3,2);
\end{codeexample}
- Note that, as explained below, every to path is implicitly
- surrounded by curly braces. This means that options like |draw|
- given in an |every to| do not actually influence the path. You can
- fix this by using the |append after command| option:
+ %
+ Note that, as explained below, every to path is implicitly surrounded
+ by curly braces. This means that options like |draw| given in an
+ |every to| do not actually influence the path. You can fix this by
+ using the |append after command| option:
+ %
\begin{codeexample}[]
\tikz[every to/.style={append after command={[draw,dashed]}}]
\draw (0,0) to (3,2);
\end{codeexample}
- \end{stylekey}
-
- \medskip
- \textbf{Options.}\ \
- The \meta{options} given with the |to| allow you to influence the
- appearance of the |to path|. Mostly, these options are used to
- change the |to path|. This can be used to change the path from a
- straight line to, say, a curve.
-
- The path used is set using the following option:
- \begin{key}{/tikz/to path=\meta{path}}
- Whenever an |to| operation is used, the \meta{path} is
- inserted. More precisely, the following path is added:
-
- \begin{quote}
- |{[every to,|\meta{options}|] |\meta{path} |}|
- \end{quote}
-
- The \meta{options} are the options given to the |to| operation,
- the \meta{path} is the path set by this option |to path|.
-
- Inside the \meta{path}, different macros are used to reference the
- from- and to-coordinates. In detail, these are:
- \begin{itemize}
- \item \declareandlabel{\tikztostart} will expand to the from-coordinate
- (without the parentheses).
- \item \declareandlabel{\tikztotarget} will expand to the to-coordinate.
- \item \declareandlabel{\tikztonodes} will expand to the nodes between
- the |to| operation and the coordinate. Furthermore, these
- nodes will have the |pos| option set implicitly.
- \end{itemize}
-
- Let us have a look at a simple example. The standard straight line
- for a |to| is achieved by the following \meta{path}:
- \begin{quote}
- |-- (\tikztotarget) \tikztonodes|
- \end{quote}
-
- Indeed, this is the default setting for the path. When we write
- |(a) to (b)|, the \meta{path} will expand to |(a) -- (b)|, when
- we write
- \begin{quote}
- |(a) to[red] node {x} (b)|
- \end{quote}
- the \meta{path} will expand to
- \begin{quote}
- |(a) -- (b) node[red] {x}|
- \end{quote}
-
- It is not possible to specify the path
- \begin{quote}
- |-- \tikztonodes (\tikztotarget)|
- \end{quote}
- since \tikzname\ does not allow one to have a macro after |--|
- that expands to a node.
-
- Now let us have a look at how we can modify the \meta{path}
- sensibly. The simplest way is to use a curve.
+ \end{stylekey}
+ \medskip
+ \textbf{Options.}\ \
+ The \meta{options} given with the |to| allow you to influence the
+ appearance of the |to path|. Mostly, these options are used to change the
+ |to path|. This can be used to change the path from a straight line to,
+ say, a curve.
+
+ The path used is set using the following option:
+ %
+ \begin{key}{/tikz/to path=\meta{path}}
+ Whenever a |to| operation is used, the \meta{path} is inserted. More
+ precisely, the following path is added:
+ %
+ \begin{quote}
+ |{[every to,|\meta{options}|] |\meta{path} |}|
+ \end{quote}
+
+ The \meta{options} are the options given to the |to| operation, the
+ \meta{path} is the path set by this option |to path|.
+
+ Inside the \meta{path}, different macros are used to reference the
+ from- and to-coordinates. In detail, these are:
+ %
+ \begin{itemize}
+ \item \declareandlabel{\tikztostart} will expand to the
+ from-coordinate (without the parentheses).
+ \item \declareandlabel{\tikztotarget} will expand to the
+ to-coordinate.
+ \item \declareandlabel{\tikztonodes} will expand to the nodes
+ between the |to| operation and the coordinate. Furthermore,
+ these nodes will have the |pos| option set implicitly.
+ \end{itemize}
+
+ Let us have a look at a simple example. The standard straight line for
+ a |to| is achieved by the following \meta{path}:
+ %
+ \begin{quote}
+ |-- (\tikztotarget) \tikztonodes|
+ \end{quote}
+
+ Indeed, this is the default setting for the path. When we write
+ |(a) to (b)|, the \meta{path} will expand to |(a) -- (b)|, when we
+ write
+ %
+ \begin{quote}
+ |(a) to[red] node {x} (b)|
+ \end{quote}
+ %
+ the \meta{path} will expand to
+ %
+ \begin{quote}
+ |(a) -- (b) node[red] {x}|
+ \end{quote}
+
+ It is not possible to specify the path
+ %
+ \begin{quote}
+ |-- \tikztonodes (\tikztotarget)|
+ \end{quote}
+ %
+ since \tikzname\ does not allow one to have a macro after |--| that
+ expands to a node.
+
+ Now let us have a look at how we can modify the \meta{path} sensibly.
+ The simplest way is to use a curve.
+ %
\begin{codeexample}[]
\begin{tikzpicture}[to path={
.. controls +(1,0) and +(1,0) .. (\tikztotarget) \tikztonodes}]
@@ -1051,8 +1073,8 @@ trigger a special path to be used instead of the straight line.
\end{tikzpicture}
\end{codeexample}
- Here is another example:
-
+ Here is another example:
+ %
\begin{codeexample}[]
\tikzset{
my loop/.style={to path={
@@ -1068,100 +1090,100 @@ trigger a special path to be used instead of the straight line.
\end{tikzpicture}
\end{codeexample}
- \begin{key}{/tikz/execute at begin to=\meta{code}}
- The \meta{code} is executed prior to the |to|. This can be used to
- draw one or more additional paths or to do additional
- computations.
- \end{key}
-
- \begin{key}{/tikz/execute at end to=\meta{code}}
- Works like the previous option, only this code is executed after
- the to path has been added.
- % FIXME : provide examples...
- \end{key}
+ \begin{key}{/tikz/execute at begin to=\meta{code}}
+ The \meta{code} is executed prior to the |to|. This can be used to
+ draw one or more additional paths or to do additional computations.
+ \end{key}
+ \begin{key}{/tikz/execute at end to=\meta{code}}
+ Works like the previous option, only this code is executed after
+ the to path has been added.
+ % FIXME : provide examples...
+ \end{key}
- \begin{stylekey}{/tikz/every to (initially \normalfont empty)}
- This style is installed at the beginning of every to.
- \end{stylekey}
- \end{key}
+ \begin{stylekey}{/tikz/every to (initially \normalfont empty)}
+ This style is installed at the beginning of every to.
+ \end{stylekey}
+ \end{key}
\end{pathoperation}
-There are a number of predefined |to path|s, see
-Section~\ref{library-to-paths} for a reference.
+There are a number of predefined |to path|s, see Section~\ref{library-to-paths}
+for a reference.
\subsection{The Foreach Operation}
\begin{pathoperation}{foreach}{\meta{variables}\opt{\oarg{options}} |in|
- \marg{path commands}}
- The |foreach| operation can be used to repeatedly insert the
- \meta{path commands} into the current path. Naturally, the
- \meta{path commands} should internally reference some of the
- \meta{variables} so that you do not insert exactly the same path
- repeatedly, but rather variations. For historical reasons, you can
- also write |\foreach| instead of |foreach|.
+ \marg{path commands}}
+ The |foreach| operation can be used to repeatedly insert the \meta{path
+ commands} into the current path. Naturally, the \meta{path commands} should
+ internally reference some of the \meta{variables} so that you do not insert
+ exactly the same path repeatedly, but rather variations. For historical
+ reasons, you can also write |\foreach| instead of |foreach|.
+ %
\begin{codeexample}[]
\tikz \draw (0,0) foreach \x in {1,...,3} { -- (\x,1) -- (\x,0) };
\end{codeexample}
- See Section~\ref{section-foreach} for more details on the
- for-each-command.
+ %
+ See Section~\ref{section-foreach} for more details on the for-each-command.
\end{pathoperation}
+
\subsection{The Let Operation}
-The \emph{let operation} is the first of a number of path operations
-that do not actually extend that path, but have different, mostly
-local, effects.
+The \emph{let operation} is the first of a number of path operations that do
+not actually extend that path, but have different, mostly local, effects.
\begin{pathoperation}{let}{\meta{assignment}
- \opt{|,|\meta{assignment}}%
- \opt{|,|\meta{assignment}\dots}\declare{| in |}}
- When this path operation is encountered, the \meta{assignment}s are
- evaluated, one by one. This will store coordinate and number in
- special \emph{registers} (which are local to \tikzname, they have
- nothing to do with \TeX\ registers). Subsequently, one can access the
- contents of these registers using the macros |\p|, |\x|, |\y|, and
- |\n|.
-
- The first kind of permissible \meta{assignment}s have the following
- form:
- \begin{quote}
- |\n|\meta{number register}|={|\meta{formula}|}|
- \end{quote}
- When an assignment has this form, the \meta{formula} is evaluated
- using the |\pgfmathparse| operation. The result is stored in the
- \meta{number register}. If the \meta{formula} involves a dimension
- anywhere (as in |2*3cm/2|), then the \meta{number register} stores
- the resulting dimension with a trailing |pt|. A \meta{number register} can
- be named arbitrarily and is a normal \TeX\ parameter to the |\n|
- macro. Possible names are |{left corner}|, but also just a single
- digit like~|5|.
-
- Let us call the path that follows a let operation its
- \emph{body}. Inside the body, the |\n| macro can be used to access
- the register.
- \begin{command}{\n\marg{number register}}
- When this macro is used on the left-hand side of an |=|-sign in a
- let operation, it has no effect and is just there for
- readability. When the macro is used on the right-hand side of an
- |=|-sign or in the body of the let operation, then it expands to
- the value stored in the \meta{number register}. This will either
- be a dimensionless number like |2.0| or a dimension like |5.6pt|.
-
- For instance, if we say |let \n1={1pt+2pt}, \n2={1+2} in ...|, then
- inside the |...| part the macro |\n1| will expand to |3pt| and
- |\n2| expands to |3|.
- \end{command}
-
- The second kind of \meta{assignments} have the following form:
- \begin{quote}
- |\p|\meta{point register}|={|\meta{formula}|}|
- \end{quote}
- Point position registers store a single point, consisting
- of an $x$-part and a $y$-part measured in \TeX\ points (|pt|). In
- particular, point registers do not store nodes or node names.
- Here is an example:
+ \opt{|,|\meta{assignment}}%
+ \opt{|,|\meta{assignment}\dots}\declare{| in |}}
+ When this path operation is encountered, the \meta{assignment}s are
+ evaluated, one by one. This will store coordinate and number in
+ special \emph{registers} (which are local to \tikzname, they have
+ nothing to do with \TeX\ registers). Subsequently, one can access the
+ contents of these registers using the macros |\p|, |\x|, |\y|, and
+ |\n|.
+
+ The first kind of permissible \meta{assignment}s have the following form:
+ %
+ \begin{quote}
+ |\n|\meta{number register}|={|\meta{formula}|}|
+ \end{quote}
+ %
+ When an assignment has this form, the \meta{formula} is evaluated using the
+ |\pgfmathparse| operation. The result is stored in the \meta{number
+ register}. If the \meta{formula} involves a dimension anywhere (as in
+ |2*3cm/2|), then the \meta{number register} stores the resulting dimension
+ with a trailing |pt|. A \meta{number register} can be named arbitrarily
+ and is a normal \TeX\ parameter to the |\n| macro. Possible names are
+ |{left corner}|, but also just a single digit like~|5|.
+
+ Let us call the path that follows a let operation its \emph{body}. Inside
+ the body, the |\n| macro can be used to access the register.
+ %
+ \begin{command}{\n\marg{number register}}
+ When this macro is used on the left-hand side of an |=|-sign in a let
+ operation, it has no effect and is just there for readability. When the
+ macro is used on the right-hand side of an |=|-sign or in the body of
+ the let operation, then it expands to the value stored in the
+ \meta{number register}. This will either be a dimensionless number like
+ |2.0| or a dimension like |5.6pt|.
+
+ For instance, if we say |let \n1={1pt+2pt}, \n2={1+2} in ...|, then
+ inside the |...| part the macro |\n1| will expand to |3pt| and |\n2|
+ expands to |3|.
+ \end{command}
+
+ The second kind of \meta{assignments} have the following form:
+ %
+ \begin{quote}
+ |\p|\meta{point register}|={|\meta{formula}|}|
+ \end{quote}
+ %
+ Point position registers store a single point, consisting of an $x$-part
+ and a $y$-part measured in \TeX\ points (|pt|). In particular, point
+ registers do not store nodes or node names. Here is an example:
+ %
\begin{codeexample}[]
\begin{tikzpicture}
\draw [help lines] (0,0) grid (3,2);
@@ -1171,37 +1193,37 @@ local, effects.
\end{tikzpicture}
\end{codeexample}
- \begin{command}{\p\marg{point register}}
- When this macro is used on the left-hand side of an |=|-sign in a
- let operation, it has no effect and is just there for
- readability. When the macro is used on the right-hand side of an
- |=|-sign or in the body of the let operation, then it expands to
- the $x$-part (measured in \TeX\ points) of the coordinate stored
- in the \meta{register}, followed, by a comma, followed by the
- $y$-part.
-
- For instance, if we say |let \p1=(1pt,1pt+2pt) in ...|, then
- inside the |...| part the macro |\p1| will expand to exactly the
- seven characters ``1pt,3pt''. This means that you when you write
- |(\p1)|, this expands to |(1pt,3pt)|, which is presumably exactly
- what you intended.
- \end{command}
- \begin{command}{\x\marg{point register}}
- This macro expands just to the $x$-part of the point
- register. If we say as above, as we did above,
- |let \p1=(1pt,1pt+2pt) in ...|, then
- inside the |...| part the macro |\x1| expands to |1pt|.
- \end{command}
- \begin{command}{\y\marg{point register}}
- Works like |\x|, only for the $y$-part.
- \end{command}
- Note that the above macros are available only inside a let
- operation.
-
- Here is an example where let clauses are used to assemble a coordinate
- from the $x$-coordinate of a first point and the $y$-coordinate of a
- second point. Naturally, using the \verb!|-! notation, this could be
- written much more compactly.
+ \begin{command}{\p\marg{point register}}
+ When this macro is used on the left-hand side of an |=|-sign in a let
+ operation, it has no effect and is just there for readability. When the
+ macro is used on the right-hand side of an |=|-sign or in the body of
+ the let operation, then it expands to the $x$-part (measured in \TeX\
+ points) of the coordinate stored in the \meta{register}, followed, by a
+ comma, followed by the $y$-part.
+
+ For instance, if we say |let \p1=(1pt,1pt+2pt) in ...|, then inside the
+ |...| part the macro |\p1| will expand to exactly the seven characters
+ ``1pt,3pt''. This means that you when you write |(\p1)|, this expands
+ to |(1pt,3pt)|, which is presumably exactly what you intended.
+ \end{command}
+ %
+ \begin{command}{\x\marg{point register}}
+ This macro expands just to the $x$-part of the point register. If we
+ say as above, as we did above, |let \p1=(1pt,1pt+2pt) in ...|, then
+ inside the |...| part the macro |\x1| expands to |1pt|.
+ \end{command}
+ %
+ \begin{command}{\y\marg{point register}}
+ Works like |\x|, only for the $y$-part.
+ \end{command}
+ %
+ Note that the above macros are available only inside a let operation.
+
+ Here is an example where let clauses are used to assemble a coordinate from
+ the $x$-coordinate of a first point and the $y$-coordinate of a second
+ point. Naturally, using the \verb!|-! notation, this could be written much
+ more compactly.
+ %
\begin{codeexample}[]
\begin{tikzpicture}
\draw [help lines] (0,0) grid (3,2);
@@ -1215,9 +1237,10 @@ local, effects.
\end{tikzpicture}
\end{codeexample}
- Note that the effect of a let operation is local to the body of the
- let operation. If you wish to access a computed coordinate outside
- the body, you must use a |coordinate| path operation:
+ Note that the effect of a let operation is local to the body of the let
+ operation. If you wish to access a computed coordinate outside the body,
+ you must use a |coordinate| path operation:
+ %
\begin{codeexample}[]
\begin{tikzpicture}
\draw [help lines] (0,0) grid (3,2);
@@ -1237,8 +1260,9 @@ local, effects.
\end{tikzpicture}
\end{codeexample}
- For a more useful application of the let operation, let us draw a
- circle that touches a given line:
+ For a more useful application of the let operation, let us draw a circle
+ that touches a given line:
+ %
\begin{codeexample}[]
\begin{tikzpicture}
\draw [help lines] (0,0) grid (3,3);
@@ -1254,71 +1278,87 @@ local, effects.
in circle [at=(c), radius=\n1];
\end{tikzpicture}
\end{codeexample}
+ %
\end{pathoperation}
\subsection{The Scoping Operation}
-When \tikzname\ encounters and opening or a closing brace (|{| or~|}|) at
-some point where a path operation should come, it will open or close a
-scope. All options that can be applied ``locally'' will be scoped
-inside the scope. For example, if you apply a transformation like
-|[xshift=1cm]| inside the scoped area, the shifting only applies to
-the scope. On the other hand, an option like |color=red| does not have
-any effect inside a scope since it can only be applied to the path as
-a whole.
+When \tikzname\ encounters and opening or a closing brace (|{| or~|}|) at some
+point where a path operation should come, it will open or close a scope. All
+options that can be applied ``locally'' will be scoped inside the scope. For
+example, if you apply a transformation like |[xshift=1cm]| inside the scoped
+area, the shifting only applies to the scope. On the other hand, an option like
+|color=red| does not have any effect inside a scope since it can only be
+applied to the path as a whole.
-Concerning the effect of scopes on relative coordinates,
-please see Section~\ref{section-scopes-relative}.
+Concerning the effect of scopes on relative coordinates, please see
+Section~\ref{section-scopes-relative}.
\subsection{The Node and Edge Operations}
-The |node| operation adds a so-called node to a
-path. This operation is special in the following sense: It does not
-change the current path in any way. In other words, this operation
-is not really a path operation, but has an effect that is
-``external'' to the path. The |edge| operation has similar effect in
-that it adds something \emph{after} the main path has been
-drawn. However, it works like the |to| operation, that is, it adds a
-|to| path to the picture after the main path has been drawn.
+The |node| operation adds a so-called node to a path. This operation is special
+in the following sense: It does not change the current path in any way. In
+other words, this operation is not really a path operation, but has an effect
+that is ``external'' to the path. The |edge| operation has similar effect in
+that it adds something \emph{after} the main path has been drawn. However, it
+works like the |to| operation, that is, it adds a |to| path to the picture
+after the main path has been drawn.
-Since these operations are quite complex, they are described in the
-separate Section~\ref{section-nodes}.
+Since these operations are quite complex, they are described in the separate
+Section~\ref{section-nodes}.
\subsection{The Graph Operation}
-The |graph| operation can be used to specify easily how a large number
-of nodes are connected. This operation is documented in a separate
-section, see Section~\ref{section-library-graphs}.
+The |graph| operation can be used to specify easily how a large number of nodes
+are connected. This operation is documented in a separate section, see
+Section~\ref{section-library-graphs}.
\subsection{The Pic Operation}
-The |pic| operation is used to insert a ``short picture'' (hence the
-``short'' name) at the current position of the path. This operation is
-somewhat similar to the |node| operation and discussed in detail in
-Section~\ref{section-pics}.
+The |pic| operation is used to insert a ``short picture'' (hence the ``short''
+name) at the current position of the path. This operation is somewhat similar
+to the |node| operation and discussed in detail in Section~\ref{section-pics}.
+
+
+\subsection{The Attribute Animation Operation}
+
+\begin{pathoperation}{:}{\meta{animation attribute}|=|\marg{options}}
+ This path operation has the same effect as if you had said:
+ %
+ \begin{quote}
+ |[animate = { myself:|\meta{animate attribute}|=|\marg{options}|} ]|
+ \end{quote}
+ %
+ This causes an animation of \meta{animate attribute} to be added to the
+ current path, see Section~\ref{section-tikz-animations} for details.
+ %
+\begin{codeexample}[width=2cm]
+\tikz \draw :xshift = {0s = "0cm", 30s = "-3cm", repeats} (0,0) circle (5mm);
+\end{codeexample}
+ %
+\end{pathoperation}
\subsection{The PGF-Extra Operation}
-In some cases you may need to ``do some calculations or some other
-stuff'' while a path is constructed. For this, you would like to
-suspend the construction of the path and suspend \tikzname's parsing
-of the path, you would then like to have some \TeX\ code executed, and
-would then like to resume the parsing of the path. This effect can be
-achieved using the following path operation |\pgfextra|. Note that
-this operation should only be used by real experts and should only be
-used deep inside clever macros, not on normal paths.
+In some cases you may need to ``do some calculations or some other stuff''
+while a path is constructed. For this, you would like to suspend the
+construction of the path and suspend \tikzname's parsing of the path, you would
+then like to have some \TeX\ code executed, and would then like to resume the
+parsing of the path. This effect can be achieved using the following path
+operation |\pgfextra|. Note that this operation should only be used by real
+experts and should only be used deep inside clever macros, not on normal paths.
\begin{command}{\pgfextra\marg{code}}
- This command may only be used inside a \tikzname\ path. There it is
- used like a normal path operation. The construction of the path is
- temporarily suspended and the \meta{code} is executed. Then, the
- path construction is resumed.
-
+ This command may only be used inside a \tikzname\ path. There it is used
+ like a normal path operation. The construction of the path is temporarily
+ suspended and the \meta{code} is executed. Then, the path construction is
+ resumed.
+ %
\begin{codeexample}[]
\newdimen\mydim
\begin{tikzpicture}
@@ -1326,16 +1366,17 @@ used deep inside clever macros, not on normal paths.
\draw (0pt,\mydim) \pgfextra{\mydim=2cm} -- (0pt,\mydim);
\end{tikzpicture}
\end{codeexample}
+ %
\end{command}
\begin{command}{\pgfextra \meta{code} \texttt{\char`\\endpgfextra}}
- This is an alternative syntax for the |\pgfextra| command. If the
- code following |\pgfextra| does not start with a brace, the
- \meta{code} is executed until |\endpgfextra| is encountered. What
- actually happens is that when |\pgfextra| is not followed by a
- brace, this completely shuts down the \tikzname\ parser and
- |\endpgfextra| is a normal macro that restarts the parser.
-
+ This is an alternative syntax for the |\pgfextra| command. If the code
+ following |\pgfextra| does not start with a brace, the \meta{code} is
+ executed until |\endpgfextra| is encountered. What actually happens is that
+ when |\pgfextra| is not followed by a brace, this completely shuts down the
+ \tikzname\ parser and |\endpgfextra| is a normal macro that restarts the
+ parser.
+ %
\begin{codeexample}[]
\newdimen\mydim
\begin{tikzpicture}
@@ -1344,4 +1385,5 @@ used deep inside clever macros, not on normal paths.
\pgfextra \mydim=2cm \endpgfextra -- (0pt,\mydim);
\end{tikzpicture}
\end{codeexample}
+ %
\end{command}