| 1 |
% Copyright 2019 by Till Tantau |
| 2 |
% |
| 3 |
% This file may be distributed and/or modified |
| 4 |
% |
| 5 |
% 1. under the LaTeX Project Public License and/or |
| 6 |
% 2. under the GNU Free Documentation License. |
| 7 |
% |
| 8 |
% See the file doc/generic/pgf/licenses/LICENSE for more details. |
| 9 |
|
| 10 |
|
| 11 |
\section{Syntax for Path Specifications} |
| 12 |
\label{section-paths} |
| 13 |
|
| 14 |
A \emph{path} is a series of straight and curved line segments. It is specified |
| 15 |
following a |\path| command and the specification must follow a special syntax, |
| 16 |
which is described in the subsections of the present section. |
| 17 |
|
| 18 |
\begin{command}{\path\meta{specification}|;|} |
| 19 |
This command is available only inside a |{tikzpicture}| environment. |
| 20 |
|
| 21 |
The \meta{specification} is a long stream of \emph{path operations}. Most |
| 22 |
of these path operations tell \tikzname\ how the path is built. For |
| 23 |
example, when you write |--(0,0)|, you use a \emph{line-to operation} and |
| 24 |
it means ``continue the path from wherever you are to the origin''. |
| 25 |
|
| 26 |
At any point where \tikzname\ expects a path operation, you can also give |
| 27 |
some graphic options, which is a list of options in brackets, such as |
| 28 |
|[rounded corners]|. These options can have different effects: |
| 29 |
% |
| 30 |
\begin{enumerate} |
| 31 |
\item Some options take ``immediate'' effect and apply to all |
| 32 |
subsequent path operations on the path. For example, the |
| 33 |
|rounded corners| option will round all following corners, but not |
| 34 |
the corners ``before'' and if the |sharp corners| is given later on |
| 35 |
the path (in a new set of brackets), the rounding effect will end. |
| 36 |
% |
| 37 |
\begin{codeexample}[] |
| 38 |
\tikz \draw (0,0) -- (1,1) |
| 39 |
[rounded corners] -- (2,0) -- (3,1) |
| 40 |
[sharp corners] -- (3,0) -- (2,1); |
| 41 |
\end{codeexample} |
| 42 |
% |
| 43 |
Another example are the transformation options, which also apply |
| 44 |
only to subsequent coordinates. |
| 45 |
\item The options that have immediate effect can be ``scoped'' by |
| 46 |
putting part of a path in curly braces. For example, the above |
| 47 |
example could also be written as follows: |
| 48 |
% |
| 49 |
\begin{codeexample}[] |
| 50 |
\tikz \draw (0,0) -- (1,1) |
| 51 |
{[rounded corners] -- (2,0) -- (3,1)} |
| 52 |
-- (3,0) -- (2,1); |
| 53 |
\end{codeexample} |
| 54 |
% |
| 55 |
\item Some options only apply to the path as a whole. For example, |
| 56 |
the |color=| option for determining the color used for, say, |
| 57 |
drawing the path always applies to all parts of the path. If |
| 58 |
several different colors are given for different parts of the |
| 59 |
path, only the last one (on the outermost scope) ``wins'': |
| 60 |
% |
| 61 |
\begin{codeexample}[] |
| 62 |
\tikz \draw (0,0) -- (1,1) |
| 63 |
[color=red] -- (2,0) -- (3,1) |
| 64 |
[color=blue] -- (3,0) -- (2,1); |
| 65 |
\end{codeexample} |
| 66 |
|
| 67 |
Most options are of this type. In the above example, we would |
| 68 |
have had to ``split up'' the path into several |\path| commands: |
| 69 |
% |
| 70 |
\begin{codeexample}[] |
| 71 |
\tikz{\draw (0,0) -- (1,1); |
| 72 |
\draw [color=red] (1,1) -- (2,0) -- (3,1); |
| 73 |
\draw [color=blue] (3,1) -- (3,0) -- (2,1);} |
| 74 |
\end{codeexample} |
| 75 |
\end{enumerate} |
| 76 |
|
| 77 |
By default, the |\path| command does ``nothing'' with the path, it just |
| 78 |
``throws it away''. Thus, if you write |\path(0,0)--(1,1);|, nothing is |
| 79 |
drawn in your picture. The only effect is that the area occupied by the |
| 80 |
picture is (possibly) enlarged so that the path fits inside the area. To |
| 81 |
actually ``do'' something with the path, an option like |draw| or |fill| |
| 82 |
must be given somewhere on the path. Commands like |\draw| do this |
| 83 |
implicitly. |
| 84 |
|
| 85 |
Finally, it is also possible to give \emph{node specifications} on a path. |
| 86 |
Such specifications can come at different locations, but they are always |
| 87 |
allowed when a normal path operation could follow. A node specification |
| 88 |
starts with |node|. Basically, the effect is to typeset the node's text as |
| 89 |
normal \TeX\ text and to place it at the ``current location'' on the path. |
| 90 |
The details are explained in Section~\ref{section-nodes}. |
| 91 |
|
| 92 |
Note, however, that the nodes are \emph{not} part of the path in any way. |
| 93 |
Rather, after everything has been done with the path what is specified by |
| 94 |
the path options (like filling and drawing the path due to a |fill| and a |
| 95 |
|draw| option somewhere in the \meta{specification}), the nodes are added |
| 96 |
in a post-processing step. |
| 97 |
|
| 98 |
\emph{Note:} When scanning for path operations \tikzname\ expands tokens |
| 99 |
looking for valid path operations. This however implies that these tokens |
| 100 |
has to be fully expandable up to the point where it results in a valid path |
| 101 |
operation. |
| 102 |
\end{command} |
| 103 |
|
| 104 |
\begin{key}{/tikz/name=\meta{path name}} |
| 105 |
Assigns a name to the path for reference (specifically, for reference |
| 106 |
in animations; for reference in intersections, use the |name path| |
| 107 |
command, which has a different purpose, see the |intersections| library |
| 108 |
for details). Since the name is a ``high-level'' name (drivers never |
| 109 |
know of it), you can use spaces, number, letters, or whatever you like |
| 110 |
when naming a path, but the name may \emph{not} contain any punctuation |
| 111 |
like a dot, a comma, or a colon. |
| 112 |
\end{key} |
| 113 |
|
| 114 |
The following style influences scopes: |
| 115 |
% |
| 116 |
\begin{stylekey}{/tikz/every path (initially \normalfont empty)} |
| 117 |
This style is installed at the beginning of every path. This can be |
| 118 |
useful for (temporarily) adding, say, the |draw| option to everything |
| 119 |
in a scope. |
| 120 |
% |
| 121 |
\begin{codeexample}[] |
| 122 |
\begin{tikzpicture} |
| 123 |
[fill=yellow!80!black, % only sets the color |
| 124 |
every path/.style={draw}] % all paths are drawn |
| 125 |
\fill (0,0) rectangle +(1,1); |
| 126 |
\shade (2,0) rectangle +(1,1); |
| 127 |
\end{tikzpicture} |
| 128 |
\end{codeexample} |
| 129 |
% |
| 130 |
\end{stylekey} |
| 131 |
|
| 132 |
\begin{key}{/tikz/insert path=\meta{path}} |
| 133 |
This key can be used inside an option to add something to the current path. |
| 134 |
This is mostly useful for defining styles that create graphic contents. |
| 135 |
This option should be used with care, for instance it should not be used as |
| 136 |
an argument of, say, a |node|. In the following example, we use a style to |
| 137 |
add little circles to a path. |
| 138 |
% |
| 139 |
\begin{codeexample}[] |
| 140 |
\tikz [c/.style={insert path={circle[radius=2pt]}}] |
| 141 |
\draw (0,0) -- (1,1) [c] -- (3,2) [c]; |
| 142 |
\end{codeexample} |
| 143 |
% |
| 144 |
The effect is the same as of |
| 145 |
|(0,0) -- (1,1) circle[radius=2pt] -- (3,2) circle[radius=2pt]|. |
| 146 |
\end{key} |
| 147 |
|
| 148 |
The following options are for experts only: |
| 149 |
|
| 150 |
\begin{key}{/tikz/append after command=\meta{path}} |
| 151 |
Some of the path commands described in the following sections take optional |
| 152 |
arguments. For these commands, when you use this key inside these options, |
| 153 |
the \meta{path} will be inserted \emph{after} the path command is done. For |
| 154 |
instance, when you give this command in the option list of a node, the |
| 155 |
\meta{path} will be added after the node. This is used by, for instance, |
| 156 |
the |label| option to allow you to specify a label in the option list of a |
| 157 |
node, but have this |label| cause a node to be added after another node. |
| 158 |
% |
| 159 |
\begin{codeexample}[] |
| 160 |
\tikz \draw node [append after command={(foo)--(1,1)},draw] (foo){foo}; |
| 161 |
\end{codeexample} |
| 162 |
% |
| 163 |
If this key is called multiple times, the effects accumulate, that is, all |
| 164 |
of the paths are added in the order to keys were found. |
| 165 |
\end{key} |
| 166 |
|
| 167 |
\begin{key}{/tikz/prefix after command=\meta{path}} |
| 168 |
Works like |append after command|, only the accumulation order is inverse: |
| 169 |
The \meta{path} is added before any earlier paths added using either |
| 170 |
|append after command| or |prefix after command|. |
| 171 |
\end{key} |
| 172 |
|
| 173 |
|
| 174 |
\subsection{The Move-To Operation} |
| 175 |
|
| 176 |
The perhaps simplest operation is the move-to operation, which is specified by |
| 177 |
just giving a coordinate where a path operation is expected. |
| 178 |
|
| 179 |
\begin{pathoperation}[noindex]{}{\meta{coordinate}} |
| 180 |
\index{empty@\protect\meta{empty} path operation}% |
| 181 |
\index{Path operations!empty@\protect\texttt{\meta{empty}}}% |
| 182 |
The move-to operation normally starts a path at a certain point. This does |
| 183 |
not cause a line segment to be created, but it specifies the starting point |
| 184 |
of the next segment. If a path is already under construction, that is, if |
| 185 |
several segments have already been created, a move-to operation will start |
| 186 |
a new part of the path that is not connected to any of the previous |
| 187 |
segments. |
| 188 |
% |
| 189 |
\begin{codeexample}[] |
| 190 |
\begin{tikzpicture} |
| 191 |
\draw (0,0) --(2,0) (0,1) --(2,1); |
| 192 |
\end{tikzpicture} |
| 193 |
\end{codeexample} |
| 194 |
|
| 195 |
In the specification |(0,0) --(2,0) (0,1) --(2,1)| two move-to operations |
| 196 |
are specified: |(0,0)| and |(0,1)|. The other two operations, namely |
| 197 |
|--(2,0)| and |--(2,1)| are line-to operations, described next. |
| 198 |
\end{pathoperation} |
| 199 |
|
| 200 |
There is special coordinate called |current subpath start| that is always at |
| 201 |
the position of the last move-to operation on the current path. |
| 202 |
% |
| 203 |
\begin{codeexample}[] |
| 204 |
\tikz [line width=2mm] |
| 205 |
\draw (0,0) -- (1,0) -- (1,1) |
| 206 |
-- (0,1) -- (current subpath start); |
| 207 |
\end{codeexample} |
| 208 |
|
| 209 |
Note how in the above example the path is not closed (as |--cycle| would do). |
| 210 |
Rather, the line just starts and ends at the origin without being a closed |
| 211 |
path. |
| 212 |
|
| 213 |
|
| 214 |
\subsection{The Line-To Operation} |
| 215 |
|
| 216 |
\subsubsection{Straight Lines} |
| 217 |
|
| 218 |
\begin{pathoperation}{--}{\meta{coordinate or cycle}} |
| 219 |
The line-to operation extends the current path from the current point in a |
| 220 |
straight line to the given \meta{coordinate} (the ``or cycle'' part is |
| 221 |
explained in a moment). The ``current point'' is the endpoint of the |
| 222 |
previous drawing operation or the point specified by a prior move-to |
| 223 |
operation. |
| 224 |
|
| 225 |
When a line-to operation is used and some path segment has just been |
| 226 |
constructed, for example by another line-to operation, the two line |
| 227 |
segments become joined. This means that if they are drawn, the point where |
| 228 |
they meet is ``joined'' smoothly. To appreciate the difference, consider |
| 229 |
the following two examples: In the left example, the path consists of two |
| 230 |
path segments that are not joined, but they happen to share a point, while |
| 231 |
in the right example a smooth join is shown. |
| 232 |
% |
| 233 |
\begin{codeexample}[] |
| 234 |
\begin{tikzpicture}[line width=10pt] |
| 235 |
\draw (0,0) --(1,1) (1,1) --(2,0); |
| 236 |
\draw (3,0) -- (4,1) -- (5,0); |
| 237 |
\useasboundingbox (0,1.5); % make bounding box higher |
| 238 |
\end{tikzpicture} |
| 239 |
\end{codeexample} |
| 240 |
|
| 241 |
Instead of a coordinate following the two minus signs, you can also use the |
| 242 |
text |cycle|. This causes the straight line from the current point to go to |
| 243 |
the last point specified by a move-to operation. Note that this need not be |
| 244 |
the beginning of the path. Furthermore, a smooth join is created between |
| 245 |
the first segment created after the last move-to operation and the straight |
| 246 |
line appended by the cycle operation. |
| 247 |
|
| 248 |
Consider the following example. In the left example, two triangles are |
| 249 |
created using three straight lines, but they are not joined at the ends. In |
| 250 |
the second example cycle operations are used. |
| 251 |
% |
| 252 |
\begin{codeexample}[] |
| 253 |
\begin{tikzpicture}[line width=10pt] |
| 254 |
\draw (0,0) -- (1,1) -- (1,0) -- (0,0) (2,0) -- (3,1) -- (3,0) -- (2,0); |
| 255 |
\draw (5,0) -- (6,1) -- (6,0) -- cycle (7,0) -- (8,1) -- (8,0) -- cycle; |
| 256 |
\useasboundingbox (0,1.5); % make bounding box higher |
| 257 |
\end{tikzpicture} |
| 258 |
\end{codeexample} |
| 259 |
% |
| 260 |
\end{pathoperation} |
| 261 |
|
| 262 |
Writing |cycle| instead of a coordinate at the end of a path operation is |
| 263 |
possible with all path operations that end with a coordinate (such as |--| or |
| 264 |
|..| or |sin| or |grid|, but not |graph| or |plot|). In all cases, the effect |
| 265 |
is that the coordinate of the last moveto is used as the coordinate expected by |
| 266 |
the path operation and that a smooth join is added. (What actually happens that |
| 267 |
the text |cycle| used with any path operation other than |--| gets replaced by |
| 268 |
|(current subpath start)--cycle|.) |
| 269 |
|
| 270 |
|
| 271 |
\subsubsection{Horizontal and Vertical Lines} |
| 272 |
|
| 273 |
Sometimes you want to connect two points via straight lines that are only |
| 274 |
horizontal and vertical. For this, you can use two path construction |
| 275 |
operations. |
| 276 |
|
| 277 |
{\catcode`\|=12 |
| 278 |
\begin{pathoperation}[noindex]{-|}{\meta{coordinate or cycle}} |
| 279 |
\index{--1@\protect\texttt{-\protect\pgfmanualbar} path operation}% |
| 280 |
\index{Path operations!--1@\protect\texttt{-\protect\pgfmanualbar}}% |
| 281 |
\pgfmanualpdflabel[\catcode`\|=12 ]{-|}{}% |
| 282 |
This operation means ``first horizontal, then vertical''. |
| 283 |
% |
| 284 |
\begin{codeexample}[] |
| 285 |
\begin{tikzpicture} |
| 286 |
\draw (0,0) node(a) [draw] {A} (1,1) node(b) [draw] {B}; |
| 287 |
\draw (a.north) |- (b.west); |
| 288 |
\draw[color=red] (a.east) -| (2,1.5) -| (b.north); |
| 289 |
\end{tikzpicture} |
| 290 |
\end{codeexample} |
| 291 |
% |
| 292 |
Instead of a coordinate you can also write \verb!cycle! to close the path: |
| 293 |
% |
| 294 |
\begin{codeexample}[] |
| 295 |
\begin{tikzpicture}[ultra thick] |
| 296 |
\draw (0,0) -- (1,1) -| cycle; |
| 297 |
\end{tikzpicture} |
| 298 |
\end{codeexample} |
| 299 |
\end{pathoperation} |
| 300 |
|
| 301 |
\begin{pathoperation}[noindex]{|-}{\meta{coordinate or cycle}} |
| 302 |
\index{--2@\protect\texttt{\protect\pgfmanualbar-} path operation}% |
| 303 |
\index{Path operations!--2@\protect\texttt{\protect\pgfmanualbar-}}% |
| 304 |
\pgfmanualpdflabel[\catcode`\|=12 ]{|-}{}% |
| 305 |
This operation means ``first vertical, then horizontal''. |
| 306 |
\end{pathoperation} |
| 307 |
} |
| 308 |
|
| 309 |
|
| 310 |
\subsection{The Curve-To Operation} |
| 311 |
|
| 312 |
The curve-to operation allows you to extend a path using a Bézier curve. |
| 313 |
|
| 314 |
\begin{pathoperation}{..}{\declare{|controls|}\meta{c}\opt{|and|\meta{d}}\declare{|..|\meta{y or cycle}}} |
| 315 |
This operation extends the current path from the current point, let us call |
| 316 |
it $x$, via a curve to a point~$y$ (if, instead of a coordinate you say |
| 317 |
|cycle| at the end, $y$ will be the coordinate of the last move-to |
| 318 |
operation). The curve is a cubic Bézier curve. For such a curve, apart |
| 319 |
from $y$, you also specify two control points $c$ and $d$. The idea is that |
| 320 |
the curve starts at $x$, ``heading'' in the direction of~$c$. |
| 321 |
Mathematically spoken, the tangent of the curve at $x$ goes through $c$. |
| 322 |
Similarly, the curve ends at $y$, ``coming from'' the other control |
| 323 |
point,~$d$. The larger the distance between $x$ and~$c$ and between $d$ |
| 324 |
and~$y$, the larger the curve will be. |
| 325 |
|
| 326 |
If the ``|and|\meta{d}'' part is not given, $d$ is assumed to be equal to |
| 327 |
$c$. |
| 328 |
% |
| 329 |
\begin{codeexample}[] |
| 330 |
\begin{tikzpicture} |
| 331 |
\draw[line width=10pt] (0,0) .. controls (1,1) .. (4,0) |
| 332 |
.. controls (5,0) and (5,1) .. (4,1); |
| 333 |
\draw[color=gray] (0,0) -- (1,1) -- (4,0) -- (5,0) -- (5,1) -- (4,1); |
| 334 |
\end{tikzpicture} |
| 335 |
\end{codeexample} |
| 336 |
|
| 337 |
\begin{codeexample}[] |
| 338 |
\begin{tikzpicture} |
| 339 |
\draw[line width=10pt] (0,0) -- (2,0) .. controls (1,1) .. cycle; |
| 340 |
\end{tikzpicture} |
| 341 |
\end{codeexample} |
| 342 |
|
| 343 |
As with the line-to operation, it makes a difference whether two curves are |
| 344 |
joined because they resulted from consecutive curve-to or line-to |
| 345 |
operations, or whether they just happen to have a common (end) point: |
| 346 |
% |
| 347 |
\begin{codeexample}[] |
| 348 |
\begin{tikzpicture}[line width=10pt] |
| 349 |
\draw (0,0) -- (1,1) (1,1) .. controls (1,0) and (2,0) .. (2,0); |
| 350 |
\draw [yshift=-1.5cm] |
| 351 |
(0,0) -- (1,1) .. controls (1,0) and (2,0) .. (2,0); |
| 352 |
\end{tikzpicture} |
| 353 |
\end{codeexample} |
| 354 |
% |
| 355 |
\end{pathoperation} |
| 356 |
|
| 357 |
|
| 358 |
\subsection{The Rectangle Operation} |
| 359 |
|
| 360 |
A rectangle can obviously be created using four straight lines and a cycle |
| 361 |
operation. However, since rectangles are needed so often, a special syntax is |
| 362 |
available for them. |
| 363 |
|
| 364 |
\begin{pathoperation}{rectangle}{\meta{corner or cycle}} |
| 365 |
When this operation is used, one corner will be the current point, another |
| 366 |
corner is given by \meta{corner}, which becomes the new current point. |
| 367 |
% |
| 368 |
\begin{codeexample}[] |
| 369 |
\begin{tikzpicture} |
| 370 |
\draw (0,0) rectangle (1,1); |
| 371 |
\draw (.5,1) rectangle (2,0.5) (3,0) rectangle (3.5,1.5) -- (2,0); |
| 372 |
\end{tikzpicture} |
| 373 |
\end{codeexample} |
| 374 |
|
| 375 |
Just for consistency, you can also use |cycle| instead of a coordinate, but |
| 376 |
it is a bit unclear what use this might have. |
| 377 |
\end{pathoperation} |
| 378 |
|
| 379 |
|
| 380 |
\subsection{Rounding Corners} |
| 381 |
|
| 382 |
All of the path construction operations mentioned up to now are influenced by |
| 383 |
the following option: |
| 384 |
|
| 385 |
\begin{key}{/tikz/rounded corners=\meta{inset} (default 4pt)} |
| 386 |
When this option is in force, all corners (places where a line is continued |
| 387 |
either via line-to or a curve-to operation) are replaced by little arcs so |
| 388 |
that the corner becomes smooth. |
| 389 |
% |
| 390 |
\begin{codeexample}[] |
| 391 |
\tikz \draw [rounded corners] (0,0) -- (1,1) |
| 392 |
-- (2,0) .. controls (3,1) .. (4,0); |
| 393 |
\end{codeexample} |
| 394 |
|
| 395 |
The \meta{inset} describes how big the corner is. Note that the |
| 396 |
\meta{inset} is \emph{not} scaled along if you use a scaling option like |
| 397 |
|scale=2|. |
| 398 |
% |
| 399 |
\begin{codeexample}[] |
| 400 |
\begin{tikzpicture} |
| 401 |
\draw[color=gray,very thin] (10pt,15pt) circle[radius=10pt]; |
| 402 |
\draw[rounded corners=10pt] (0,0) -- (0pt,25pt) -- (40pt,25pt); |
| 403 |
\end{tikzpicture} |
| 404 |
\end{codeexample} |
| 405 |
|
| 406 |
You can switch the rounded corners on and off ``in the middle of path'' and |
| 407 |
different corners in the same path can have different corner radii: |
| 408 |
% |
| 409 |
\begin{codeexample}[] |
| 410 |
\begin{tikzpicture} |
| 411 |
\draw (0,0) [rounded corners=10pt] -- (1,1) -- (2,1) |
| 412 |
[sharp corners] -- (2,0) |
| 413 |
[rounded corners=5pt] -- cycle; |
| 414 |
\end{tikzpicture} |
| 415 |
\end{codeexample} |
| 416 |
|
| 417 |
Here is a rectangle with rounded corners: |
| 418 |
% |
| 419 |
\begin{codeexample}[] |
| 420 |
\tikz \draw[rounded corners=1ex] (0,0) rectangle (20pt,2ex); |
| 421 |
\end{codeexample} |
| 422 |
|
| 423 |
You should be aware, that there are several pitfalls when using this |
| 424 |
option. First, the rounded corner will only be an arc (part of a circle) if |
| 425 |
the angle is $90^\circ$. In other cases, the rounded corner will still be |
| 426 |
round, but ``not as nice''. |
| 427 |
|
| 428 |
Second, if there are very short line segments in a path, the ``rounding'' |
| 429 |
may cause inadvertent effects. In such case it may be necessary to |
| 430 |
temporarily switch off the rounding using |sharp corners|. |
| 431 |
\end{key} |
| 432 |
|
| 433 |
\begin{key}{/tikz/sharp corners} |
| 434 |
This options switches off any rounding on subsequent corners of the path. |
| 435 |
\end{key} |
| 436 |
|
| 437 |
|
| 438 |
\subsection{The Circle and Ellipse Operations} |
| 439 |
|
| 440 |
Circles and ellipses are common path elements for which there is a special path |
| 441 |
operation. |
| 442 |
|
| 443 |
\begin{pathoperation}{circle}{\opt{|[|\meta{options}|]|}} |
| 444 |
This command adds a circle to the current path where the center of the |
| 445 |
circle is the current point by default, but you can use the |at| option to |
| 446 |
change this. The new current point of the path will be (typically just |
| 447 |
remain) the center of the circle. |
| 448 |
|
| 449 |
The radius of the circle is specified using the following options: |
| 450 |
% |
| 451 |
\begin{key}{/tikz/x radius=\meta{value}} |
| 452 |
Sets the horizontal radius of the circle (which, when this value is |
| 453 |
different from the vertical radius, is actually an ellipse). The |
| 454 |
\meta{value} may either be a dimension or a dimensionless number. In |
| 455 |
the latter case, the number is interpreted in the $xy$-coordinate |
| 456 |
system (if the $x$-unit is set to, say, |2cm|, then |x radius=3| will |
| 457 |
have the same effect as |x radius=6cm|). |
| 458 |
\end{key} |
| 459 |
% |
| 460 |
\begin{key}{/tikz/y radius=\meta{value}} |
| 461 |
Works like the |x radius|. |
| 462 |
\end{key} |
| 463 |
% |
| 464 |
\begin{key}{/tikz/radius=\meta{value}} |
| 465 |
Sets the |x radius| and |y radius| simultaneously. |
| 466 |
\end{key} |
| 467 |
% |
| 468 |
\begin{key}{/tikz/at=\meta{coordinate}} |
| 469 |
If this option is explicitly set inside the \meta{options} (or |
| 470 |
indirectly via the |every circle| style), the \meta{coordinate} is used |
| 471 |
as the center of the circle instead of the current point. Setting |at| |
| 472 |
to some value in an enclosing scope has no effect. |
| 473 |
\end{key} |
| 474 |
The \meta{options} may also contain additional options like, say, a |
| 475 |
|rotate| or |scale|, that will only have an effect on the circle. |
| 476 |
% |
| 477 |
\begin{codeexample}[] |
| 478 |
\begin{tikzpicture} |
| 479 |
\draw (1,0) circle [radius=1.5]; |
| 480 |
\fill (1,0) circle [x radius=1cm, y radius=5mm, rotate=30]; |
| 481 |
\end{tikzpicture} |
| 482 |
\end{codeexample} |
| 483 |
|
| 484 |
It is possible to set the |radius| also in some enclosing scope, in this |
| 485 |
case the options can be left out (but see the note below on what may |
| 486 |
follow): |
| 487 |
% |
| 488 |
\begin{codeexample}[] |
| 489 |
\begin{tikzpicture}[radius=2pt] |
| 490 |
\draw (0,0) circle -- (1,1) circle -- ++(0,1) circle; |
| 491 |
\end{tikzpicture} |
| 492 |
\end{codeexample} |
| 493 |
|
| 494 |
The following style is used with every circle: |
| 495 |
% |
| 496 |
\begin{stylekey}{/tikz/every circle} |
| 497 |
You can use this key to set up, say, a default radius for every circle. |
| 498 |
The key will also be used with the |ellipse| operation. |
| 499 |
\end{stylekey} |
| 500 |
|
| 501 |
In case you feel that the names |radius| and |x radius| are too long for |
| 502 |
your taste, you can easily created shorter aliases: |
| 503 |
% |
| 504 |
\begin{codeexample}[code only] |
| 505 |
\tikzset{r/.style={radius=#1},rx/.style={x radius=#1},ry/.style={y radius=#1}} |
| 506 |
\end{codeexample} |
| 507 |
% |
| 508 |
You can then say |circle [r=1cm]| or |circle [rx=1,ry=1.5]|. The reason |
| 509 |
\tikzname\ uses the longer names by default is that it encourages people to |
| 510 |
write more readable code. |
| 511 |
|
| 512 |
\emph{Note:} There also exists an older syntax for circles, where the |
| 513 |
radius of the circle is given in parentheses right after the |circle| |
| 514 |
command as in |circle (1pt)|. Although this syntax is a bit more succinct, |
| 515 |
it is harder to understand for readers of the code and the use of |
| 516 |
parentheses for something other than a coordinate is ill-chosen. |
| 517 |
|
| 518 |
\tikzname\ will use the following rule to determine whether the old or the |
| 519 |
normal syntax is used: If |circle| is directly followed by something that |
| 520 |
(expands to) an opening parenthesis, then the old syntax is used and inside |
| 521 |
these following parentheses there must be a single number or dimension |
| 522 |
representing a radius. In all other cases the new syntax is used. |
| 523 |
\end{pathoperation} |
| 524 |
|
| 525 |
\begin{pathoperation}{ellipse}{|[|\meta{options}|]|} |
| 526 |
This command has exactly the same effect as |circle|. The older syntax for |
| 527 |
this command is |ellipse (|\meta{x radius} |and| \meta{y radius}|)|. As for |
| 528 |
the |circle| command, this syntax is not as good as the standard syntax. |
| 529 |
% |
| 530 |
\begin{codeexample}[] |
| 531 |
\begin{tikzpicture} |
| 532 |
\draw [help lines] (0,0) grid (3,2); |
| 533 |
\draw (1,1) ellipse [x radius=1cm,y radius=.5cm]; |
| 534 |
\end{tikzpicture} |
| 535 |
\end{codeexample} |
| 536 |
% |
| 537 |
\end{pathoperation} |
| 538 |
|
| 539 |
|
| 540 |
\subsection{The Arc Operation} |
| 541 |
|
| 542 |
The \emph{arc operation} allows you to add an arc to the current path. |
| 543 |
% |
| 544 |
\begin{pathoperation}{arc}{\oarg{options}} |
| 545 |
The |arc| operation adds a part of an ellipse to the current path. The |
| 546 |
radii of the ellipse are given by the values of |x radius| and |y radius|, |
| 547 |
which should be set in the \meta{options}. The arc will start at the |
| 548 |
current point and will end at the end of the arc. The arc will start and |
| 549 |
end at angles computed from the three keys |start angle|, |end angle|, and |
| 550 |
|delta angle|. Normally, the first two keys specify the start and end |
| 551 |
angle. However, in case one of them is empty, it is computed from the other |
| 552 |
key plus or minus the |delta angle|. In detail, if |end angle| is empty, it |
| 553 |
is set to the start angle plus the delta angle. If the start angle is |
| 554 |
missing, it is set to the end angle minus the delta angle. If all three |
| 555 |
keys are set, the delta angle is ignored. |
| 556 |
% |
| 557 |
\begin{key}{/tikz/start angle=\meta{degrees}} |
| 558 |
Sets the start angle. |
| 559 |
\end{key} |
| 560 |
% |
| 561 |
\begin{key}{/tikz/end angle=\meta{degrees}} |
| 562 |
Sets the end angle. |
| 563 |
\end{key} |
| 564 |
% |
| 565 |
\begin{key}{/tikz/delta angle=\meta{degrees}} |
| 566 |
Sets the delta angle. |
| 567 |
\end{key} |
| 568 |
|
| 569 |
\begin{codeexample}[] |
| 570 |
\begin{tikzpicture}[radius=1cm] |
| 571 |
\draw (0,0) arc[start angle=180, end angle=90] |
| 572 |
-- (2,.5) arc[start angle=90, delta angle=-90]; |
| 573 |
\draw (4,0) -- +(30:1cm) |
| 574 |
arc [start angle=30, delta angle=30] -- cycle; |
| 575 |
\draw (8,0) arc [start angle=0, end angle=270, |
| 576 |
x radius=1cm, y radius=5mm] -- cycle; |
| 577 |
\end{tikzpicture} |
| 578 |
\end{codeexample} |
| 579 |
|
| 580 |
\begin{codeexample}[] |
| 581 |
\begin{tikzpicture}[radius=1cm,delta angle=30] |
| 582 |
\draw (-1,0) -- +(3.5,0); |
| 583 |
\draw (1,0) ++(210:2cm) -- +(30:4cm); |
| 584 |
\draw (1,0) +(0:1cm) arc [start angle=0]; |
| 585 |
\draw (1,0) +(180:1cm) arc [start angle=180]; |
| 586 |
\path (1,0) ++(15:.75cm) node{$\alpha$}; |
| 587 |
\path (1,0) ++(15:-.75cm) node{$\beta$}; |
| 588 |
\end{tikzpicture} |
| 589 |
\end{codeexample} |
| 590 |
|
| 591 |
There also exists a shorter syntax for the arc operation, namely |arc| |
| 592 |
begin directly followed by |
| 593 |
|(|\meta{start angle}|:|\meta{end angle}|:|\meta{radius}). However, this |
| 594 |
syntax is harder to read, so the normal syntax should be preferred in |
| 595 |
general. |
| 596 |
\end{pathoperation} |
| 597 |
|
| 598 |
|
| 599 |
\subsection{The Grid Operation} |
| 600 |
|
| 601 |
You can add a grid to the current path using the |grid| path operation. |
| 602 |
|
| 603 |
\begin{pathoperation}{grid}{\opt{\oarg{options}}\meta{corner or cycle}} |
| 604 |
This operation adds a grid filling a rectangle whose two corners are given |
| 605 |
by \meta{corner} and by the previous coordinate. (Instead of a coordinate |
| 606 |
you can also say |cycle| to use the position of the last move-to as the |
| 607 |
corner coordinate, but it is not very natural to do so.) Thus, the |
| 608 |
typical way in which a grid is drawn is |\draw (1,1) grid (3,3);|, which |
| 609 |
yields a grid filling the rectangle whose corners are at $(1,1)$ and |
| 610 |
$(3,3)$. All coordinate transformations apply to the grid. |
| 611 |
% |
| 612 |
\begin{codeexample}[] |
| 613 |
\tikz[rotate=30] \draw[step=1mm] (0,0) grid (2,2); |
| 614 |
\end{codeexample} |
| 615 |
|
| 616 |
The \meta{options}, which are local to the |grid| operation, can be used to |
| 617 |
influence the appearance of the grid. The stepping of the grid is governed |
| 618 |
by the following options: |
| 619 |
% |
| 620 |
\begin{key}{/tikz/step=\meta{number or dimension or coordinate} (initially 1cm)} |
| 621 |
Sets the stepping in both the $x$ and $y$-direction. If a dimension is |
| 622 |
provided, this is used directly. If a number is provided, this number |
| 623 |
is interpreted in the $xy$-coordinate system. For example, if you |
| 624 |
provide the number |2|, then the $x$-step is twice the $x$-vector and |
| 625 |
the $y$-step is twice the $y$-vector set by the |x=| and |y=| options. |
| 626 |
Finally, if you provide a coordinate, then the $x$-part of this |
| 627 |
coordinate will be used as the $x$-step and the $y$-part will be used |
| 628 |
as the $y$-coordinate. |
| 629 |
% |
| 630 |
\begin{codeexample}[] |
| 631 |
\begin{tikzpicture}[x=.5cm] |
| 632 |
\draw[thick] (0,0) grid [step=1] (3,2); |
| 633 |
\draw[red] (0,0) grid [step=.75cm] (3,2); |
| 634 |
\end{tikzpicture} |
| 635 |
\begin{tikzpicture} |
| 636 |
\draw (0,0) circle [radius=1]; |
| 637 |
\draw[blue] (0,0) grid [step=(45:1)] (3,2); |
| 638 |
\end{tikzpicture} |
| 639 |
\end{codeexample} |
| 640 |
|
| 641 |
A complication arises when the $x$- and/or $y$-vector do not point |
| 642 |
along the axes. Because of this, the actual rule for computing the |
| 643 |
$x$-step and the $y$-step is the following: As the $x$- and $y$-steps |
| 644 |
we use the $x$- and $y$-components or the following two vectors: The |
| 645 |
first vector is either $(\meta{x-grid-step-number},0)$ or |
| 646 |
$(\meta{x-grid-step-dimension},0\mathrm{pt})$, the second vector is |
| 647 |
$(0,\meta{y-grid-step-number})$ or |
| 648 |
$(0\mathrm{pt},\meta{y-grid-step-dimension})$. |
| 649 |
|
| 650 |
If the $x$-step or $y$-step is $0$ or negative the corresponding lines |
| 651 |
are not drawn. |
| 652 |
\end{key} |
| 653 |
|
| 654 |
\begin{key}{/tikz/xstep=\meta{dimension or number} (initially 1cm)} |
| 655 |
Sets the stepping in the $x$-direction. |
| 656 |
% |
| 657 |
\begin{codeexample}[] |
| 658 |
\begin{tikzpicture} |
| 659 |
\draw (0,0) grid [xstep=.5,ystep=.75] (3,2); |
| 660 |
\draw[ultra thick] (0,0) grid [ystep=0] (3,2); |
| 661 |
\end{tikzpicture} |
| 662 |
\end{codeexample} |
| 663 |
\end{key} |
| 664 |
|
| 665 |
\begin{key}{/tikz/ystep=\meta{dimension or number} (initially 1cm)} |
| 666 |
Sets the stepping in the $y$-direction. |
| 667 |
\end{key} |
| 668 |
|
| 669 |
It is important to note that the grid is always ``phased'' such that it |
| 670 |
contains the point $(0,0)$ if that point happens to be inside the |
| 671 |
rectangle. Thus, the grid does \emph{not} always have an intersection at |
| 672 |
the corner points; this occurs only if the corner points are multiples of |
| 673 |
the stepping. Note that due to rounding errors, the ``last'' lines of a |
| 674 |
grid may be omitted. In this case, you have to add an epsilon to the corner |
| 675 |
points. |
| 676 |
|
| 677 |
The following style is useful for drawing grids: |
| 678 |
% |
| 679 |
\begin{stylekey}{/tikz/help lines (initially {line width=0.2pt,gray})} |
| 680 |
This style makes lines ``subdued'' by using thin gray lines for them. |
| 681 |
However, this style is not installed automatically and you have to say |
| 682 |
for example: |
| 683 |
% |
| 684 |
\begin{codeexample}[] |
| 685 |
\tikz \draw[help lines] (0,0) grid (3,3); |
| 686 |
\end{codeexample} |
| 687 |
\end{stylekey} |
| 688 |
\end{pathoperation} |
| 689 |
|
| 690 |
|
| 691 |
\subsection{The Parabola Operation} |
| 692 |
|
| 693 |
The |parabola| path operation continues the current path with a parabola. A |
| 694 |
parabola is a (shifted and scaled) curve defined by the equation $f(x) = x^2$ |
| 695 |
and looks like this: \tikz \draw (-1ex,1.5ex) parabola[parabola height=-1.5ex] |
| 696 |
+(2ex,0ex);. |
| 697 |
|
| 698 |
\begin{pathoperation}{parabola}{\opt{\oarg{options}|bend|\meta{bend |
| 699 |
coordinate}}\meta{coordinate or cycle}} |
| 700 |
This operation adds a parabola through the current point and the given |
| 701 |
\meta{coordinate} or, if |cycle| is used instead of coordinate at the end, |
| 702 |
the \meta{coordinate} is set to the position of the last move-to and the |
| 703 |
path gets closed after the parabola. If the |bend| is given, it specifies |
| 704 |
where the bend should go; the \meta{options} can also be used to specify |
| 705 |
where the bend is. By default, the bend is at the old current point. |
| 706 |
% |
| 707 |
\begin{codeexample}[] |
| 708 |
\begin{tikzpicture} |
| 709 |
\draw (0,0) rectangle (1,1.5) |
| 710 |
(0,0) parabola (1,1.5); |
| 711 |
\draw[xshift=1.5cm] (0,0) rectangle (1,1.5) |
| 712 |
(0,0) parabola[bend at end] (1,1.5); |
| 713 |
\draw[xshift=3cm] (0,0) rectangle (1,1.5) |
| 714 |
(0,0) parabola bend (.75,1.75) (1,1.5); |
| 715 |
|
| 716 |
\draw[yshift=-2cm] (1,1.5) -- |
| 717 |
(0,0) parabola cycle; |
| 718 |
\end{tikzpicture} |
| 719 |
\end{codeexample} |
| 720 |
|
| 721 |
The following options influence parabolas: |
| 722 |
% |
| 723 |
\begin{key}{/tikz/bend=\meta{coordinate}} |
| 724 |
Has the same effect as saying |bend|\meta{coordinate} outside the |
| 725 |
\meta{options}. The option specifies that the bend of the parabola |
| 726 |
should be at the given \meta{coordinate}. You have to take care |
| 727 |
yourself that the bend position is a ``valid'' position; which means |
| 728 |
that if there is no parabola of the form $f(x) = a x^2 + b x + c$ that |
| 729 |
goes through the old current point, the given bend, and the new current |
| 730 |
point, the result will not be a parabola. |
| 731 |
|
| 732 |
There is one special property of the \meta{coordinate}: When a relative |
| 733 |
coordinate is given like |+(0,0)|, the position relative to this |
| 734 |
coordinate is ``flexible''. More precisely, this position lies |
| 735 |
somewhere on a line from the old current point to the new current |
| 736 |
point. The exact position depends on the next option. |
| 737 |
\end{key} |
| 738 |
|
| 739 |
\begin{key}{/tikz/bend pos=\meta{fraction}} |
| 740 |
Specifies where the ``previous'' point is relative to which the bend is |
| 741 |
calculated. The previous point will be at the \meta{fraction}th part of |
| 742 |
the line from the old current point to the new current point. |
| 743 |
|
| 744 |
The idea is the following: If you say |bend pos=0| and |bend +(0,0)|, |
| 745 |
the bend will be at the old current point. If you say |bend pos=1| and |
| 746 |
|bend +(0,0)|, the bend will be at the new current point. If you say |
| 747 |
|bend pos=0.5| and |bend +(0,2cm)| the bend will be 2cm above the |
| 748 |
middle of the line between the start and end point. This is most useful |
| 749 |
in situations such as the following: |
| 750 |
% |
| 751 |
\begin{codeexample}[] |
| 752 |
\begin{tikzpicture} |
| 753 |
\draw[help lines] (0,0) grid (3,2); |
| 754 |
\draw (-1,0) parabola[bend pos=0.5] bend +(0,2) +(3,0); |
| 755 |
\end{tikzpicture} |
| 756 |
\end{codeexample} |
| 757 |
|
| 758 |
In the above example, the |bend +(0,2)| essentially means ``a parabola |
| 759 |
that is 2cm high'' and |+(3,0)| means ``and 3cm wide''. Since this |
| 760 |
situation arises often, there is a special shortcut option: |
| 761 |
% |
| 762 |
\begin{key}{/tikz/parabola height=\meta{dimension}} |
| 763 |
This option has the same effect as |
| 764 |
|[bend pos=0.5,bend={+(0pt,|\meta{dimension}|)}]|. |
| 765 |
% |
| 766 |
\begin{codeexample}[] |
| 767 |
\begin{tikzpicture} |
| 768 |
\draw[help lines] (0,0) grid (3,2); |
| 769 |
\draw (-1,0) parabola[parabola height=2cm] +(3,0); |
| 770 |
\end{tikzpicture} |
| 771 |
\end{codeexample} |
| 772 |
\end{key} |
| 773 |
\end{key} |
| 774 |
|
| 775 |
The following styles are useful shortcuts: |
| 776 |
% |
| 777 |
\begin{stylekey}{/tikz/bend at start} |
| 778 |
This places the bend at the start of a parabola. It is a shortcut for |
| 779 |
the following options: |bend pos=0,bend={+(0,0)}|. |
| 780 |
\end{stylekey} |
| 781 |
|
| 782 |
\begin{stylekey}{/tikz/bend at end} |
| 783 |
This places the bend at the end of a parabola. |
| 784 |
\end{stylekey} |
| 785 |
\end{pathoperation} |
| 786 |
|
| 787 |
|
| 788 |
\subsection{The Sine and Cosine Operation} |
| 789 |
|
| 790 |
The |sin| and |cos| operations are similar to the |parabola| operation. They, |
| 791 |
too, can be used to draw (parts of) a sine or cosine curve. |
| 792 |
|
| 793 |
\begin{pathoperation}{sin}{\meta{coordinate or cycle}} |
| 794 |
The effect of |sin| is to draw a scaled and shifted version of a sine curve |
| 795 |
in the interval $[0,\pi/2]$. The scaling and shifting is done in such a way |
| 796 |
that the start of the sine curve in the interval is at the old current |
| 797 |
point and that the end of the curve in the interval is at |
| 798 |
\meta{coordinate}. Here is an example that should clarify this: |
| 799 |
% |
| 800 |
\begin{codeexample}[] |
| 801 |
\tikz \draw (0,0) rectangle (1,1) (0,0) sin (1,1) |
| 802 |
(2,0) rectangle +(1.57,1) (2,0) sin +(1.57,1); |
| 803 |
\end{codeexample} |
| 804 |
% |
| 805 |
\end{pathoperation} |
| 806 |
|
| 807 |
\begin{pathoperation}{cos}{\meta{coordinate or cycle}} |
| 808 |
This operation works similarly, only a cosine in the interval $[0,\pi/2]$ |
| 809 |
is drawn. By correctly alternating |sin| and |cos| operations, you can |
| 810 |
create a complete sine or cosine curve: |
| 811 |
% |
| 812 |
\begin{codeexample}[] |
| 813 |
\begin{tikzpicture}[xscale=1.57] |
| 814 |
\draw (0,0) sin (1,1) cos (2,0) sin (3,-1) cos (4,0) sin (5,1); |
| 815 |
\draw[color=red] (0,1.5) cos (1,0) sin (2,-1.5) cos (3,0) sin (4,1.5) cos (5,0); |
| 816 |
\end{tikzpicture} |
| 817 |
\end{codeexample} |
| 818 |
% |
| 819 |
\end{pathoperation} |
| 820 |
|
| 821 |
Note that there is no way to (conveniently) draw an interval on a sine or |
| 822 |
cosine curve whose end points are not multiples of $\pi/2$. |
| 823 |
|
| 824 |
|
| 825 |
\subsection{The SVG Operation} |
| 826 |
|
| 827 |
The |svg| operation can be used to extend the current path by a path given in |
| 828 |
the \textsc{svg} path data syntax. This syntax is described in detail in |
| 829 |
Section~8.3 of the \textsc{svg 1.1} specification, please consult this |
| 830 |
specification for details. |
| 831 |
|
| 832 |
\begin{pathoperation}{svg}{\opt{\oarg{options}}\marg{path data}} |
| 833 |
This operation adds the path specified in the \meta{path data} in |
| 834 |
\textsc{svg 1.1 path data} syntax to the current path. Unlike the |
| 835 |
\textsc{svg}-specification, it \emph{is} permissible that the path data |
| 836 |
does not start with a move-to command (|m| or |M|), in which case the last |
| 837 |
point of the current path is used as start point. The optional |
| 838 |
\meta{options} apply locally to this path operation, typically you will use |
| 839 |
them to set up, say, some transformations. |
| 840 |
% |
| 841 |
\begin{codeexample}[preamble={\usetikzlibrary{svg.path}}] |
| 842 |
\begin{tikzpicture} |
| 843 |
\filldraw [fill=red!20] (0,1) svg[scale=2] {h 10 v 10 h -10} |
| 844 |
node [above left] {upper left} -- cycle; |
| 845 |
|
| 846 |
\draw svg {M 0 0 L 20 20 h 10 a 10 10 0 0 0 -20 0}; |
| 847 |
\end{tikzpicture} |
| 848 |
\end{codeexample} |
| 849 |
|
| 850 |
An \textsc{svg} coordinate like |10 20| is always interpreted as |
| 851 |
|(10pt,20pt)|, so the basic unit is always points (|pt|). The |
| 852 |
$xy$-coordinate system is not used. However, you can use scaling to |
| 853 |
(locally) change the basic unit. For instance, |svg[scale=1cm]| (yes, this |
| 854 |
works, although some rather evil magic is involved) will cause 1cm to be |
| 855 |
the basic unit. |
| 856 |
|
| 857 |
Instead of curly braces, you can also use quotation marks to indicate the |
| 858 |
start and end of the \textsc{svg} path. |
| 859 |
|
| 860 |
\emph{Warning:} The arc operations (|a| and |A|) are numerically instable. |
| 861 |
This means that they will be quite imprecise, except when the angle is a |
| 862 |
multiple of $90^\circ$ (as is, fortunately, most often the case). |
| 863 |
\end{pathoperation} |
| 864 |
|
| 865 |
|
| 866 |
\subsection{The Plot Operation} |
| 867 |
|
| 868 |
The |plot| operation can be used to append a line or curve to the path that |
| 869 |
goes through a large number of coordinates. These coordinates are either given |
| 870 |
in a simple list of coordinates, read from some file, or they are computed on |
| 871 |
the fly. |
| 872 |
|
| 873 |
Since the syntax and the behavior of this command are a bit complex, they are |
| 874 |
described in the separated Section~\ref{section-tikz-plots}. |
| 875 |
|
| 876 |
|
| 877 |
\subsection{The To Path Operation} |
| 878 |
|
| 879 |
The |to| operation is used to add a user-defined path from the previous |
| 880 |
coordinate to the following coordinate. When you write |(a) to (b)|, a straight |
| 881 |
line is added from |a| to |b|, exactly as if you had written |(a) -- (b)|. |
| 882 |
However, if you write |(a) to [out=135,in=45] (b)| a curve is added to the |
| 883 |
path, which leaves at an angle of 135$^\circ$ at |a| and arrives at an angle of |
| 884 |
45$^\circ$ at |b|. This is because the options |in| and |out| trigger a special |
| 885 |
path to be used instead of the straight line. |
| 886 |
|
| 887 |
\begin{pathoperation}{to}{\opt{|[|\meta{options}|]|} |
| 888 |
\opt{\meta{nodes}} \meta{coordinate or cycle}} |
| 889 |
This path operation inserts the path currently set via the |to path| option |
| 890 |
at the current position. The \meta{options} can be used to modify (perhaps |
| 891 |
implicitly) the |to path| and to set up how the path will be rendered. |
| 892 |
|
| 893 |
Before the |to path| is inserted, a number of macros are set up that can |
| 894 |
``help'' the |to path|. These are |\tikztostart|, |\tikztotarget|, and |
| 895 |
|\tikztonodes|; they are explained in the following. |
| 896 |
|
| 897 |
\medskip |
| 898 |
\textbf{Start and Target Coordinates.}\ \ |
| 899 |
The |to| operation is always followed by a \meta{coordinate}, called the |
| 900 |
target coordinate, or the text |cycle|, in which case the last move-to is |
| 901 |
used as a coordinate and the path gets closed. The macro |\tikztotarget| is |
| 902 |
set to this coordinate (without its parentheses). There is also a |
| 903 |
\emph{start coordinate}, which is the coordinate preceding the |to| |
| 904 |
operation. This coordinate can be accessed via the macro |\tikztostart|. In |
| 905 |
the following example, for the first |to|, the macro |\tikztostart| is |
| 906 |
|0pt,0pt| and the |\tikztotarget| is |0,2|. For the second |to|, the macro |
| 907 |
|\tikztostart| is |10pt,10pt| and |\tikztotarget| is |a|. For the third, |
| 908 |
they are set to |a| and |current subpath start|. |
| 909 |
% |
| 910 |
\begin{codeexample}[] |
| 911 |
\begin{tikzpicture} |
| 912 |
\draw[help lines] (0,0) grid (3,2); |
| 913 |
\node (a) at (2,2) {a}; |
| 914 |
|
| 915 |
\draw (0,0) to (0,2); |
| 916 |
\draw[red] (10pt,10pt) to (a); |
| 917 |
\draw[blue] (3,0) -- (3,2) -- (a) to cycle; |
| 918 |
\end{tikzpicture} |
| 919 |
\end{codeexample} |
| 920 |
|
| 921 |
\medskip |
| 922 |
\textbf{Nodes on to--paths.}\ \ |
| 923 |
It is possible to add nodes to the paths constructed by a |to| operation. |
| 924 |
To do so, you specify the nodes between the |to| keyword and the coordinate |
| 925 |
(if there are options to the |to| operation, these come first). The effect |
| 926 |
of |(a) to node {x} (b)| (typically) is the same as if you had written |
| 927 |
|(a) -- node {x} (b)|, namely that the node is placed on the |to|. This can |
| 928 |
be used to add labels to |to|s: |
| 929 |
% |
| 930 |
\begin{codeexample}[] |
| 931 |
\begin{tikzpicture} |
| 932 |
\draw (0,0) to node [sloped,above] {x} (3,2); |
| 933 |
|
| 934 |
\draw (0,0) to[out=90,in=180] node [sloped,above] {x} (3,2); |
| 935 |
\end{tikzpicture} |
| 936 |
\end{codeexample} |
| 937 |
|
| 938 |
Instead of writing the node between the |to| keyword and the target |
| 939 |
coordinate, you may also use the following keys to create such nodes: |
| 940 |
% |
| 941 |
\begin{key}{/tikz/edge node=\meta{node specification}} |
| 942 |
This key can be used inside the \meta{options} of a |to| path command. |
| 943 |
It will add the \meta{node specification} to the list of nodes to be |
| 944 |
placed on the connecting line, just as if you had written the |
| 945 |
\meta{node specification} directly after the |to| keyword: |
| 946 |
% |
| 947 |
\begin{codeexample}[] |
| 948 |
\begin{tikzpicture} |
| 949 |
\draw (0,0) to [edge node={node [sloped,above] {x}}] (3,2); |
| 950 |
|
| 951 |
\draw (0,0) to [out=90,in=180, |
| 952 |
edge node={node [sloped,above] {x}}] (3,2); |
| 953 |
\end{tikzpicture} |
| 954 |
\end{codeexample} |
| 955 |
% |
| 956 |
This key is mostly useful to create labels automatically using other |
| 957 |
keys. |
| 958 |
\end{key} |
| 959 |
% |
| 960 |
\begin{key}{/tikz/edge label=\meta{text}} |
| 961 |
A shorthand for |edge node={node[auto]{|\meta{text}|}}|. |
| 962 |
% |
| 963 |
\begin{codeexample}[] |
| 964 |
\tikz \draw (0,0) to [edge label=x] (3,2); |
| 965 |
\end{codeexample} |
| 966 |
\end{key} |
| 967 |
% |
| 968 |
\begin{key}{/tikz/edge label'=\meta{text}} |
| 969 |
A shorthand for |edge node={node[auto,swap]{|\meta{text}|}}|. |
| 970 |
% |
| 971 |
\begin{codeexample}[] |
| 972 |
\tikz \draw (0,0) to [edge label=x, edge label'=y] (3,2); |
| 973 |
\end{codeexample} |
| 974 |
\end{key} |
| 975 |
|
| 976 |
When the |quotes| library is loaded, additional ways of specifying nodes on |
| 977 |
to--paths become available, see Section~\ref{section-edge-quotes}. |
| 978 |
|
| 979 |
\medskip |
| 980 |
\textbf{Styles for to-paths.}\ \ |
| 981 |
In addition to the \meta{options} given after the |to| operation, the |
| 982 |
following style is also set at the beginning of the to path: |
| 983 |
% |
| 984 |
\begin{stylekey}{/tikz/every to (initially \normalfont empty)} |
| 985 |
This style is installed at the beginning of every to. |
| 986 |
% |
| 987 |
\begin{codeexample}[] |
| 988 |
\tikz[every to/.style={bend left}] |
| 989 |
\draw (0,0) to (3,2); |
| 990 |
\end{codeexample} |
| 991 |
% |
| 992 |
Note that, as explained below, every to path is implicitly surrounded |
| 993 |
by curly braces. This means that options like |draw| given in an |
| 994 |
|every to| do not actually influence the path. You can fix this by |
| 995 |
using the |append after command| option: |
| 996 |
% |
| 997 |
\begin{codeexample}[] |
| 998 |
\tikz[every to/.style={append after command={[draw,dashed]}}] |
| 999 |
\draw (0,0) to (3,2); |
| 1000 |
\end{codeexample} |
| 1001 |
\end{stylekey} |
| 1002 |
|
| 1003 |
\medskip |
| 1004 |
\textbf{Options.}\ \ |
| 1005 |
The \meta{options} given with the |to| allow you to influence the |
| 1006 |
appearance of the |to path|. Mostly, these options are used to change the |
| 1007 |
|to path|. This can be used to change the path from a straight line to, |
| 1008 |
say, a curve. |
| 1009 |
|
| 1010 |
The path used is set using the following option: |
| 1011 |
% |
| 1012 |
\begin{key}{/tikz/to path=\meta{path}} |
| 1013 |
Whenever a |to| operation is used, the \meta{path} is inserted. More |
| 1014 |
precisely, the following path is added: |
| 1015 |
% |
| 1016 |
\begin{quote} |
| 1017 |
|{[every to,|\meta{options}|] |\meta{path} |}| |
| 1018 |
\end{quote} |
| 1019 |
|
| 1020 |
The \meta{options} are the options given to the |to| operation, the |
| 1021 |
\meta{path} is the path set by this option |to path|. |
| 1022 |
|
| 1023 |
Inside the \meta{path}, different macros are used to reference the |
| 1024 |
from- and to-coordinates. In detail, these are: |
| 1025 |
% |
| 1026 |
\begin{itemize} |
| 1027 |
\item \declareandlabel{\tikztostart} will expand to the |
| 1028 |
from-coordinate (without the parentheses). |
| 1029 |
\item \declareandlabel{\tikztotarget} will expand to the |
| 1030 |
to-coordinate. |
| 1031 |
\item \declareandlabel{\tikztonodes} will expand to the nodes |
| 1032 |
between the |to| operation and the coordinate. Furthermore, |
| 1033 |
these nodes will have the |pos| option set implicitly. |
| 1034 |
\end{itemize} |
| 1035 |
|
| 1036 |
Let us have a look at a simple example. The standard straight line for |
| 1037 |
a |to| is achieved by the following \meta{path}: |
| 1038 |
% |
| 1039 |
\begin{quote} |
| 1040 |
|-- (\tikztotarget) \tikztonodes| |
| 1041 |
\end{quote} |
| 1042 |
|
| 1043 |
Indeed, this is the default setting for the path. When we write |
| 1044 |
|(a) to (b)|, the \meta{path} will expand to |(a) -- (b)|, when we |
| 1045 |
write |
| 1046 |
% |
| 1047 |
\begin{quote} |
| 1048 |
|(a) to[red] node {x} (b)| |
| 1049 |
\end{quote} |
| 1050 |
% |
| 1051 |
the \meta{path} will expand to |
| 1052 |
% |
| 1053 |
\begin{quote} |
| 1054 |
|(a) -- (b) node[red] {x}| |
| 1055 |
\end{quote} |
| 1056 |
|
| 1057 |
It is not possible to specify the path |
| 1058 |
% |
| 1059 |
\begin{quote} |
| 1060 |
|-- \tikztonodes (\tikztotarget)| |
| 1061 |
\end{quote} |
| 1062 |
% |
| 1063 |
since \tikzname\ does not allow one to have a macro after |--| that |
| 1064 |
expands to a node. |
| 1065 |
|
| 1066 |
Now let us have a look at how we can modify the \meta{path} sensibly. |
| 1067 |
The simplest way is to use a curve. |
| 1068 |
% |
| 1069 |
\begin{codeexample}[] |
| 1070 |
\begin{tikzpicture}[to path={ |
| 1071 |
.. controls +(1,0) and +(1,0) .. (\tikztotarget) \tikztonodes}] |
| 1072 |
|
| 1073 |
\node (a) at (0,0) {a}; |
| 1074 |
\node (b) at (2,1) {b}; |
| 1075 |
\node (c) at (1,2) {c}; |
| 1076 |
|
| 1077 |
\draw (a) to node {x} (b) |
| 1078 |
(a) to (c); |
| 1079 |
\end{tikzpicture} |
| 1080 |
\end{codeexample} |
| 1081 |
|
| 1082 |
Here is another example: |
| 1083 |
% |
| 1084 |
\begin{codeexample}[] |
| 1085 |
\tikzset{ |
| 1086 |
my loop/.style={to path={ |
| 1087 |
.. controls +(80:1) and +(100:1) .. (\tikztotarget) \tikztonodes}}, |
| 1088 |
my state/.style={circle,draw}} |
| 1089 |
|
| 1090 |
\begin{tikzpicture}[shorten >=2pt] |
| 1091 |
\node [my state] (a) at (210:1) {$q_a$}; |
| 1092 |
\node [my state] (b) at (330:1) {$q_b$}; |
| 1093 |
|
| 1094 |
\draw[->] (a) to node[below] {1} (b) |
| 1095 |
to [my loop] node[above right] {0} (b); |
| 1096 |
\end{tikzpicture} |
| 1097 |
\end{codeexample} |
| 1098 |
|
| 1099 |
\begin{key}{/tikz/execute at begin to=\meta{code}} |
| 1100 |
The \meta{code} is executed prior to the |to|. This can be used to |
| 1101 |
draw one or more additional paths or to do additional computations. |
| 1102 |
\end{key} |
| 1103 |
|
| 1104 |
\begin{key}{/tikz/execute at end to=\meta{code}} |
| 1105 |
Works like the previous option, only this code is executed after |
| 1106 |
the to path has been added. |
| 1107 |
% FIXME : provide examples... |
| 1108 |
\end{key} |
| 1109 |
|
| 1110 |
\begin{stylekey}{/tikz/every to (initially \normalfont empty)} |
| 1111 |
This style is installed at the beginning of every to. |
| 1112 |
\end{stylekey} |
| 1113 |
\end{key} |
| 1114 |
\end{pathoperation} |
| 1115 |
|
| 1116 |
There are a number of predefined |to path|s, see Section~\ref{library-to-paths} |
| 1117 |
for a reference. |
| 1118 |
|
| 1119 |
|
| 1120 |
\subsection{The Foreach Operation} |
| 1121 |
|
| 1122 |
\begin{pathoperation}{foreach}{\meta{variables}\opt{\oarg{options}} |in| |
| 1123 |
\meta{list} \marg{path commands}} |
| 1124 |
The |foreach| operation can be used to repeatedly insert the \meta{path |
| 1125 |
commands} into the current path. Naturally, the \meta{path commands} should |
| 1126 |
internally reference some of the \meta{variables} so that you do not insert |
| 1127 |
exactly the same path repeatedly, but rather variations. For historical |
| 1128 |
reasons, you can also write |\foreach| instead of |foreach|. |
| 1129 |
% |
| 1130 |
\begin{codeexample}[] |
| 1131 |
\tikz \draw (0,0) foreach \x in {1,...,3} { -- (\x,1) -- (\x,0) }; |
| 1132 |
\end{codeexample} |
| 1133 |
% |
| 1134 |
See Section~\ref{section-foreach} for more details on the for-each-command. |
| 1135 |
\end{pathoperation} |
| 1136 |
|
| 1137 |
|
| 1138 |
\subsection{The Let Operation} |
| 1139 |
|
| 1140 |
The \emph{let operation} is the first of a number of path operations that do |
| 1141 |
not actually extend that path, but have different, mostly local, effects. |
| 1142 |
It requires the |calc| library, see Section~\ref{tikz-lib-calc}. |
| 1143 |
|
| 1144 |
\begin{pathoperation}{let}{\meta{assignment} |
| 1145 |
\opt{|,|\meta{assignment}}% |
| 1146 |
\opt{|,|\meta{assignment}\dots}\declare{| in |}} |
| 1147 |
When this path operation is encountered, the \meta{assignment}s are |
| 1148 |
evaluated, one by one. This will store coordinate and number in |
| 1149 |
special \emph{registers} (which are local to \tikzname, they have |
| 1150 |
nothing to do with \TeX\ registers). Subsequently, one can access the |
| 1151 |
contents of these registers using the macros |\p|, |\x|, |\y|, and |
| 1152 |
|\n|. |
| 1153 |
|
| 1154 |
The first kind of permissible \meta{assignment}s have the following form: |
| 1155 |
% |
| 1156 |
\begin{quote} |
| 1157 |
|\n|\meta{number register}|={|\meta{formula}|}| |
| 1158 |
\end{quote} |
| 1159 |
% |
| 1160 |
When an assignment has this form, the \meta{formula} is evaluated using the |
| 1161 |
|\pgfmathparse| operation. The result is stored in the \meta{number |
| 1162 |
register}. If the \meta{formula} involves a dimension anywhere (as in |
| 1163 |
|2*3cm/2|), then the \meta{number register} stores the resulting dimension |
| 1164 |
with a trailing |pt|. A \meta{number register} can be named arbitrarily |
| 1165 |
and is a normal \TeX\ parameter to the |\n| macro. Possible names are |
| 1166 |
|{left corner}|, but also just a single digit like~|5|. |
| 1167 |
|
| 1168 |
Let us call the path that follows a let operation its \emph{body}. Inside |
| 1169 |
the body, the |\n| macro can be used to access the register. |
| 1170 |
% |
| 1171 |
\begin{command}{\n\marg{number register}} |
| 1172 |
When this macro is used on the left-hand side of an |=|-sign in a let |
| 1173 |
operation, it has no effect and is just there for readability. When the |
| 1174 |
macro is used on the right-hand side of an |=|-sign or in the body of |
| 1175 |
the let operation, then it expands to the value stored in the |
| 1176 |
\meta{number register}. This will either be a dimensionless number like |
| 1177 |
|2.0| or a dimension like |5.6pt|. |
| 1178 |
|
| 1179 |
For instance, if we say |let \n1={1pt+2pt}, \n2={1+2} in ...|, then |
| 1180 |
inside the |...| part the macro |\n1| will expand to |3pt| and |\n2| |
| 1181 |
expands to |3|. |
| 1182 |
\end{command} |
| 1183 |
|
| 1184 |
The second kind of \meta{assignments} have the following form: |
| 1185 |
% |
| 1186 |
\begin{quote} |
| 1187 |
|\p|\meta{point register}|=|\meta{coordinate} |
| 1188 |
\end{quote} |
| 1189 |
% |
| 1190 |
Point position registers store a single point, consisting of an $x$-part |
| 1191 |
and a $y$-part measured in \TeX\ points (|pt|). In particular, point |
| 1192 |
registers do not store nodes or node names. Here is an example: |
| 1193 |
% |
| 1194 |
\begin{codeexample}[preamble={\usetikzlibrary{calc}}] |
| 1195 |
\begin{tikzpicture} |
| 1196 |
\draw [help lines] (0,0) grid (3,2); |
| 1197 |
|
| 1198 |
\draw let \p{foo} = (1,1), \p2 = (2,0) in |
| 1199 |
(0,0) -- (\p2) -- (\p{foo}); |
| 1200 |
\end{tikzpicture} |
| 1201 |
\end{codeexample} |
| 1202 |
|
| 1203 |
\begin{command}{\p\marg{point register}} |
| 1204 |
When this macro is used on the left-hand side of an |=|-sign in a let |
| 1205 |
operation, it has no effect and is just there for readability. When the |
| 1206 |
macro is used on the right-hand side of an |=|-sign or in the body of |
| 1207 |
the let operation, then it expands to the $x$-part (measured in \TeX\ |
| 1208 |
points) of the coordinate stored in the \meta{register}, followed, by a |
| 1209 |
comma, followed by the $y$-part. |
| 1210 |
|
| 1211 |
For instance, if we say |let \p1=(1pt,1pt+2pt) in ...|, then inside the |
| 1212 |
|...| part the macro |\p1| will expand to exactly the seven characters |
| 1213 |
``1pt,3pt''. This means that you when you write |(\p1)|, this expands |
| 1214 |
to |(1pt,3pt)|, which is presumably exactly what you intended. |
| 1215 |
\end{command} |
| 1216 |
% |
| 1217 |
\begin{command}{\x\marg{point register}} |
| 1218 |
This macro expands just to the $x$-part of the point register. If we |
| 1219 |
say as above, as we did above, |let \p1=(1pt,1pt+2pt) in ...|, then |
| 1220 |
inside the |...| part the macro |\x1| expands to |1pt|. |
| 1221 |
\end{command} |
| 1222 |
% |
| 1223 |
\begin{command}{\y\marg{point register}} |
| 1224 |
Works like |\x|, only for the $y$-part. |
| 1225 |
\end{command} |
| 1226 |
% |
| 1227 |
Note that the above macros are available only inside a let operation. |
| 1228 |
|
| 1229 |
Here is an example where let clauses are used to assemble a coordinate from |
| 1230 |
the $x$-coordinate of a first point and the $y$-coordinate of a second |
| 1231 |
point. Naturally, using the \verb!|-! notation, this could be written much |
| 1232 |
more compactly. |
| 1233 |
% |
| 1234 |
\begin{codeexample}[preamble={\usetikzlibrary{calc}}] |
| 1235 |
\begin{tikzpicture} |
| 1236 |
\draw [help lines] (0,0) grid (3,2); |
| 1237 |
|
| 1238 |
\draw (1,0) coordinate (first point) |
| 1239 |
-- (3,2) coordinate (second point); |
| 1240 |
|
| 1241 |
\fill[red] let \p1 = (first point), |
| 1242 |
\p2 = (second point) in |
| 1243 |
(\x1,\y2) circle [radius=2pt]; |
| 1244 |
\end{tikzpicture} |
| 1245 |
\end{codeexample} |
| 1246 |
|
| 1247 |
Note that the effect of a let operation is local to the body of the let |
| 1248 |
operation. If you wish to access a computed coordinate outside the body, |
| 1249 |
you must use a |coordinate| path operation: |
| 1250 |
% |
| 1251 |
\begin{codeexample}[preamble={\usetikzlibrary{calc}}] |
| 1252 |
\begin{tikzpicture} |
| 1253 |
\draw [help lines] (0,0) grid (3,2); |
| 1254 |
|
| 1255 |
\path % let's define some points: |
| 1256 |
let |
| 1257 |
\p1 = (1,0), |
| 1258 |
\p2 = (3,2), |
| 1259 |
\p{center} = ($ (\p1) !.5! (\p2) $) % center |
| 1260 |
in |
| 1261 |
coordinate (p1) at (\p1) |
| 1262 |
coordinate (p2) at (\p2) |
| 1263 |
coordinate (center) at (\p{center}); |
| 1264 |
|
| 1265 |
\draw (p1) -- (p2); |
| 1266 |
\fill[red] (center) circle [radius=2pt]; |
| 1267 |
\end{tikzpicture} |
| 1268 |
\end{codeexample} |
| 1269 |
|
| 1270 |
For a more useful application of the let operation, let us draw a circle |
| 1271 |
that touches a given line: |
| 1272 |
% |
| 1273 |
\begin{codeexample}[pre={\pgfmathsetseed{1}},preamble={\usetikzlibrary{calc}}] |
| 1274 |
\begin{tikzpicture} |
| 1275 |
\draw [help lines] (0,0) grid (3,3); |
| 1276 |
|
| 1277 |
\coordinate (a) at (rnd,rnd); |
| 1278 |
\coordinate (b) at (3-rnd,3-rnd); |
| 1279 |
\draw (a) -- (b); |
| 1280 |
|
| 1281 |
\node (c) at (1,2) {x}; |
| 1282 |
|
| 1283 |
\draw let \p1 = ($ (a)!(c)!(b) - (c) $), |
| 1284 |
\n1 = {veclen(\x1,\y1)} |
| 1285 |
in circle [at=(c), radius=\n1]; |
| 1286 |
\end{tikzpicture} |
| 1287 |
\end{codeexample} |
| 1288 |
% |
| 1289 |
\end{pathoperation} |
| 1290 |
|
| 1291 |
|
| 1292 |
\subsection{The Scoping Operation} |
| 1293 |
|
| 1294 |
When \tikzname\ encounters and opening or a closing brace (|{| or~|}|) at some |
| 1295 |
point where a path operation should come, it will open or close a scope. All |
| 1296 |
options that can be applied ``locally'' will be scoped inside the scope. For |
| 1297 |
example, if you apply a transformation like |[xshift=1cm]| inside the scoped |
| 1298 |
area, the shifting only applies to the scope. On the other hand, an option like |
| 1299 |
|color=red| does not have any effect inside a scope since it can only be |
| 1300 |
applied to the path as a whole. |
| 1301 |
|
| 1302 |
Concerning the effect of scopes on relative coordinates, please see |
| 1303 |
Section~\ref{section-scopes-relative}. |
| 1304 |
|
| 1305 |
|
| 1306 |
\subsection{The Node and Edge Operations} |
| 1307 |
|
| 1308 |
The |node| operation adds a so-called node to a path. This operation is special |
| 1309 |
in the following sense: It does not change the current path in any way. In |
| 1310 |
other words, this operation is not really a path operation, but has an effect |
| 1311 |
that is ``external'' to the path. The |edge| operation has similar effect in |
| 1312 |
that it adds something \emph{after} the main path has been drawn. However, it |
| 1313 |
works like the |to| operation, that is, it adds a |to| path to the picture |
| 1314 |
after the main path has been drawn. |
| 1315 |
|
| 1316 |
Since these operations are quite complex, they are described in the separate |
| 1317 |
Section~\ref{section-nodes}. |
| 1318 |
|
| 1319 |
|
| 1320 |
\subsection{The Graph Operation} |
| 1321 |
|
| 1322 |
The |graph| operation can be used to specify easily how a large number of nodes |
| 1323 |
are connected. This operation is documented in a separate section, see |
| 1324 |
Section~\ref{section-library-graphs}. |
| 1325 |
|
| 1326 |
|
| 1327 |
\subsection{The Pic Operation} |
| 1328 |
|
| 1329 |
The |pic| operation is used to insert a ``short picture'' (hence the ``short'' |
| 1330 |
name) at the current position of the path. This operation is somewhat similar |
| 1331 |
to the |node| operation and discussed in detail in Section~\ref{section-pics}. |
| 1332 |
|
| 1333 |
|
| 1334 |
\subsection{The Attribute Animation Operation} |
| 1335 |
|
| 1336 |
\begin{pathoperation}{:}{\meta{animation attribute}|=|\marg{options}} |
| 1337 |
This path operation has the same effect as if you had said: |
| 1338 |
% |
| 1339 |
\begin{quote} |
| 1340 |
|[animate = { myself:|\meta{animate attribute}|=|\marg{options}|} ]| |
| 1341 |
\end{quote} |
| 1342 |
% |
| 1343 |
This causes an animation of \meta{animate attribute} to be added to the |
| 1344 |
current path, see Section~\ref{section-tikz-animations} for details. |
| 1345 |
% |
| 1346 |
\begin{codeexample}[width=2cm,preamble={\usetikzlibrary{animations}}] |
| 1347 |
\tikz \draw :xshift = {0s = "0cm", 30s = "-3cm", repeats} (0,0) circle (5mm); |
| 1348 |
\end{codeexample} |
| 1349 |
% |
| 1350 |
\end{pathoperation} |
| 1351 |
|
| 1352 |
|
| 1353 |
\subsection{The PGF-Extra Operation} |
| 1354 |
|
| 1355 |
In some cases you may need to ``do some calculations or some other stuff'' |
| 1356 |
while a path is constructed. For this, you would like to suspend the |
| 1357 |
construction of the path and suspend \tikzname's parsing of the path, you would |
| 1358 |
then like to have some \TeX\ code executed, and would then like to resume the |
| 1359 |
parsing of the path. This effect can be achieved using the following path |
| 1360 |
operation |\pgfextra|. Note that this operation should only be used by real |
| 1361 |
experts and should only be used deep inside clever macros, not on normal paths. |
| 1362 |
|
| 1363 |
\begin{command}{\pgfextra\marg{code}} |
| 1364 |
This command may only be used inside a \tikzname\ path. There it is used |
| 1365 |
like a normal path operation. The construction of the path is temporarily |
| 1366 |
suspended and the \meta{code} is executed. Then, the path construction is |
| 1367 |
resumed. |
| 1368 |
% |
| 1369 |
\begin{codeexample}[] |
| 1370 |
\newdimen\mydim |
| 1371 |
\begin{tikzpicture} |
| 1372 |
\mydim=1cm |
| 1373 |
\draw (0pt,\mydim) \pgfextra{\mydim=2cm} -- (0pt,\mydim); |
| 1374 |
\end{tikzpicture} |
| 1375 |
\end{codeexample} |
| 1376 |
% |
| 1377 |
\end{command} |
| 1378 |
|
| 1379 |
\begin{command}{\pgfextra \meta{code} \texttt{\char`\\endpgfextra}} |
| 1380 |
This is an alternative syntax for the |\pgfextra| command. If the code |
| 1381 |
following |\pgfextra| does not start with a brace, the \meta{code} is |
| 1382 |
executed until |\endpgfextra| is encountered. What actually happens is that |
| 1383 |
when |\pgfextra| is not followed by a brace, this completely shuts down the |
| 1384 |
\tikzname\ parser and |\endpgfextra| is a normal macro that restarts the |
| 1385 |
parser. |
| 1386 |
% |
| 1387 |
\begin{codeexample}[] |
| 1388 |
\newdimen\mydim |
| 1389 |
\begin{tikzpicture} |
| 1390 |
\mydim=1cm |
| 1391 |
\draw (0pt,\mydim) |
| 1392 |
\pgfextra \mydim=2cm \endpgfextra -- (0pt,\mydim); |
| 1393 |
\end{tikzpicture} |
| 1394 |
\end{codeexample} |
| 1395 |
% |
| 1396 |
\end{command} |
| 1397 |
|
| 1398 |
|
| 1399 |
\subsection{Interacting with the Soft Path subsystem} |
| 1400 |
|
| 1401 |
During construction \tikzname\ stores the path internally as a \emph{soft |
| 1402 |
path}. Sometimes it is desirable to save a path during the stage of |
| 1403 |
construction, restore it elsewhere and continue using it. There are two keys to |
| 1404 |
facilitate this operation, which are explained below. To learn more about the |
| 1405 |
soft path subsystem, refer to section~\ref{section-soft-paths}. |
| 1406 |
|
| 1407 |
\begin{key}{/tikz/save path=\meta{macro}} |
| 1408 |
Save the current soft path into \meta{macro}. |
| 1409 |
\end{key} |
| 1410 |
|
| 1411 |
\begin{key}{/tikz/use path=\meta{macro}} |
| 1412 |
Set the current path to the soft path stored in \meta{macro}. |
| 1413 |
\end{key} |
| 1414 |
|
| 1415 |
\begin{codeexample}[preamble={\usetikzlibrary{intersections}}] |
| 1416 |
\begin{tikzpicture} |
| 1417 |
\path[save path=\pathA,name path=A] (0,1) to [bend left] (1,0); |
| 1418 |
\path[save path=\pathB,name path=B] |
| 1419 |
(0,0) .. controls (.33,.1) and (.66,.9) .. (1,1); |
| 1420 |
|
| 1421 |
\fill[name intersections={of=A and B}] (intersection-1) circle (1pt); |
| 1422 |
|
| 1423 |
\draw[blue][use path=\pathA]; |
| 1424 |
\draw[red] [use path=\pathB]; |
| 1425 |
\end{tikzpicture} |
| 1426 |
\end{codeexample} |