summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-paths.tex
diff options
context:
space:
mode:
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.tex340
1 files changed, 322 insertions, 18 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 9eaffdcd086..37c0be02ec6 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
@@ -1,9 +1,11 @@
-% Copyright 2005 by Till Tantau <tantau@cs.tu-berlin.de>.
+% Copyright 2006 by Till Tantau
%
-% This program can be redistributed and/or modified under the terms
-% of the LaTeX Project Public License Distributed from CTAN
-% archives in directory macros/latex/base/lppl.txt.
-
+% This file may be distributed and/or modified
+%
+% 1. under the LaTeX Project Public License and/or
+% 2. under the GNU Free Documentation License.
+%
+% See the file doc/generic/pgf/licenses/LICENSE for more details.
\section{Syntax for Path Specifications}
@@ -628,7 +630,7 @@ current path.
The \emph{arc operation} allows you to add an arc to the current
path.
\begin{pathoperation}{arc}{|(|\meta{start angle}|:|\meta{end
- angle}|:|\meta{radius}\opt{|/|\meta{half height}}|)|}
+ angle}|:|\meta{radius}\opt{| and |\meta{half height}}|)|}
The arc operation adds a part of a circle of the given radius
between the given angles. The arc will start at the current point
and will end at the end of the arc.
@@ -637,7 +639,7 @@ path.
\begin{tikzpicture}
\draw (0,0) arc (180:90:1cm) -- (2,.5) arc (90:0:1cm);
\draw (4,0) -- +(30:1cm) arc (30:60:1cm) -- cycle;
- \draw (8,0) arc (0:270:1cm/.5cm) -- cycle;
+ \draw (8,0) arc (0:270:1cm and .5cm) -- cycle;
\end{tikzpicture}
\end{codeexample}
@@ -664,20 +666,54 @@ operation.
are given by \meta{corner} and by the previous coordinate. 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.
+ $(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 stepping of the grid is governed by the following options:
+ 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{itemize}
- \itemoption{step}|=|\meta{dimension} sets the stepping in both the
- $x$ and $y$-direction.
- \itemoption{xstep}|=|\meta{dimension} sets the stepping in the
+ \itemoption{step}|=|\meta{number or dimension or coordinate} 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);
+ \draw[red] (0,0) grid [step=.75cm] (3,2);
+\end{tikzpicture}
+\begin{tikzpicture}
+ \draw (0,0) circle (1);
+ \draw[blue] (0,0) grid [step=(45:1)] (3,2);
+\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})$.
+
+ \itemoption{xstep}|=|\meta{dimension or number} sets the stepping in the
$x$-direction.
- \itemoption{ystep}|=|\meta{dimension} sets the stepping in the
+\begin{codeexample}[]
+\tikz \draw (0,0) grid [xstep=.5,ystep=.75] (3,2);
+\end{codeexample}
+\itemoption{ystep}|=|\meta{dimension or number} sets the stepping in the
$y$-direction.
\end{itemize}
@@ -1109,13 +1145,40 @@ In detail, the following options govern how marks are drawn:
One plot mark is special: the |ball| plot mark is available only
it \tikzname. The |ball color| determines the balls's color. Do not use
- this option with large number of marks since it will take very long
+ this option with a large number of marks since it will take very long
to render in PostScript.
\begin{tabular}{lc}
Option & Effect \\\hline \vrule height14pt width0pt
\plotmarkentrytikz{ball}
\end{tabular}
+
+ \itemoption{mark repeat}|=|\meta{r}
+ This option tells \tikzname\ that only every $r$th mark should be
+ drawn.
+
+\begin{codeexample}[]
+\tikz \draw plot[mark=x,mark repeat=3,smooth] file {plots/pgfmanual-sine.table};
+\end{codeexample}
+
+ \itemoption{mark phase}|=|\meta{p}
+ This option tells \tikzname\ that the first mark to be draw should
+ be the $p$th, followed by the $(p+r)$th, then the $(p+2r)$th, and so
+ on.
+
+\begin{codeexample}[]
+\tikz \draw plot[mark=x,mark repeat=3,mark phase=6,smooth] file {plots/pgfmanual-sine.table};
+\end{codeexample}
+
+ \itemoption{mark indices}|=|\meta{list}
+ This option allows you to specify explicitly the indices at which a
+ mark should be placed. Counting starts with 1. You can use the
+ |\foreach| syntax, that is, |...| can be used.
+
+\begin{codeexample}[]
+\tikz \draw plot[mark=x,mark indices={1,4,...,10,11,12,...,16,20},smooth]
+ file {plots/pgfmanual-sine.table};
+\end{codeexample}
\itemoption{mark size}|=|\meta{dimension}
Sets the size of the plot marks. For circular plot marks,
@@ -1244,6 +1307,193 @@ use options to change the behavior of |plot|.
+\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.
+
+\begin{pathoperation}{to}{\opt{|[|\meta{options}|]|}
+ \opt{\meta{nodes}} |(|\meta{coordinate}|)|}
+
+ This path operation inserts the path current 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 setup how the path
+ will be rendered.
+
+ Before the |to path| is inserted, a number of macros are setup 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. The macro |\tikztotarget| is set to this
+ coordinate (without the parantheses). 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|.
+
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \draw[help lines] (0,0) grid (3,2);
+
+ \draw (0,0) to (0,2);
+ \node (a) at (2,2) {a};
+ \draw[red] (10pt,10pt) to (a);
+\end{tikzpicture}
+\end{codeexample}
+
+
+ \medskip
+ \textbf{Nodes on tos.}\ \
+ 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);
+
+ \draw (0,0) to[out=90,in=180] node [sloped,above] {x} (3,2);
+\end{tikzpicture}
+\end{codeexample}
+
+ \medskip
+ \textbf{Styles for nodes.}\ \
+ 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{itemize}
+ \itemstyle{every to}
+ This style is installed at the beginning of every to. By
+ default, it is set to |draw|.
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \tikzstyle{every to}=[draw,dashed]
+ \path (0,0) to (3,2);
+\end{tikzpicture}
+\end{codeexample}
+ \end{itemize}
+
+ \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{itemize}
+ \itemoption{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 \declare{|\tikztostart|} will expand to the from-coordinate
+ (without the parantheses).
+ \item \declare{|\tikztotarget|} will expand to the to-coordinate.
+ \item \declare{|\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 an 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[pos] {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}]
+
+ \node (a) at (0,0) {a};
+ \node (b) at (2,1) {b};
+ \node (c) at (1,2) {c};
+
+ \draw (a) to node {x} (b)
+ (a) to (c);
+\end{tikzpicture}
+\end{codeexample}
+
+ Here is another example:
+
+\begin{codeexample}[]
+\tikzstyle{my loop}=[->,to path={
+ .. controls +(80:1) and +(100:1) .. (\tikztotarget) \tikztonodes}]
+\tikzstyle{my state}= [circle,draw]
+
+\begin{tikzpicture}[shorten >=2pt]
+ \node [my state] (a) at (210:1) {$q_a$};
+ \node [my state] (b) at (330:1) {$q_b$};
+
+ \draw (a) to node[below] {1} (b)
+ to [my loop] node[above right] {0} (b);
+\end{tikzpicture}
+\end{codeexample}
+
+ \itemoption{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.
+
+ \itemoption{executed at end to}|=|\meta{code}
+ Works like the previous option, only this code is executed after
+ the to path has been added.
+
+ \itemstyle{every to}
+ This style is installed at the beginning of every to. It is empty
+ by default.
+ \end{itemize}
+\end{pathoperation}
+
+There are a number of predefined |to path|s, see
+Section~\ref{library-to-paths} for a reference.
+
+
\subsection{The Scoping Operation}
@@ -1260,7 +1510,61 @@ a whole.
\subsection{The Node Operation}
-You can add nodes to a path using the |node| operation. Since this
-operation is quite complex and since the nodes are not really part of
-the path itself, there is a separate section dealing with nodes, see
-Section~\ref{section-nodes}.
+There are teo more operations that can be found in paths:
+|node| and |edge|. The first is used to add 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 parth 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}.
+
+
+
+\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.
+
+\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.
+
+\begin{codeexample}[]
+\newdimen\mydim
+\begin{tikzpicture}
+ \mydim=1cm
+ \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 |\pgfextra| that is not followed by a brace
+ completely shuts down the \tikzname\ parse and |\endpgfextra| is a
+ normal macro that restarts the parser.
+
+\begin{codeexample}[]
+\newdimen\mydim
+\begin{tikzpicture}
+ \mydim=1cm
+ \draw (0pt,\mydim)
+ \pgfextra \mydim=2cm \endpgfextra -- (0pt,\mydim);
+\end{tikzpicture}
+\end{codeexample}
+\end{command}