diff options
author | Karl Berry <karl@freefriends.org> | 2006-10-15 22:37:32 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2006-10-15 22:37:32 +0000 |
commit | 237df1eb06d422ff243a05b9a25501ba287681c1 (patch) | |
tree | 4cc4f2032474921cb986d1ca63b3cf9a267b480a /Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-paths.tex | |
parent | 15e21b5bab66eca251ac48fdc052126505428d4e (diff) |
pgf/tikz 1.09 big update (13oct06)
git-svn-id: svn://tug.org/texlive/trunk@2332 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.tex | 340 |
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} |