Debian Codegraph @

texmf-dist/doc/generic/pgf/pgfmanual-en-tikz-shapes.tex

raw
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{Nodes and Edges}
12 \label{section-nodes}
13
14 \subsection{Overview}
15
16 In the present section, the usage of \emph{nodes} in \tikzname\ is explained. A
17 node is typically a rectangle or circle or another simple shape with some text
18 on it.
19
20 Nodes are added to paths using the special path operation |node|. Nodes
21 \emph{are not part of the path itself}. Rather, they are added to the picture
22 just before or after the path has been drawn.
23
24 In Section~\ref{section-nodes-basic} the basic syntax of the node operation is
25 explained, followed in Section~\ref{section-nodes-multi} by the syntax for
26 multi-part nodes, which are nodes that contain several different text parts.
27 After this, the different options for the text in nodes are explained. In
28 Section~\ref{section-nodes-anchors} the concept of \emph{anchors} is introduced
29 along with their usage. In Section~\ref{section-nodes-transformations} the
30 different ways transformations affect nodes are studied.
31 Sections~\ref{section-nodes-placing-1} and~\ref{section-nodes-placing-2} are
32 about placing nodes on or next to straight lines and curves.
33 Section~\ref{section-nodes-connecting} explains how a node can be used as a
34 ``pseudo-coordinate''. Section~\ref{section-nodes-edges} introduces the |edge|
35 operation, which works similar to the |to| operation and also similar to the
36 |node| operation.
37
38
39 \subsection{Nodes and Their Shapes}
40 \label{section-nodes-basic}
41
42 In the simplest case, a node is just some text that is placed at some
43 coordinate. However, a node can also have a border drawn around it or have a
44 more complex background and foreground. Indeed, some nodes do not have a text
45 at all, but consist solely of the background. You can name nodes so that you
46 can reference their coordinates later in the same picture or, if certain
47 precautions are taken as explained in Section~\ref{section-cross-picture-tikz},
48 also in different pictures.
49
50 There are no special \TeX\ commands for adding a node to a picture; rather,
51 there is path operation called |node| for this. Nodes are created whenever
52 \tikzname\ encounters |node| or |coordinate| at a point on a path where it
53 would expect a normal path operation (like |-- (1,1)| or |rectangle (1,1)|). It
54 is also possible to give node specifications \emph{inside} certain path
55 operations as explained later.
56
57 The node operation is typically followed by some options, which apply only to
58 the node. Then, you can optionally \emph{name} the node by providing a name in
59 parentheses. Lastly, for the |node| operation you must provide some label text
60 for the node in curly braces, while for the |coordinate| operation you may not.
61 The node is placed at the current position of the path either \emph{after the
62 path has been drawn} or (more seldom and only if you add the |behind path|
63 option) \emph{just before the path is drawn.} Thus, all nodes are drawn ``on
64 top'' or ``behind'' the path and are retained until the path is complete. If
65 there are several nodes on a path, perhaps some behind and some on top of the
66 path, first come the nodes behind the path in the order they were encountered,
67 then comes that path, and then come the remaining node, again in the order they
68 are encountered.
69 %
70 \begin{codeexample}[]
71 \tikz \fill [fill=yellow!80!black]
72 (0,0) node {first node}
73 -- (1,1) node[behind path] {second node}
74 -- (2,0) node {third node};
75 \end{codeexample}
76
77
78 \subsubsection{Syntax of the Node Command}
79
80 The syntax for specifying nodes is the following:
81 %
82 \begin{pathoperation}{node}{
83 \opt{\meta{foreach statements}}
84 \opt{|[|\meta{options}|]|}
85 \opt{|(|\meta{name}|)|}
86 \opt{|at(|\meta{coordinate}|)|}
87 \opt{|:|\meta{animation attribute}|=|\marg{options}}
88 \opt{\marg{node contents}}%
89 }
90 Since this path operation is one of the most involved around, let us go
91 over it step by step.
92
93 \medskip
94 \textbf{Order of the parts of the specification.}
95 Everything between ``|node|'' and the opening brace of a node is optional.
96 If there are \meta{foreach statements}, they must come first, directly
97 following ``|node|''. Other than that, the ordering of all the other
98 elements of a node specification (the \meta{options}, the \meta{name},
99 \meta{coordinate}, and \meta{animation attribute}) is arbitrary, indeed,
100 there can be multiple occurrences of any of these elements (although for
101 the name and the coordinate this makes no sense).
102
103 \medskip
104 \textbf{The text of a node.}
105 At the end of a node, you must (normally) provide some \meta{node contents}
106 in curly braces; indeed, the ``end'' of the node specification is detected
107 by the opening curly brace. For normal nodes it is possible to use
108 ``fragile'' stuff inside the \meta{node contents} like the |\verb| command
109 (for the technically savvy: code inside the \meta{node contents} is allowed
110 to change catcodes; however, this rule does not apply to ``nodes on a
111 path'' to be discussed later).
112
113 Instead of giving \meta{node contents} at the end of the node in curly
114 braces, you can also use the following key:
115 %
116 \begin{key}{/tikz/node contents=\meta{node contents}}
117 \label{option-node-contents}%
118 This key sets the contents of the node to the given text as if you had
119 given it at the end in curly braces. When the option is used inside the
120 options of a node, the parsing of the node stops immediately after the
121 end of the option block. In particular, the option block cannot be
122 followed by further option blocks or curly braces (or, rather, these do
123 not count as part of the node specification.) Also note that the
124 \meta{node contents} may not contain fragile stuff since the catcodes
125 get fixed upon reading the options. Here is an example:
126 %
127 \begin{codeexample}[]
128 \tikz {
129 \path (0,0) node [red] {A}
130 (1,0) node [blue] {B}
131 (2,0) node [green, node contents=C]
132 (3,0) node [node contents=D] ;
133 }
134 \end{codeexample}
135 %
136 \end{key}
137
138 \medskip
139 \textbf{Specifying the location of the node.}
140 Nodes are placed at the last position mentioned on the path. The effect of
141 adding ``|at|'' to a node specification is that the coordinate given after
142 |at| is used instead. The |at| syntax is not available when a node is given
143 inside a path operation (it would not make any sense there).
144
145 \begin{key}{/tikz/at=\meta{coordinate}}
146 This is another way of specifying the |at| coordinate. Note that,
147 typically, you will have to enclose the \meta{coordinate} in curly
148 braces so that a comma inside the \meta{coordinate} does not confuse
149 \TeX.
150 \end{key}
151
152 Another aspect of the ``location'' of a node is whether it appears \emph{in
153 front of} or \emph{behind} the current path. You can change which of these
154 two possibilities happens on a node-by-node basis using the following keys:
155 %
156 \begin{key}{/tikz/behind path}
157 When this key is set, either as a local option for the node or some
158 surrounding scope, the node will be drawn behind the current path. For
159 this, \tikzname\ collects all nodes defined on the current path with
160 this option set and then inserts all of them, in the order they appear,
161 just before it draws the path. Thus, several nodes with this option set
162 may obscure one another, but never the path itself. ``Just before it
163 draws the path'' actually means that the nodes are inserted into the
164 page output just before any pre-actions are applied to the path (see
165 below for what pre-actions are).
166 %
167 \begin{codeexample}[]
168 \tikz \fill [fill=blue!50, draw=blue, very thick]
169 (0,0) node [behind path, fill=red!50] {first node}
170 -- (1.5,0) node [behind path, fill=green!50] {second node}
171 -- (1.5,1) node [behind path, fill=brown!50] {third node}
172 -- (0,1) node [ fill=blue!30] {fourth node};
173 \end{codeexample}
174
175 Note that |behind path| only applies to the current path; not to the
176 current scope or picture. To put a node ``behind everything'' you need
177 to use layers and options like |on background layer|, see the
178 |backgrounds| library in Section~\ref{section-tikz-backgrounds}.
179 \end{key}
180
181 \begin{key}{/tikz/in front of path}
182 This is the opposite of |behind path|: It causes nodes to be drawn on
183 top of the path. Since this is the default behavior, you usually do
184 not need this option; it is only needed when an enclosing scope has
185 used |behind path| and you now wish to ``switch back'' to the normal
186 behavior.
187 \end{key}
188
189 \medskip
190 \textbf{The name of a node.}
191 The |(|\meta{name}|)| is a name for later reference and it is optional. You
192 may also add the option |name=|\meta{name} to the \meta{option} list; it
193 has the same effect.
194
195 \begin{key}{/tikz/name=\meta{node name}}
196 Assigns a name to the node for later reference. Since this is a
197 ``high-level'' name (drivers never know of it), you can use spaces,
198 number, letters, or whatever you like when naming a node. Thus, you can
199 name a node just |1| or perhaps |start of chart| or even |y_1|. Your
200 node name should \emph{not} contain any punctuation like a dot, a
201 comma, or a colon since these are used to detect what kind of
202 coordinate you mean when you reference a node.
203 \end{key}
204
205 \begin{key}{/tikz/alias=\meta{another node name}}
206 This option allows you to provide another name for the node. Giving
207 this option multiple times will allow you to access the node via
208 several aliases. Using the |node also| syntax, you can also assign an
209 alias name to a node at a later point, see
210 Section~\ref{section-node-also}.
211 \end{key}
212
213 \medskip
214 \textbf{The options of a node.}
215 The \meta{options} is an optional list of options that \emph{apply only to
216 the node} and have no effect outside. The other way round, most ``outside''
217 options also apply to the node, but not all. For example, the ``outside''
218 rotation does not apply to nodes (unless some special options are used,
219 sigh). Also, the outside path action, like |draw| or |fill|, never applies
220 to the node and must be given in the node (unless some special other
221 options are used, deep sigh).
222
223 \medskip
224 \textbf{The shape of a node.}
225 As mentioned before, we can add a border and even a background to a node:
226 %
227 \begin{codeexample}[]
228 \tikz \fill[fill=yellow!80!black]
229 (0,0) node {first node}
230 -- (1,1) node[draw, behind path] {second node}
231 -- (0,2) node[fill=red!20,draw,double,rounded corners] {third node};
232 \end{codeexample}
233
234 The ``border'' is actually just a special case of a much more general
235 mechanism. Each node has a certain \emph{shape} which, by default, is a
236 rectangle. However, we can also ask \tikzname\ to use a circle shape
237 instead or an ellipse shape (you have to include one of the
238 |shapes.geometric| library for the latter shape):
239 %
240 \begin{codeexample}[preamble={\usetikzlibrary{shapes.geometric}}]
241 \tikz \fill[fill=yellow!80!black]
242 (0,0) node {first node}
243 -- (1,1) node[ellipse,draw, behind path] {second node}
244 -- (0,2) node[circle,fill=red!20] {third node};
245 \end{codeexample}
246
247 There are many more shapes available such as, say, a shape for a resistor
248 or a large arrow, see the |shapes| library in
249 Section~\ref{section-libs-shapes} for details.
250
251 To select the shape of a node, the following option is used:
252 %
253 \begin{key}{/tikz/shape=\meta{shape name} (initially rectangle)}
254 Select the shape either of the current node or, when this option is not
255 given inside a node but somewhere outside, the shape of all nodes in
256 the current scope.%
257 \indexoption{\meta{shape name}}
258
259 Since this option is used often, you can leave out the |shape=|. When
260 \tikzname\ encounters an option like |circle| that it does not know, it
261 will, after everything else has failed, check whether this option is
262 the name of some shape. If so, that shape is selected as if you had
263 said |shape=|\meta{shape name}.
264
265 By default, the following shapes are available: |rectangle|, |circle|,
266 |coordinate|. Details of these shapes, like their anchors and size
267 options, are discussed in Section~\ref{section-the-shapes}.
268 \end{key}
269
270 \medskip
271 \textbf{Animating a node.}
272 When you say |:|\meta{animation attribute}|={|\meta{options}|}|, an
273 \emph{animation} of the specified attribute is added to the node.
274 Animations are discussed in detail in
275 Section~\ref{section-tikz-animations}. Here is a typical example of how
276 this syntax can be used:
277 %
278 \begin{codeexample}[preamble={\usetikzlibrary{animations}},animation list={0.5,1,1.5,2}]
279 \tikz
280 \node :fill opacity = { 0s="1", 2s="0", begin on=click }
281 :rotate = { 0s="0", 2s="90", begin on=click }
282 [fill = blue!20, draw = blue, ultra thick, circle]
283 {Click me!};
284 \end{codeexample}
285
286 \medskip
287 \textbf{The foreach statement for nodes.}
288 At the beginning of a node specification (and only there) you can provide
289 multiple \meta{foreach statements}, each of which has the form |foreach|
290 \meta{var} |in| \meta{list} (note that there is no backslash before
291 |foreach|). When they are given, instead of a single node, multiple nodes
292 will be created: The \meta{var} will iterate over all values of \meta{list}
293 and for each of them, a new node is created. These nodes are all created
294 using all the text following the \meta{foreach statements}, but in each
295 copy the \meta{var} will have the current value of the current element in
296 the \meta{list}.
297
298 As an example, the following two codes have the same effect:
299 %
300 \begin{codeexample}[]
301 \tikz \draw (0,0) node foreach \x in {1,2,3} at (\x,0) {\x};
302 \end{codeexample}
303 \begin{codeexample}[]
304 \tikz \draw (0,0) node at (1,0) {1} node at (2,0) {2} node at (3,0) {3};
305 \end{codeexample}
306 %
307 When you provide several |foreach| statements, they work like ``nested
308 loops'':
309 %
310 \begin{codeexample}[]
311 \tikz \node foreach \x in {1,...,4} foreach \y in {1,2,3}
312 [draw] at (\x,\y) {\x,\y};
313 \end{codeexample}
314 %
315 As the example shows, a \meta{list} can contain ellipses (three dots) to
316 indicate that a larger number of numbers is meant. Indeed, you can use the
317 full power of the |\foreach| command here, including multiple parameters
318 and options, see Section~\ref{section-foreach}.
319
320 \medskip
321 \textbf{Styles for nodes.}
322 The following styles influence how nodes are rendered:
323 %
324 \begin{stylekey}{/tikz/every node (initially \normalfont empty)}
325 This style is installed at the beginning of every node.
326 %
327 \begin{codeexample}[]
328 \begin{tikzpicture}[every node/.style={draw}]
329 \draw (0,0) node {A} -- (1,1) node {B};
330 \end{tikzpicture}
331 \end{codeexample}
332 \end{stylekey}
333 %
334 \begin{stylekey}{/tikz/every \meta{shape} node (initially \normalfont empty)}
335 These styles are installed at the beginning of a node of a given
336 \meta{shape}. For example, |every rectangle node| is used for rectangle
337 nodes, and so on.
338 %
339 \begin{codeexample}[]
340 \begin{tikzpicture}
341 [every rectangle node/.style={draw},
342 every circle node/.style={draw,double}]
343 \draw (0,0) node[rectangle] {A} -- (1,1) node[circle] {B};
344 \end{tikzpicture}
345 \end{codeexample}
346 \end{stylekey}
347
348 \begin{key}{/tikz/execute at begin node=\meta{code}}
349 This option causes \meta{code} to be executed at the beginning of a
350 node. Using this option multiple times will cause the code to
351 accumulate.
352 \end{key}
353
354 \begin{key}{/tikz/execute at end node=\meta{code}}
355 This option installs \meta{code} that will be executed at the end of
356 the node. Using this option multiple times will cause the code to
357 accumulate.
358 %
359 \begin{codeexample}[]
360 \begin{tikzpicture}
361 [execute at begin node={A},
362 execute at end node={D}]
363 \node[execute at begin node={B}] {C};
364 \end{tikzpicture}
365 \end{codeexample}
366 %
367 \end{key}
368
369 \medskip
370 \textbf{Name scopes.}
371 It turns out that the name of a node can further be influenced using two
372 keys:
373 %
374 \begin{key}{/tikz/name prefix=\meta{text} (initially \normalfont empty)}
375 The value of this key is prefixed to every node inside the current
376 scope. This includes both the naming of the node (via the |name| key or
377 via the implicit |(|\meta{name}|)| syntax) as well as any referencing
378 of the node. Outside the scope, the nodes can (and need to) be
379 referenced using ``full name'' consisting of the prefix and the node
380 name.
381
382 The net effect of this is that you can set the name prefix at the
383 beginning of a scope to some value and then use short and simple names
384 for the nodes inside the scope. Later, outside the scope, you can
385 reference the nodes via their full name:
386 %
387 \begin{codeexample}[]
388 \tikz {
389 \begin{scope}[name prefix = top-]
390 \node (A) at (0,1) {A};
391 \node (B) at (1,1) {B};
392 \draw (A) -- (B);
393 \end{scope}
394 \begin{scope}[name prefix = bottom-]
395 \node (A) at (0,0) {A};
396 \node (B) at (1,0) {B};
397 \draw (A) -- (B);
398 \end{scope}
399
400 \draw [red] (top-A) -- (bottom-B);
401 }
402 \end{codeexample}
403 %
404 As can be seen, name prefixing makes it easy to write reusable code.
405 \end{key}
406 %
407 \begin{key}{/tikz/name suffix=\meta{text} (initially \normalfont empty)}
408 Works as |name prefix|, only the \meta{text} is appended to every node
409 name in the current scope.
410 \end{key}
411 \end{pathoperation}
412
413 There is a special syntax for specifying ``light-weight'' nodes:
414
415 \begin{pathoperation}{coordinate}{\opt{|[|\meta{options}|]|}|(|\meta{name}|)|\opt{|at(|\meta{coordinate}|)|}}
416 This has the same effect as
417
418 |\node[shape=coordinate]|\verb|[|\meta{options}|](|\meta{name}|)at(|\meta{coordinate}|){}|,
419
420 where the |at| part may be omitted.
421 \end{pathoperation}
422
423 Since nodes are often the only path operation on paths, there are two special
424 commands for creating paths containing only a node:
425
426 \begin{command}{\node}
427 Inside |{tikzpicture}| this is an abbreviation for |\path node|.
428 \end{command}
429
430 \begin{command}{\coordinate}
431 Inside |{tikzpicture}| this is an abbreviation for |\path coordinate|.
432 \end{command}
433
434
435 \subsubsection{Predefined Shapes}
436 \label{section-nodes-predefined}
437 \label{section-the-shapes}
438
439 \pgfname\ \todosp{why two labels for the same point? The first doesn't seem to
440 be used anywhere} and \tikzname\ define three shapes, by default:
441 %
442 \begin{itemize}
443 \item |rectangle|,
444 \item |circle|, and
445 \item |coordinate|.
446 \end{itemize}
447 %
448 By loading library packages, you can define more shapes like ellipses or
449 diamonds; see Section~\ref{section-libs-shapes} for the complete list of
450 shapes.
451
452 \label{section-tikz-coordinate-shape}%
453 The |coordinate| shape is handled in a special way by \tikzname. When a node
454 |x| whose shape is |coordinate| is used as a coordinate |(x)|, this has the
455 same effect as if you had said |(x.center)|. None of the special ``line
456 shortening rules'' apply in this case. This can be useful since, normally, the
457 line shortening causes paths to be segmented and they cannot be used for
458 filling. Here is an example that demonstrates the difference:
459 %
460 \begin{codeexample}[]
461 \begin{tikzpicture}[every node/.style={draw}]
462 \path[yshift=1.5cm,shape=rectangle]
463 (0,0) node(a1){} (1,0) node(a2){}
464 (1,1) node(a3){} (0,1) node(a4){};
465 \filldraw[fill=yellow!80!black] (a1) -- (a2) -- (a3) -- (a4);
466
467 \path[shape=coordinate]
468 (0,0) coordinate(b1) (1,0) coordinate(b2)
469 (1,1) coordinate(b3) (0,1) coordinate(b4);
470 \filldraw[fill=yellow!80!black] (b1) -- (b2) -- (b3) -- (b4);
471 \end{tikzpicture}
472 \end{codeexample}
473
474
475 \subsubsection{Common Options: Separations, Margins, Padding and
476 Border Rotation}
477 \label{section-shape-seps}
478 \label{section-shape-common-options}
479
480 The \todosp{why two labels for the same point?} exact behavior of shapes
481 differs, shapes defined for more special purposes (like a, say, transistor
482 shape) will have even more custom behaviors. However, there are some options
483 that apply to most shapes:
484
485 \begin{key}{/pgf/inner sep=\meta{dimension} (initially .3333em)}
486 \keyalias{tikz}
487 An additional (invisible) separation space of \meta{dimension} will be
488 added inside the shape, between the text and the shape's background path.
489 The effect is as if you had added appropriate horizontal and vertical skips
490 at the beginning and end of the text to make it a bit ``larger''.
491
492 For those familiar with \textsc{css}, this is the same as \emph{padding}.
493 %
494 \begin{codeexample}[]
495 \begin{tikzpicture}
496 \draw (0,0) node[inner sep=0pt,draw] {tight}
497 (0cm,2em) node[inner sep=5pt,draw] {loose}
498 (0cm,4em) node[fill=yellow!80!black] {default};
499 \end{tikzpicture}
500 \end{codeexample}
501 %
502 \end{key}
503
504 \begin{key}{/pgf/inner xsep=\meta{dimension} (initially .3333em)}
505 \keyalias{tikz}
506 Specifies the inner separation in the $x$-direction, only.
507 \end{key}
508
509 \begin{key}{/pgf/inner ysep=\meta{dimension} (initially .3333em)}
510 \keyalias{tikz}
511 Specifies the inner separation in the $y$-direction, only.
512 \end{key}
513
514 \begin{key}{/pgf/outer sep=\meta{dimension or ``auto''}}
515 \keyalias{tikz}
516 This option adds an additional (invisible) separation space of
517 \meta{dimension} outside the background path. The main effect of this
518 option is that all anchors will move a little ``to the outside''.
519
520 For those familiar with \textsc{css}, this is same as \emph{margin}.
521
522 The default for this option is half the line width. When the default is
523 used and when the background path is draw, the anchors will lie exactly on
524 the ``outside border'' of the path (not on the path itself).
525 %
526 \begin{codeexample}[]
527 \begin{tikzpicture}
528 \draw[line width=5pt]
529 (0,0) node[fill=yellow!80!black] (f) {filled}
530 (2,0) node[draw] (d) {drawn}
531 (1,-2) node[draw,scale=2] (s) {scaled};
532
533 \draw[->] (1,-1) -- (f);
534 \draw[->] (1,-1) -- (d);
535 \draw[->] (1,-1) -- (s);
536 \end{tikzpicture}
537 \end{codeexample}
538
539 As the above example demonstrates, the standard settings for the outer sep
540 are not always ``correct''. First, when a shape is filled, but not drawn,
541 the outer sep should actually be |0|. Second, when a node is scaled, for
542 instance by a factor of 5, the outer separation also gets scaled by a
543 factor of 5, while the line width stays at its original width; again
544 causing problems.
545
546 In such cases, you can say |outer sep=auto| to make \tikzname\ \emph{try}
547 to compensate for the effects described above. This is done by, firstly,
548 setting the outer sep to |0| when no drawing is done and, secondly, setting
549 the outer separations to half the line width (as before) times two
550 adjustment factors, one for the horizontal separations and one for the
551 vertical separations (see Section~\ref{section-adjustment-transformations}
552 for details on these factors). Note, however, that these factors can
553 compensate only for transformations that are either scalings plus rotations
554 or scalings with different magnitudes in the horizontal and the vertical
555 direction. If you apply slanting, the factors will only approximate the
556 correct values.
557
558 In general, it is a good idea to say |outer sep=auto| at some early stage.
559 It is not the default mainly for compatibility with earlier versions.
560 %
561 \begin{codeexample}[]
562 \begin{tikzpicture}[outer sep=auto]
563 \draw[line width=5pt]
564 (0,0) node[fill=yellow!80!black] (f) {filled}
565 (2,0) node[draw] (d) {drawn}
566 (1,-2) node[draw,scale=2] (s) {scaled};
567
568 \draw[->] (1,-1) -- (f);
569 \draw[->] (1,-1) -- (d);
570 \draw[->] (1,-1) -- (s);
571 \end{tikzpicture}
572 \end{codeexample}
573 %
574 \end{key}
575
576 \begin{key}{/pgf/outer xsep=\meta{dimension} (initially .5\string\pgflinewidth)}
577 \keyalias{tikz}
578 Specifies the outer separation in the $x$-direction, only. This value will
579 be overwritten when |outer sep| is set, either to the value given there or
580 a computed value in case of |auto|.
581 \end{key}
582
583 \begin{key}{/pgf/outer ysep=\meta{dimension} (initially .5\string\pgflinewidth)}
584 \keyalias{tikz}
585 Specifies the outer separation in the $y$-direction, only.
586 \end{key}
587
588 \begin{key}{/pgf/minimum height=\meta{dimension} (initially 1pt)}
589 \keyalias{tikz}
590 This option ensures that the height of the shape (including the inner, but
591 ignoring the outer separation) will be at least \meta{dimension}. Thus, if
592 the text plus the inner separation is not at least as large as
593 \meta{dimension}, the shape will be enlarged appropriately. However, if the
594 text is already larger than \meta{dimension}, the shape will not be shrunk.
595 %
596 \begin{codeexample}[]
597 \begin{tikzpicture}
598 \draw (0,0) node[minimum height=1cm,draw] {1cm}
599 (2,0) node[minimum height=0cm,draw] {0cm};
600 \end{tikzpicture}
601 \end{codeexample}
602 %
603 \end{key}
604
605 \begin{key}{/pgf/minimum width=\meta{dimension} (initially 1pt)}
606 \keyalias{tikz}
607 Same as |minimum height|, only for the width.
608 %
609 \begin{codeexample}[]
610 \begin{tikzpicture}
611 \draw (0,0) node[minimum height=2cm,minimum width=3cm,draw] {$3 \times 2$};
612 \end{tikzpicture}
613 \end{codeexample}
614 %
615 \end{key}
616
617 \begin{key}{/pgf/minimum size=\meta{dimension}}
618 \keyalias{tikz}
619 Sets both the minimum height and width at the same time.
620 %
621 \begin{codeexample}[]
622 \begin{tikzpicture}
623 \draw (0,0) node[minimum size=2cm,draw] {square};
624 \draw (0,-2) node[minimum size=2cm,draw,circle] {circle};
625 \end{tikzpicture}
626 \end{codeexample}
627 %
628 \end{key}
629
630 \begin{key}{/pgf/shape aspect=\meta{aspect ratio}}
631 \keyalias{tikz}
632 Sets a desired aspect ratio for the shape. For the |diamond| shape, this
633 option sets the ratio between width and height of the shape.
634 %
635 \begin{codeexample}[preamble={\usetikzlibrary{shapes.geometric}}]
636 \begin{tikzpicture}
637 \draw (0,0) node[shape aspect=1,diamond,draw] {aspect 1};
638 \draw (0,-2) node[shape aspect=2,diamond,draw] {aspect 2};
639 \end{tikzpicture}
640 \end{codeexample}
641 %
642 \end{key}
643
644 \label{section-rotating-shape-borders}
645
646 Some shapes (but not all), support a special kind of rotation. This rotation
647 affects only the border of a shape and is independent of the node contents, but
648 \emph{in addition} to any other transformations.
649 %
650 \begin{codeexample}[preamble={\usetikzlibrary{shapes.geometric}}]
651 \tikzset{every node/.style={dart, shape border uses incircle,
652 inner sep=1pt, draw}}
653 \tikz \node foreach \a/\b/\c in {A/0/0, B/45/0, C/0/45, D/45/45}
654 [shape border rotate=\b, rotate=\c] at (\b/36,-\c/36) {\a};
655 \end{codeexample}
656
657 There are two types of rotation: restricted and unrestricted. Which type of
658 rotation is applied is determined by on how the shape border is constructed. If
659 the shape border is constructed using an incircle, that is, a circle that
660 tightly fits the node contents (including the |inner sep|), then the rotation
661 can be unrestricted. If, however, the border is constructed using the natural
662 dimensions of the node contents, the rotation is restricted to integer
663 multiples of 90 degrees.
664
665 Why should there be two kinds of rotation and border construction? Borders
666 constructed using the natural dimensions of the node contents provide a much
667 tighter fit to the node contents, but to maintain this tight fit, the border
668 rotation must be restricted to integer multiples of 90 degrees. By using an
669 incircle, unrestricted rotation is possible, but the border will not make a
670 very tight fit to the node contents.
671 %
672 \begin{codeexample}[preamble={\usetikzlibrary{shapes.geometric}}]
673 \tikzset{every node/.style={isosceles triangle, draw}}
674 \begin{tikzpicture}
675 \node {abc};
676 \node [shape border uses incircle] at (2,0) {abc};
677 \end{tikzpicture}
678 \end{codeexample}
679
680 There are \pgfname{} keys that determine how a shape border is constructed, and
681 to specify its rotation. It should be noted that not all shapes support these
682 keys, so reference should be made to the documentation for individual shapes.
683
684 \begin{key}{/pgf/shape border uses incircle=\opt{\meta{boolean}} (default true)}
685 \keyalias{tikz}
686 Determines if the border of a shape is constructed using the incircle. If
687 no value is given \meta{boolean} will take the default value |true|.
688 \end{key}
689
690 \begin{key}{/pgf/shape border rotate=\meta{angle} (initially 0)}
691 \keyalias{tikz}
692 Rotates the border of a shape independently of the node contents, but in
693 addition to any other transformations. If the shape border is not
694 constructed using the incircle, the rotation will be rounded to the nearest
695 integer multiple of 90 degrees when the shape is drawn.
696 \end{key}
697
698 Note that if the border of the shape is rotated, the compass point anchors, and
699 `text box' anchors (including |mid east|, |base west|, and so on), \emph{do not
700 rotate}, but the other anchors do:
701 %
702 \begin{codeexample}[preamble={\usetikzlibrary{shapes.geometric}}]
703 \tikzset{every node/.style={shape=trapezium, draw, shape border uses incircle}}
704 \begin{tikzpicture}
705 \node at (0,0) (A) {A};
706 \node [shape border rotate=30] at (1.5,0) (B) {B};
707 \foreach \s/\t in
708 {left side/base east, bottom side/north, bottom left corner/base}{
709 \fill[red] (A.\s) circle(1.5pt) (B.\s) circle(1.5pt);
710 \fill[blue] (A.\t) circle(1.5pt) (B.\t) circle(1.5pt);
711 }
712 \end{tikzpicture}
713 \end{codeexample}
714
715 Finally, a somewhat unfortunate side-effect of rotating shape borders is that
716 the supporting shapes do not distinguish between |outer xsep| and |outer ysep|,
717 and typically, the larger of the two values will be used.
718
719
720 \subsection{Multi-Part Nodes}
721 \label{section-nodes-multi}
722
723 Most nodes just have a single simple text label. However, nodes of a more
724 complicated shape might be made up from several \emph{node parts}. For example,
725 in automata theory a so-called Moore state has a state name, drawn in the upper
726 part of the state circle, and an output text, drawn in the lower part of the
727 state circle. These two parts are quite independent. Similarly, a \textsc{uml}
728 class shape would have a name part, a method part, and an attributes part.
729 Different molecule shapes might use parts for the different atoms to be drawn
730 at the different positions, and so on.
731
732 Both \pgfname\ and \tikzname\ support such multipart nodes. On the lower level,
733 \pgfname\ provides a system for specifying that a shape consists of several
734 parts. On the \tikzname\ level, you specify the different node parts by using
735 the following command:
736
737 \begin{command}{\nodepart\opt{|[|\meta{options}|]|}\marg{part name}}
738 This command can only be used inside the \meta{text} argument of a |node|
739 path operation. It works a little bit like a |\part| command in \LaTeX. It
740 will stop the typesetting of whatever node part was typeset until now and
741 then start putting all following text into the node part named \meta{part
742 name} -- until another |\nodepart| is encountered or until the node
743 \meta{text} ends. The \meta{options} will be local to this part.
744 %
745 \begin{codeexample}[preamble={\usetikzlibrary{shapes.multipart}}]
746 \begin{tikzpicture}
747 \node [circle split,draw,double,fill=red!20]
748 {
749 % No \nodepart has been used, yet. So, the following is put in the
750 % ``text'' node part by default.
751 $q_1$
752 \nodepart{lower} % Ok, end ``text'' part, start ``output'' part
753 $00$
754 }; % output part ended.
755 \end{tikzpicture}
756 \end{codeexample}
757
758 You will have to lookup which parts are defined by a shape.
759
760 The following styles influences node parts:
761 %
762 \begin{stylekey}{/tikz/every \meta{part name} node part (initially \normalfont empty)}
763 This style is installed at the beginning of every node part named
764 \meta{part name}.
765 %
766 \begin{codeexample}[preamble={\usetikzlibrary{shapes.multipart}}]
767 \tikz [every lower node part/.style={red}]
768 \node [circle split,draw] {$q_1$ \nodepart{lower} $00$};
769 \end{codeexample}
770 \end{stylekey}
771 \end{command}
772
773
774 \subsection{The Node Text}
775 \label{section-nodes-options}
776
777 \subsubsection{Text Parameters: Color and Opacity}
778
779 The simplest option for the text in nodes is its color. Normally, this color is
780 just the last color installed using |color=|, possibly inherited from another
781 scope. However, it is possible to specifically set the color used for text
782 using the following option:
783
784 \begin{key}{/tikz/text=\meta{color}}
785 Sets the color to be used for text labels. A |color=| option will
786 immediately override this option.
787 %
788 \begin{codeexample}[]
789 \begin{tikzpicture}
790 \draw[red] (0,0) -- +(1,1) node[above] {red};
791 \draw[text=red] (1,0) -- +(1,1) node[above] {red};
792 \draw (2,0) -- +(1,1) node[above,red] {red};
793 \end{tikzpicture}
794 \end{codeexample}
795 %
796 \end{key}
797
798 Just like the color itself, you may also wish to set the opacity of the text
799 only. For this, use the |text opacity| option, which is detailed in
800 Section~\ref{section-tikz-transparency}.
801
802
803 \subsubsection{Text Parameters: Font}
804
805 Next, you may wish to adjust the font used for the text. Naturally, you can
806 just use a font command like |\small| or |\rm| at the beginning of a node.
807 However, the following two options make it easier to set the font used in nodes
808 on a general basis. Let us start with:
809
810 \begin{key}{/tikz/node font=\meta{font commands}}
811 This option sets the font used for all text used in a node.
812 %
813 \begin{codeexample}[]
814 \begin{tikzpicture}
815 \draw[node font=\itshape] (1,0) -- +(1,1) node[above] {italic};
816 \end{tikzpicture}
817 \end{codeexample}
818 %
819 Since the \meta{font commands} are executed at a very early stage in the
820 construction of the node, the font selected using this command will also
821 dictate the values of dimensions defined in terms of |em| or |ex|. For
822 instance, when the |minimum height| of a node is |3em|, the actual height
823 will be (at least) three times the line distance selected by the \meta{font
824 commands}:
825 \begin{codeexample}[]
826 \tikz \node [node font=\tiny, minimum height=3em, draw] {tiny};
827 \tikz \node [node font=\small, minimum height=3em, draw] {small};
828 \end{codeexample}
829 %
830 \end{key}
831
832 The other font command is:
833 %
834 \begin{key}{/tikz/font=\meta{font commands}}
835 Sets the font used for the text inside nodes. However, this font will
836 \emph{not} (yet) be installed when any of the dimensions of the node are
837 being computed, so dimensions like |1em| will be with respect to the font
838 used outside the node (usually the font that was in force when the picture
839 started).
840 %
841 \begin{codeexample}[]
842 \begin{tikzpicture}
843 \node [font=\itshape] {italic};
844 \end{tikzpicture}
845 \end{codeexample}
846
847 \begin{codeexample}[]
848 \tikz \node [font=\tiny, minimum height=3em, draw] {tiny};
849 \tikz \node [font=\small, minimum height=3em, draw] {small};
850 \end{codeexample}
851
852 A useful example of how the |font| option can be used is the following:
853 %
854 \begin{codeexample}[preamble={\usetikzlibrary{shapes.multipart}}]
855 \tikz [every text node part/.style={font=\itshape},
856 every lower node part/.style={font=\footnotesize}]
857 \node [circle split,draw] {state \nodepart{lower} output};
858 \end{codeexample}
859
860 As can be seen, the font can be changed for each node part. This does
861 \emph{not} work with the |node font| command since, as the name suggests,
862 this command can only be used to select the ``overall'' font for the node
863 and this is done very early.
864 \end{key}
865
866
867 \subsubsection{Text Parameters: Alignment and Width for Multi-Line Text}
868
869 Normally, when a node is typeset, all the text you give in the braces is put in
870 one long line (in an |\hbox|, to be precise) and the node will become as wide
871 as necessary.
872
873 From time to time you may wish to create nodes that contain multiple lines of
874 text. There are three different ways of achieving this:
875 %
876 \begin{enumerate}
877 \item Inside the node, you can put some standard environment that produces
878 multi-line, aligned text. For instance, you can use a |{tabular}|
879 inside a node:
880 %
881 \begin{codeexample}[width=5cm]
882 \tikz \node [draw] {
883 \begin{tabular}{cc}
884 upper left & upper right\\
885 lower left & lower right
886 \end{tabular}
887 };
888 \end{codeexample}
889 %
890 This approach offers the most flexibility in the sense that it allows
891 you to use all of the alignment commands offered by your format of
892 choice.
893 \item You use |\\| inside your node to mark the end of lines and then
894 request \tikzname\ to arrange these lines in some manner. This will
895 only be done, however, if the |align| option has been given.
896 %
897 \begin{codeexample}[]
898 \tikz[align=left] \node[draw] {This is a\\demonstration.};
899 \end{codeexample}
900 %
901 \begin{codeexample}[]
902 \tikz[align=center] \node[draw] {This is a\\demonstration.};
903 \end{codeexample}
904 %
905 The |\\| command takes an optional extra space as an argument in square
906 brackets.
907 %
908 \begin{codeexample}[]
909 \tikz \node[fill=yellow!80!black,align=right]
910 {This is a\\[-2pt] demonstration text for\\[1ex] alignments.};
911 \end{codeexample}
912 %
913 \item You can request that \tikzname\ does an automatic line-breaking for
914 you inside the node by specifying a fixed |text width| for the node. In
915 this case, you can still use |\\| to enforce a line-break. Note that
916 when you specify a text width, the node will have this width,
917 independently of whether the text actually ``reaches the end'' of the
918 node.
919 \end{enumerate}
920
921 Let us now first have a look at the |text width| command.
922 %
923 \begin{key}{/tikz/text width=\meta{dimension}}
924 This option will put the text of a node in a box of the given width
925 (something akin to a |{minipage}| of this width, only portable across
926 formats). If the node text is not as wide as \meta{dimension}, it will
927 nevertheless be put in a box of this width. If it is larger, line breaking
928 will be done.
929
930 By default, when this option is given, a ragged right border will be used
931 (|align=left|). This is sensible since, typically, these boxes are narrow
932 and justifying the text looks ugly. You can, however, change the alignment
933 using |align| or directly using commands line |\centering|.
934 %
935 \begin{codeexample}[]
936 \tikz \draw (0,0) node[fill=yellow!80!black,text width=3cm]
937 {This is a demonstration text for showing how line breaking works.};
938 \end{codeexample}
939 %
940 Setting \meta{dimension} to an empty string causes the automatic line
941 breaking to be disabled.
942 \end{key}
943
944 \begin{key}{/tikz/align=\meta{alignment option}}
945 This key is used to set up an alignment for multi-line text inside a node.
946 If |text width| is set to some width (let us call this \emph{alignment with
947 line breaking}), the |align| key will setup the |\leftskip| and the
948 |\rightskip| in such a way that the text is broken and aligned according to
949 \meta{alignment option}. If |text width| is not set (that is, set to the
950 empty string; let us call this \emph{alignment without line breaking}),
951 then a different mechanism is used internally, namely the key
952 |node halign header|, is set to an appropriate value. While this key, which
953 is documented below, is not to be used by beginners, the net effect is
954 simple: When |text width| is not set, you can use |\\| to break lines and
955 align them according to \meta{alignment option} and the resulting node's
956 width will be minimal to encompass the resulting lines.
957
958 In detail, you can set \meta{alignment option} to one of the following values:
959 %
960 \begin{description}
961 \item[|align=|\declare{|left|}] For alignment without line breaking,
962 the different lines are simply aligned such that their left borders
963 are below one another.
964 %
965 \begin{codeexample}[]
966 \tikz \node[fill=yellow!80!black,align=left]
967 {This is a\\ demonstration text for\\ alignments.};
968 \end{codeexample}
969 %
970 For alignment with line breaking, the same will happen; only the
971 lines will now, additionally, be broken automatically:
972 %
973 \begin{codeexample}[]
974 \tikz \node[fill=yellow!80!black,text width=3cm,align=left]
975 {This is a demonstration text for showing how line breaking works.};
976 \end{codeexample}
977 %
978 \item[|align=|\declare{\texttt{flush left}}] For alignment without line
979 breaking this option has exactly the same effect as |left|.
980 However, for alignment with line breaking, there is a difference:
981 While |left| uses the original plain \TeX\ definition of a ragged
982 right border, in which \TeX\ will try to balance the right border
983 as well as possible, |flush left| causes the right border to be
984 ragged in the \LaTeX-style, in which no balancing occurs. This
985 looks ugly, but it may be useful for very narrow boxes and when you
986 wish to avoid hyphenations.
987 %
988 \begin{codeexample}[]
989 \tikz \node[fill=yellow!80!black,text width=3cm,align=flush left]
990 {This is a demonstration text for showing how line breaking works.};
991 \end{codeexample}
992 %
993 \item[|align=|\declare{|right|}] Works like |left|, only for right
994 alignment.
995 %
996 \begin{codeexample}[]
997 \tikz \node[fill=yellow!80!black,align=right]
998 {This is a\\ demonstration text for\\ alignments.};
999 \end{codeexample}
1000 %
1001 \begin{codeexample}[]
1002 \tikz \node[fill=yellow!80!black,text width=3cm,align=right]
1003 {This is a demonstration text for showing how line breaking works.};
1004 \end{codeexample}
1005 %
1006 \item[|align=|\declare{\texttt{flush right}}] Works like |flush left|,
1007 only for right alignment.
1008 %
1009 \begin{codeexample}[]
1010 \tikz \node[fill=yellow!80!black,text width=3cm,align=flush right]
1011 {This is a demonstration text for showing how line breaking works.};
1012 \end{codeexample}
1013 %
1014 \item[|align=|\declare{|center|}] Works like |left| or |right|, only
1015 for centered alignment.
1016 %
1017 \begin{codeexample}[]
1018 \tikz \node[fill=yellow!80!black,align=center]
1019 {This is a\\ demonstration text for\\ alignments.};
1020 \end{codeexample}
1021 \begin{codeexample}[]
1022 \tikz \node[fill=yellow!80!black,text width=3cm,align=center]
1023 {This is a demonstration text for showing how line breaking works.};
1024 \end{codeexample}
1025
1026 There is one annoying problem with the |center| alignment (but not
1027 with |flush center| and the other options): If you specify a large
1028 line width and the node text fits on a single line and is, in fact,
1029 much shorter than the specified |text width|, an underfull
1030 horizontal box will result. Unfortunately, this cannot be avoided,
1031 due to the way \TeX\ works (more precisely, I have thought long and
1032 hard about this and have not been able to figure out a sensible way
1033 to avoid this). For this reason, \tikzname\ switches off horizontal
1034 badness warnings inside boxes with |align=center|. Since this will
1035 also suppress some ``wanted'' warnings, there is also an option for
1036 switching the warnings on once more:
1037 %
1038 \begin{key}{/tikz/badness warnings for centered text=\meta{true or false} (initially false)}
1039 If set to true, normal badness warnings will be issued for
1040 centered boxes. Note that you may get annoying warnings for
1041 perfectly normal boxes, namely whenever the box is very large
1042 and the contents is not long enough to fill the box
1043 sufficiently.
1044 \end{key}
1045 \item[|align=|\declare{\texttt{flush center}}] Works like |flush left|
1046 or |flush right|, only for center alignment. Because of all the
1047 trouble that results from the |center| option in conjunction with
1048 narrow lines, I suggest picking this option rather than |center|
1049 \emph{unless} you have longer text, in which case |center| will
1050 give the typographically better results.
1051 %
1052 \begin{codeexample}[]
1053 \tikz \node[fill=yellow!80!black,text width=3cm,align=flush center]
1054 {This is a demonstration text for showing how line breaking works.};
1055 \end{codeexample}
1056 %
1057 \item[|align=|\declare{|justify|}] For alignment without line breaking,
1058 this has the same effect as |left|. For alignment with line
1059 breaking, this causes the text to be ``justified''. Use this only
1060 with rather broad nodes.
1061 {%
1062 \hbadness=10000
1063 \begin{codeexample}[]
1064 \tikz \node[fill=yellow!80!black,text width=3cm,align=justify]
1065 {This is a demonstration text for showing how line breaking works.};
1066 \end{codeexample}
1067 }
1068 In the above example, \TeX\ complains (rightfully) about three very
1069 badly typeset lines. (For this manual I asked \TeX\ to stop
1070 complaining by using |\hbadness=10000|, but this is a foul deed,
1071 indeed.)
1072 \item[|align=|\declare{|none|}] Disables all alignments and |\\| will
1073 not be redefined.
1074 \end{description}
1075 \end{key}
1076
1077 \begin{key}{/tikz/node halign header=\meta{macro storing a header} (initially \normalfont empty)}
1078 This is the key that is used by |align| internally for alignment without
1079 line breaking. Read the following only if you are familiar with the
1080 |\halign| command.
1081
1082 This key only has an effect if |text width| is empty, otherwise it is
1083 ignored. Furthermore, if \meta{macro storing a header} is empty, then this
1084 key also has no effect. So, suppose |text width| is empty, but
1085 \meta{header} is not. In this case the following happens:
1086
1087 When the node text is parsed, the command |\\| is redefined internally.
1088 This redefinition is done in such a way that the text from the start of the
1089 node to the first occurrence of |\\| is put in an |\hbox|. Then the text
1090 following |\\| up to the next |\\| is put in another |\hbox|. This goes on
1091 until the text between the last |\\| and the closing |}| is also put in an
1092 |\hbox|.
1093
1094 The \meta{macro storing a header} should be a macro that contains some text
1095 suitable for use as a header for the |\halign| command. For instance, you
1096 might define
1097 %
1098 \begin{codeexample}[code only]
1099 \def\myheader{\hfil\hfil##\hfil\cr}
1100 \tikz [node halign header=\myheader] ...
1101 \end{codeexample}
1102 %
1103 You cannot just say |node halign header=\hfil\hfil#\hfil\cr| because this
1104 confuses \TeX\ inside matrices, so this detour via a macro is needed.
1105
1106 Next, conceptually, all these boxes are recursively put inside an |\halign|
1107 command. Assuming that \meta{first} is the first of the above boxes, the
1108 command |\halign{|\meta{header} |\box|\meta{first} |\cr}| is used to create
1109 a new box, which we will call the \meta{previous box}. Then, the following
1110 box is created, where \meta{second} is the second input box:
1111 |\halign{|\meta{header} |\box|\meta{previous box} |\cr|
1112 |\box|\meta{second}|\cr}|. Let us call the resulting box the \meta{previous
1113 box} once more. Then the next box that is created is
1114 |\halign{|\meta{header} |\box|\meta{previous box} |\cr|
1115 |\box|\meta{third}|\cr}|.
1116
1117 All of this means that if \meta{header} is an |\halign| header like
1118 |\hfil#\hfil\cr|, then all boxes will be centered relative to one another.
1119 Similarly, a \meta{header} of |\hfil#\cr| causes the text to be flushed
1120 right.
1121
1122 Note that this mechanism is not flexible enough to all multiple columns
1123 inside \meta{header}. You will have to use a |tabular| or a |matrix| in
1124 such cases.
1125
1126 One further note: Since the text of each line is placed in a box, settings
1127 will be local to each ``line''. This is very similar to the way a cell in a
1128 |tabular| or a |matrix| behaves.
1129 \end{key}
1130
1131
1132 \subsubsection{Text Parameters: Height and Depth of Text}
1133
1134 In addition to changing the width of nodes, you can also change the height of
1135 nodes. This can be done in two ways: First, you can use the option
1136 |minimum height|, which ensures that the height of the whole node is at least
1137 the given height (this option is described in more detail later). Second, you
1138 can use the option |text height|, which sets the height of the text itself,
1139 more precisely, of the \TeX\ text box of the text. Note that the |text height|
1140 typically is not the height of the shape's box: In addition to the
1141 |text height|, an internal |inner sep| is added as extra space and the text
1142 depth is also taken into account.
1143
1144 I recommend using |minimum size| instead of |text height| except for special
1145 situations.
1146
1147 \begin{key}{/tikz/text height=\meta{dimension}}
1148 Sets the height of the text boxes in shapes. Thus, when you write something
1149 like |node {text}|, the |text| is first typeset, resulting in some box of a
1150 certain height. This height is then replaced by the height |text height|.
1151 The resulting box is then used to determine the size of the shape, which
1152 will typically be larger. When you write |text height=| without specifying
1153 anything, the ``natural'' size of the text box remains unchanged.
1154 %
1155 \begin{codeexample}[]
1156 \tikz \node[draw] {y};
1157 \tikz \node[draw,text height=10pt] {y};
1158 \end{codeexample}
1159 %
1160 \end{key}
1161
1162 \begin{key}{/tikz/text depth=\meta{dimension}}
1163 This option works like |text height|, only for the depth of the text box.
1164 This option is mostly useful when you need to ensure a uniform depth of
1165 text boxes that need to be aligned.
1166 \end{key}
1167
1168
1169 \subsection{Positioning Nodes}
1170 \label{section-nodes-anchors}
1171
1172 When you place a node at some coordinate, the node is centered on this
1173 coordinate by default. This is often undesirable and it would be better to have
1174 the node to the right or above the actual coordinate.
1175
1176
1177 \subsubsection{Positioning Nodes Using Anchors}
1178
1179 \pgfname\ uses a so-called anchoring mechanism to give you a very fine control
1180 over the placement. The idea is simple: Imagine a node of rectangular shape of
1181 a certain size. \pgfname\ defines numerous anchor positions in the shape. For
1182 example the upper right corner is called, well, not ``upper right anchor'', but
1183 the |north east| anchor of the shape. The center of the shape has an anchor
1184 called |center| on top of it, and so on. Here are some examples (a complete
1185 list for predefined shapes is given in Section~\ref{section-predefined-shapes}).
1186
1187 \medskip\noindent
1188 \begin{tikzpicture}
1189 \path node[minimum height=2cm,minimum width=5cm,fill=blue!25](x) {Big node};
1190 \fill (x.north) circle (2pt) node[above] {|north|}
1191 (x.north east) circle (2pt) node[above] {|north east|}
1192 (x.north west) circle (2pt) node[above] {|north west|}
1193 (x.west) circle (2pt) node[left] {|west|}
1194 (x.east) circle (2pt) node[right] {|east|}
1195 (x.base) circle (2pt) node[below] {|base|};
1196 \end{tikzpicture}
1197
1198 Now, when you place a node at a certain coordinate, you can ask \tikzname\ to
1199 place the node shifted around in such a way that a certain anchor is at the
1200 coordinate. In the following example, we ask \tikzname\ to shift the first node
1201 such that its |north east| anchor is at coordinate |(0,0)| and that the |west|
1202 anchor of the second node is at coordinate |(1,1)|.
1203 %
1204 \begin{codeexample}[]
1205 \tikz \draw (0,0) node[anchor=north east] {first node}
1206 rectangle (1,1) node[anchor=west] {second node};
1207 \end{codeexample}
1208
1209 Since the default anchor is |center|, the default behavior is to shift the node
1210 in such a way that it is centered on the current position.
1211
1212 \begin{key}{/tikz/anchor=\meta{anchor name}}
1213 Causes the node to be shifted such that its anchor \meta{anchor name} lies
1214 on the current coordinate.
1215
1216 The only anchor that is present in all shapes is |center|. However, most
1217 shapes will at least define anchors in all ``compass directions''.
1218 Furthermore, the standard shapes also define a |base| anchor, as well as
1219 |base west| and |base east|, for placing things on the baseline of the
1220 text.
1221
1222 The standard shapes also define a |mid| anchor (and |mid west| and
1223 |mid east|). This anchor is half the height of the character ``x'' above
1224 the base line. This anchor is useful for vertically centering multiple
1225 nodes that have different heights and depth. Here is an example:
1226 %
1227 \begin{codeexample}[]
1228 \begin{tikzpicture}[scale=3,transform shape]
1229 % First, center alignment -> wobbles
1230 \draw[anchor=center] (0,1) node{x} -- (0.5,1) node{y} -- (1,1) node{t};
1231 % Second, base alignment -> no wobble, but too high
1232 \draw[anchor=base] (0,.5) node{x} -- (0.5,.5) node{y} -- (1,.5) node{t};
1233 % Third, mid alignment
1234 \draw[anchor=mid] (0,0) node{x} -- (0.5,0) node{y} -- (1,0) node{t};
1235 \end{tikzpicture}
1236 \end{codeexample}
1237 %
1238 \end{key}
1239
1240
1241 \subsubsection{Basic Placement Options}
1242
1243 Unfortunately, while perfectly logical, it is often rather counter-intuitive
1244 that in order to place a node \emph{above} a given point, you need to specify
1245 the |south| anchor. For this reason, there are some useful options that allow
1246 you to select the standard anchors more intuitively:
1247
1248 \begin{key}{/tikz/above=\meta{offset} (default 0pt)}
1249 Does the same as |anchor=south|. If the \meta{offset} is specified, the
1250 node is additionally shifted upwards by the given \meta{offset}.
1251 %
1252 \begin{codeexample}[]
1253 \tikz \fill (0,0) circle (2pt) node[above] {above};
1254 \end{codeexample}
1255 %
1256 \begin{codeexample}[]
1257 \tikz \fill (0,0) circle (2pt) node[above=2pt] {above};
1258 \end{codeexample}
1259 %
1260 \end{key}
1261
1262 \begin{key}{/tikz/below=\meta{offset} (default 0pt)}
1263 Similar to |above|.
1264 \end{key}
1265
1266 \begin{key}{/tikz/left=\meta{offset} (default 0pt)}
1267 Similar to |above|.
1268 \end{key}
1269
1270 \begin{key}{/tikz/right=\meta{offset} (default 0pt)}
1271 Similar to |above|.
1272 \end{key}
1273
1274 \begin{key}{/tikz/above left}
1275 Does the same as |anchor=south east|. Note that giving both |above| and
1276 |left| options does not have the same effect as |above left|, rather only
1277 the last |left| ``wins''. Actually, this option also takes an \meta{offset}
1278 parameter, but using this parameter without using the |positioning| library
1279 is deprecated. (The |positioning| library changes the meaning of this
1280 parameter to something more sensible.)
1281 %
1282 \begin{codeexample}[]
1283 \tikz \fill (0,0) circle (2pt) node[above left] {above left};
1284 \end{codeexample}
1285 %
1286 \end{key}
1287
1288 \begin{key}{/tikz/above right}
1289 Similar to |above left|.
1290 %
1291 \begin{codeexample}[]
1292 \tikz \fill (0,0) circle (2pt) node[above right] {above right};
1293 \end{codeexample}
1294 %
1295 \end{key}
1296
1297 \begin{key}{/tikz/below left}
1298 Similar to |above left|.
1299 \end{key}
1300
1301 \begin{key}{/tikz/below right}
1302 Similar to |above left|.
1303 \end{key}
1304
1305 \begin{key}{/tikz/centered}
1306 A shorthand for |anchor=center|.
1307 \end{key}
1308
1309 % A second set of options behaves similarly, namely the |above of|,
1310 % |below of|, and so on options. They cause the same anchors to be set
1311 % as the options without |of|, however, their parameter is different:
1312 % You must provide the name of another node. The current node will then
1313 % be placed, say, above this specified node at a distance given by the
1314 % option |node distance|.
1315 % \begin{key}{/tikz/above of=\meta{node}}
1316 % This option causes the node to be placed at the distance
1317 % |node distance| above of \meta{node}. The anchor is |center|.
1318 % \begin{codeexample}[]
1319 % \begin{tikzpicture}[node distance=1cm]
1320 % \draw[help lines] (0,0) grid (3,2);
1321 % \node (a) {a};
1322 % \node (b) [above of=a] {b};
1323 % \node (c) [above of=b] {c};
1324 % \node (d) [right of=c] {d};
1325 % \node (e) [below right of=d] {e};
1326 % \end{tikzpicture}
1327 % \end{codeexample}
1328 % \end{key}
1329 %
1330 % \begin{key}{/tikz/above left of=\meta{node}}
1331 % Works like |above of|, only the node is now put above and left. The
1332 % |node distance| is the Euclidean distance between the two nodes, not
1333 % the $L_1$-distance.
1334 % \end{key}
1335 %
1336 % \begin{key}{/tikz/above right of=\meta{node}}
1337 % Works similarly.
1338 % \end{key}
1339 % \begin{key}{/tikz/left of=\meta{node}}
1340 % Works similarly.
1341 % \end{key}
1342 % \begin{key}{/tikz/right of=\meta{node}}
1343 % Works similarly.
1344 % \end{key}
1345 % \begin{key}{/tikz/below of=\meta{node}}
1346 % Works similarly.
1347 % \end{key}
1348 % \begin{key}{/tikz/below left of=\meta{node}}
1349 % Works similarly.
1350 % \end{key}
1351 % \begin{key}{/tikz/below right of=\meta{node}}
1352 % Works similarly.
1353 % \end{key}
1354 % \begin{key}{/tikz/node distance=\meta{dimension}}
1355 % Sets the distance between nodes that are placed using the
1356 % |... of| options. Note that this distance is the distance between
1357 % the centers of the nodes, not the distance between their borders.
1358 % \end{key}
1359
1360
1361 \subsubsection{Advanced Placement Options}
1362
1363 While the standard placement options suffice for simple cases, the
1364 |positioning| library offers more convenient placement options.
1365
1366 \begin{tikzlibrary}{positioning}
1367 The library defines additional options for placing nodes conveniently. It
1368 also redefines the standard options like |above| so that they give you
1369 better control of node placement.
1370 \end{tikzlibrary}
1371
1372 When this library is loaded, the options like |above| or |above left| behave
1373 differently.
1374
1375 \begin{key}{/tikz/above=\opt{\meta{specification}} (default 0pt)}
1376 With the |positioning| library loaded, the |above| option does not take a
1377 simple \meta{dimension} as its parameter. Rather, it can (also) take a more
1378 elaborate \meta{specification} as parameter. This \meta{specification} has
1379 the following general form: It starts with an optional \meta{shifting part}
1380 and is followed by an optional \meta{of-part}. Let us start with the
1381 \meta{shifting part}, which can have three forms:
1382 %
1383 \begin{enumerate}
1384 \item It can simply be a \declare{\meta{dimension}} (or a mathematical
1385 expression that evaluates to a dimension) like |2cm| or
1386 |3cm/2+4cm|. In this case, the following happens: the node's anchor
1387 is set to |south| and the node is vertically shifted upwards by
1388 \meta{dimension}.
1389 %
1390 \begin{codeexample}[]
1391 \begin{tikzpicture}
1392 \draw[help lines] (0,0) grid (2,2);
1393 \node at (1,1) [above=2pt+3pt,draw] {above};
1394 \end{tikzpicture}
1395 \end{codeexample}
1396 %
1397 This use of the |above| option is the same as if the |positioning|
1398 library were not loaded.
1399 \item It can be a \declare{\meta{number}} (that is, any mathematical
1400 expression that does not include a unit like |pt| or |cm|).
1401 Examples are |2| or |3+sin(60)|. In this case, the anchor is also
1402 set to |south| and the node is vertically shifted by the vertical
1403 component of the coordinate |(0,|\meta{number}|)|.
1404 %
1405 \begin{codeexample}[]
1406 \begin{tikzpicture}
1407 \draw[help lines] (0,0) grid (2,2);
1408 \node at (1,1) [above=.2,draw] {above};
1409 % south border of the node is now 2mm above (1,1)
1410 \end{tikzpicture}
1411 \end{codeexample}
1412 %
1413 \item It can be of the form
1414 \declare{\meta{number or dimension 1}| and |\meta{number or dimension 2}}.
1415 This specification does not make particular sense for the |above|
1416 option, it is much more useful for options like |above left|. The
1417 reason it is allowed for the |above| option is that it is sometimes
1418 automatically used, as explained later.
1419
1420 The effect of this option is the following. First, the point
1421 |(|\meta{number or dimension 2}|,|\meta{number or dimension 1}|)|
1422 is computed (note the inverted order), using the normal rules for
1423 evaluating such a coordinate, yielding some position. Then, the
1424 node is shifted by the vertical component of this point. The anchor
1425 is set to |south|.
1426 %
1427 \begin{codeexample}[preamble={\usetikzlibrary{positioning}}]
1428 \begin{tikzpicture}
1429 \draw[help lines] (0,0) grid (2,2);
1430 \node at (1,1) [above=.2 and 3mm,draw] {above};
1431 % south border of the node is also 2mm above (1,1)
1432 \end{tikzpicture}
1433 \end{codeexample}
1434 \end{enumerate}
1435 %
1436 The \meta{shifting part} can optionally be followed by a \meta{of-part},
1437 which has one of the following forms:
1438 %
1439 \begin{enumerate}
1440 \item The \meta{of-part} can be
1441 \declareandlabel{of}| |\meta{coordinate}, where \meta{coordinate} is
1442 \emph{not} in parentheses and it is \emph{not} just a node name. An
1443 example would be |of somenode.north| or |of {2,3}|. In this case, the
1444 following happens: First, the node's |at| parameter is set to the
1445 \meta{coordinate}. Second, the node is shifted according to the
1446 \meta{shift-part}. Third, the anchor is set to |south|.
1447
1448 Here is a basic example:
1449 %
1450 \begin{codeexample}[preamble={\usetikzlibrary{positioning}}]
1451 \begin{tikzpicture}[every node/.style=draw]
1452 \draw[help lines] (0,0) grid (2,2);
1453 \node (somenode) at (1,1) {some node};
1454
1455 \node [above=5mm of somenode.north east] {\tiny 5mm of somenode.north east};
1456 \node [above=1cm of somenode.north] {\tiny 1cm of somenode.north};
1457 \end{tikzpicture}
1458 \end{codeexample}
1459 %
1460 As can be seen the |above=5mm of somenode.north east| option does,
1461 indeed, place the node 5mm above the north east anchor of
1462 |somenode|. The same effect could have been achieved writing
1463 |above=5mm| followed by |at=(somenode.north east)|.
1464
1465 If the \meta{shifting-part} is missing, the shift is not zero, but
1466 rather the value of the |node distance| key is used, see below.
1467 \item The \meta{of-part} can be |of |\meta{node name}. An example would
1468 be |of somenode|. In this case, the following usually happens:
1469 %
1470 \begin{itemize}
1471 \item The anchor is set to |south|.
1472 \item The node is shifted according to the \meta{shifting part}
1473 or, if it is missing, according to the value of
1474 |node distance|.
1475 \item The node's |at| parameter is set to \meta{node
1476 name}|.north|.
1477 \end{itemize}
1478 %
1479 The net effect of all this is that the new node will be placed in
1480 such a way that the distance between its south border and \meta{node
1481 name}'s north border is exactly the given distance.
1482 %
1483 \begin{codeexample}[preamble={\usetikzlibrary{positioning}}]
1484 \begin{tikzpicture}[every node/.style=draw]
1485 \draw[help lines] (0,0) grid (2,2);
1486 \node (some node) at (1,1) {some node};
1487
1488 \node (other node) [above=1cm of some node] {\tiny above=1cm of some node};
1489
1490 \draw [<->] (some node.north) -- (other node.south)
1491 node [midway,right,draw=none] {1cm};
1492 \end{tikzpicture}
1493 \end{codeexample}
1494 %
1495 It is possible to change the behavior of this \meta{specification}
1496 rather drastically, using the following key:
1497 %
1498 \begin{key}{/tikz/on grid=\meta{boolean} (initially false)}
1499 When this key is set to |true|, an \meta{of-part} of the
1500 current form behaves differently: The anchors set for the
1501 current node as well as the anchor used for the other
1502 \meta{node name} are set to |center|.
1503
1504 This has the following effect: When you say
1505 |above=1cm of somenode| with |on grid| set to true, the new
1506 node will be placed in such a way that its center is 1cm above
1507 the center of |somenode|. Repeatedly placing nodes in this way
1508 will result in nodes that are centered on ``grid coordinate'',
1509 hence the name of the option.
1510 %
1511 \begin{codeexample}[preamble={\usetikzlibrary{positioning}}]
1512 \begin{tikzpicture}[every node/.style=draw]
1513 \draw[help lines] (0,0) grid (2,3);
1514
1515 % Not gridded
1516 \node (a1) at (0,0) {not gridded};
1517 \node (b1) [above=1cm of a1] {fooy};
1518 \node (c1) [above=1cm of b1] {a};
1519
1520 % gridded
1521 \node (a2) at (2,0) {gridded};
1522 \node (b2) [on grid,above=1cm of a2] {fooy};
1523 \node (c2) [on grid,above=1cm of b2] {a};
1524 \end{tikzpicture}
1525 \end{codeexample}
1526 \end{key}
1527 \end{enumerate}
1528
1529 \begin{key}{/tikz/node distance=\meta{shifting part} (initially 1cm and 1cm)}
1530 The value of this key is used as \meta{shifting part} is used if and
1531 only if a \meta{of-part} is present, but no \meta{shifting part}.
1532 %
1533 \begin{codeexample}[preamble={\usetikzlibrary{positioning}}]
1534 \begin{tikzpicture}[every node/.style=draw,node distance=5mm]
1535 \draw[help lines] (0,0) grid (2,3);
1536
1537 % Not gridded
1538 \node (a1) at (0,0) {not gridded};
1539 \node (b1) [above=of a1] {fooy};
1540 \node (c1) [above=of b1] {a};
1541
1542 % gridded
1543 \begin{scope}[on grid]
1544 \node (a2) at (2,0) {gridded};
1545 \node (b2) [above=of a2] {fooy};
1546 \node (c2) [above=of b2] {a};
1547 \end{scope}
1548 \end{tikzpicture}
1549 \end{codeexample}
1550 \end{key}
1551 \end{key}
1552
1553 \begin{key}{/tikz/below=\opt{\meta{specification}}}
1554 This key is redefined in the same manner as |above|.
1555 \end{key}
1556
1557 \begin{key}{/tikz/left=\opt{\meta{specification}}}
1558 This key is redefined in the same manner as |above|, only all vertical
1559 shifts are replaced by horizontal shifts.
1560 \end{key}
1561
1562 \begin{key}{/tikz/right=\opt{\meta{specification}}}
1563 This key is redefined in the same manner as |left|.
1564 \end{key}
1565
1566 \begin{key}{/tikz/above left=\opt{\meta{specification}}}
1567 This key is also redefined in a manner similar to the above, but behavior
1568 of the \meta{shifting part} is more complicated:
1569 %
1570 \begin{enumerate}
1571 \item When the \meta{shifting part} is of the form
1572 \meta{number or dimension}| and |\meta{number or dimension}, it has
1573 (essentially) the effect of shifting the node vertically upwards by
1574 the first \meta{number or dimension} and to the left by the second.
1575 To be more precise, the coordinate |(|\meta{second number or
1576 dimension}|,|\meta{first number or dimension}|)| is computed and
1577 then the node is shifted vertically by the $y$-part of the
1578 resulting coordinate and horizontally be the negated $x$-part of
1579 the result. (This is exactly what you expect, except possibly when
1580 you have used the |x| and |y| options to modify the |xy|-coordinate
1581 system so that the unit vectors no longer point in the expected
1582 directions.)
1583 \item When the \meta{shifting part} is of the form \meta{number or
1584 dimension}, the node is shifted by this \meta{number or dimension}
1585 in the direction of $135^\circ$. This means that there is a
1586 difference between a \meta{shifting part} of |1cm| and of
1587 |1cm and 1cm|: In the second case, the node is shifted by 1cm
1588 upward and 1cm to the left; in the first case it is shifted by
1589 $\frac{1}{2}\sqrt{2}$cm upward and by the same amount to the left.
1590 A more mathematical way of phrasing this is the following: A plain
1591 \meta{dimension} is measured in the $l_2$-norm, while a
1592 \meta{dimension}| and |\meta{dimension} is measured in the
1593 $l_1$-norm.
1594 \end{enumerate}
1595 %
1596 The following example should help to illustrate the difference:
1597 %
1598 \begin{codeexample}[preamble={\usetikzlibrary{positioning}}]
1599 \begin{tikzpicture}[every node/.style={draw,circle}]
1600 \draw[help lines] (0,0) grid (2,5);
1601 \begin{scope}[node distance=5mm and 5mm]
1602 \node (b) at (1,4) {b};
1603 \node [left=of b] {1}; \node [right=of b] {2};
1604 \node [above=of b] {3}; \node [below=of b] {4};
1605 \node [above left=of b] {5}; \node [above right=of b] {6};
1606 \node [below left=of b] {7}; \node [below right=of b] {8};
1607 \end{scope}
1608 \begin{scope}[node distance=5mm]
1609 \node (a) at (1,1) {a};
1610 \node [left=of a] {1}; \node [right=of a] {2};
1611 \node [above=of a] {3}; \node [below=of a] {4};
1612 \node [above left=of a] {5}; \node [above right=of a] {6};
1613 \node [below left=of a] {7}; \node [below right=of a] {8};
1614 \end{scope}
1615 \end{tikzpicture}
1616 \end{codeexample}
1617 %
1618 \begin{codeexample}[preamble={\usetikzlibrary{positioning}}]
1619 \begin{tikzpicture}[every node/.style={draw,rectangle}]
1620 \draw[help lines] (0,0) grid (2,5);
1621 \begin{scope}[node distance=5mm and 5mm]
1622 \node (b) at (1,4) {b};
1623 \node [left=of b] {1}; \node [right=of b] {2};
1624 \node [above=of b] {3}; \node [below=of b] {4};
1625 \node [above left=of b] {5}; \node [above right=of b] {6};
1626 \node [below left=of b] {7}; \node [below right=of b] {8};
1627 \end{scope}
1628 \begin{scope}[node distance=5mm]
1629 \node (a) at (1,1) {a};
1630 \node [left=of a] {1}; \node [right=of a] {2};
1631 \node [above=of a] {3}; \node [below=of a] {4};
1632 \node [above left=of a] {5}; \node [above right=of a] {6};
1633 \node [below left=of a] {7}; \node [below right=of a] {8};
1634 \end{scope}
1635 \end{tikzpicture}
1636 \end{codeexample}
1637 %
1638 \begin{codeexample}[preamble={\usetikzlibrary{positioning}}]
1639 \begin{tikzpicture}[every node/.style={draw,rectangle},on grid]
1640 \draw[help lines] (0,0) grid (4,4);
1641 \begin{scope}[node distance=1]
1642 \node (a) at (2,3) {a};
1643 \node [left=of a] {1}; \node [right=of a] {2};
1644 \node [above=of a] {3}; \node [below=of a] {4};
1645 \node [above left=of a] {5}; \node [above right=of a] {6};
1646 \node [below left=of a] {7}; \node [below right=of a] {8};
1647 \end{scope}
1648 \begin{scope}[node distance=1 and 1]
1649 \node (b) at (2,0) {b};
1650 \node [left=of b] {1}; \node [right=of b] {2};
1651 \node [above=of b] {3}; \node [below=of b] {4};
1652 \node [above left=of b] {5}; \node [above right=of b] {6};
1653 \node [below left=of b] {7}; \node [below right=of b] {8};
1654 \end{scope}
1655 \end{tikzpicture}
1656 \end{codeexample}
1657 %
1658 \end{key}
1659
1660 \begin{key}{/tikz/below left=\opt{\meta{specification}}}
1661 Works similar to |above left|.
1662 \end{key}
1663
1664 \begin{key}{/tikz/above right=\opt{\meta{specification}}}
1665 Works similar to |above left|.
1666 \end{key}
1667
1668 \begin{key}{/tikz/below right=\opt{\meta{specification}}}
1669 Works similar to |above left|.
1670 \end{key}
1671
1672 The |positioning| package also introduces the following new placement keys:
1673 %
1674 \begin{key}{/tikz/base left=\opt{\meta{specification}}}
1675 This key works like the |left| key, only instead of the |east| anchor, the
1676 |base east| anchor is used and, when the second form of an \meta{of-part}
1677 is used, the corresponding |base west| anchor.
1678
1679 This key is useful for chaining together nodes so that their base lines are
1680 aligned.
1681 %
1682 \begin{codeexample}[preamble={\usetikzlibrary{positioning}}]
1683 \begin{tikzpicture}[node distance=1ex]
1684 \draw[help lines] (0,0) grid (3,1);
1685 \huge
1686 \node (X) at (0,1) {X};
1687 \node (a) [right=of X] {a};
1688 \node (y) [right=of a] {y};
1689
1690 \node (X) at (0,0) {X};
1691 \node (a) [base right=of X] {a};
1692 \node (y) [base right=of a] {y};
1693 \end{tikzpicture}
1694 \end{codeexample}
1695 %
1696 \end{key}
1697
1698 \begin{key}{/tikz/base right=\opt{\meta{specification}}}
1699 Works like |base left|.
1700 \end{key}
1701 \begin{key}{/tikz/mid left=\opt{\meta{specification}}}
1702 Works like |base left|, but with |mid east| and |mid west| anchors instead
1703 of |base east| and |base west|.
1704 \end{key}
1705
1706 \begin{key}{/tikz/mid right=\opt{\meta{specification}}}
1707 Works like |mid left|.
1708 \end{key}
1709
1710
1711 \subsubsection{Advanced Arrangements of Nodes}
1712
1713 The simple |above| and |right| options may not always suffice for arranging a
1714 large number of nodes. For such situations \tikzname\ offers libraries that
1715 make positioning easier: The |matrix| library and the |graphdrawing| library.
1716 These libraries for positioning nodes are described in two separate
1717 Sections~\ref{section-matrices} and~\ref{section-intro-gd}.
1718
1719
1720 \subsection{Fitting Nodes to a Set of Coordinates}
1721 \label{section-nodes-fitting}
1722
1723 It is sometimes desirable that the size and position of a node is not given
1724 using anchors and size parameters, rather one would sometimes have a box be
1725 placed and be sized such that it ``is just large enough to contain this, that,
1726 and that point''. This situation typically arises when a picture has been drawn
1727 and, afterwards, parts of the picture are supposed to be encircled or
1728 highlighted.
1729
1730 In this situation the |fit| option from the |fit| library is useful, see
1731 Section~\ref{section-library-fit} for the details. The idea is that you may
1732 give the |fit| option to a node. The |fit| option expects a list of coordinates
1733 (one after the other without commas) as its parameter. The effect will be that
1734 the node's text area has exactly the necessary size so that it contains all the
1735 given coordinates. Here is an example:
1736 %
1737 \begin{codeexample}[preamble={\usetikzlibrary{fit,shapes.geometric}}]
1738 \begin{tikzpicture}[level distance=8mm]
1739 \node (root) {root}
1740 child { node (a) {a} }
1741 child { node (b) {b}
1742 child { node (d) {d} }
1743 child { node (e) {e} } }
1744 child { node (c) {c} };
1745
1746 \node[draw=red,inner sep=0pt,thick,ellipse,fit=(root) (b) (d) (e)] {};
1747 \node[draw=blue,inner sep=0pt,thick,ellipse,fit=(b) (c) (e)] {};
1748 \end{tikzpicture}
1749 \end{codeexample}
1750
1751 If you want to fill the fitted node you will usually have to place it on a
1752 background layer.
1753 %
1754 \begin{codeexample}[preamble={\usetikzlibrary{backgrounds,fit,shapes.geometric}}]
1755 \begin{tikzpicture}[level distance=8mm]
1756 \node (root) {root}
1757 child { node (a) {a} }
1758 child { node (b) {b}
1759 child { node (d) {d} }
1760 child { node (e) {e} } }
1761 child { node (c) {c} };
1762
1763 \begin{scope}[on background layer]
1764 \node[fill=red!20,inner sep=0pt,ellipse,fit=(root) (b) (d) (e)] {};
1765 \node[fill=blue!20,inner sep=0pt,ellipse,fit=(b) (c) (e)] {};
1766 \end{scope}
1767 \end{tikzpicture}
1768 \end{codeexample}
1769
1770
1771 \subsection{Transformations}
1772 \label{section-nodes-transformations}
1773
1774 It is possible to transform nodes, but, by default, transformations do not
1775 apply to nodes. The reason is that you usually do \emph{not} want your text to
1776 be scaled or rotated even if the main graphic is transformed. Scaling text is
1777 evil, rotating slightly less so.
1778
1779 However, sometimes you \emph{do} wish to transform a node, for example, it
1780 certainly sometimes makes sense to rotate a node by 90 degrees. There are two
1781 ways to achieve this:
1782 %
1783 \begin{enumerate}
1784 \item You can use the following option:
1785 %
1786 \begin{key}{/tikz/transform shape}
1787 Causes the current ``external'' transformation matrix to be applied
1788 to the shape. For example, if you said |\tikz[scale=3]| and then
1789 say |node[transform shape] {X}|, you will get a ``huge'' X in your
1790 graphic.
1791 \end{key}
1792 \item You can give transformation options \emph{inside} the option list of
1793 the node. \emph{These} transformations always apply to the node.
1794 %
1795 \begin{codeexample}[
1796 preamble={\usepgfmodule{nonlineartransformations}\usetikzlibrary{curvilinear}},
1797 pre={\makeatletter},
1798 ]
1799 \begin{tikzpicture}[every node/.style={draw}]
1800 \draw[help lines](0,0) grid (3,2);
1801 \draw (1,0) node{A}
1802 (2,0) node[rotate=90,scale=1.5] {B};
1803 \draw[rotate=30] (1,0) node{A}
1804 (2,0) node[rotate=90,scale=1.5] {B};
1805 \draw[rotate=60] (1,0) node[transform shape] {A}
1806 (2,0) node[transform shape,rotate=90,scale=1.5] {B};
1807 \end{tikzpicture}
1808 \end{codeexample}
1809 %
1810 \end{enumerate}
1811
1812 Even though \tikzname\ currently does not allow you to configure so-called
1813 \emph{nonlinear transformations,} see
1814 Section~\ref{section-nonlinear-transformations}, there is an option that
1815 influences how nodes are transformed when nonlinear transformations are in
1816 force:
1817 %
1818 \begin{key}{/tikz/transform shape nonlinear=\opt{\meta{true or false}} (initially false)}
1819 When set to true, \tikzname\ will try to apply any current nonlinear
1820 transformation also to nodes. Typically, for the text in nodes this is not
1821 possible in general, in such cases a linear approximation of the nonlinear
1822 transformation is used. For more details, see
1823 Section~\ref{section-nonlinear-transformations}.
1824 %
1825 \makeatletter
1826 \begin{codeexample}[
1827 preamble={\usepgfmodule{nonlineartransformations}\usetikzlibrary{curvilinear}},
1828 pre={\makeatletter},
1829 ]
1830 \begin{tikzpicture}
1831 % Install a nonlinear transformation:
1832 \pgfsetcurvilinearbeziercurve
1833 {\pgfpoint{0mm}{20mm}}
1834 {\pgfpoint{10mm}{20mm}}
1835 {\pgfpoint{10mm}{10mm}}
1836 {\pgfpoint{20mm}{10mm}}
1837 \pgftransformnonlinear{\pgfpointcurvilinearbezierorthogonal\pgf@x\pgf@y}%
1838
1839 % Draw something:
1840 \draw [help lines] (0,-30pt) grid [step=10pt] (80pt,30pt);
1841
1842 \foreach \x in {0,20,...,80}
1843 \node [fill=red!20] at (\x pt, -20pt) {\x};
1844
1845 \foreach \x in {0,20,...,80}
1846 \node [fill=blue!20, transform shape nonlinear] at (\x pt, 20pt) {\x};
1847 \end{tikzpicture}
1848 \end{codeexample}
1849 %
1850 \end{key}
1851
1852
1853 \subsection{Placing Nodes on a Line or Curve Explicitly}
1854 \label{section-nodes-placing-1}
1855
1856 Until now, we always placed nodes on a coordinate that is mentioned in the path.
1857 Often, however, we wish to place nodes on ``the middle'' of a line and we do
1858 not wish to compute these coordinates ``by hand''. To facilitate such
1859 placements, \tikzname\ allows you to specify that a certain node should be
1860 somewhere ``on'' a line. There are two ways of specifying this: Either
1861 explicitly by using the |pos| option or implicitly by placing the node
1862 ``inside'' a path operation. These two ways are described in the following.
1863
1864 \label{section-pos-option}
1865
1866 \begin{key}{/tikz/pos=\meta{fraction}}
1867 When this option is given, the node is not anchored on the last coordinate.
1868 Rather, it is anchored on some point on the line from the previous
1869 coordinate to the current point. The \meta{fraction} dictates how ``far''
1870 on the line the point should be. A \meta{fraction} of 0 is the previous
1871 coordinate, 1 is the current one, everything else is in between. In
1872 particular, 0.5 is the middle.
1873
1874 Now, what is ``the previous line''? This depends on the previous path
1875 construction operation.
1876
1877 In the simplest case, the previous path operation was a ``line-to''
1878 operation, that is, a |--|\meta{coordinate} operation:
1879 %
1880 \begin{codeexample}[]
1881 \tikz \draw (0,0) -- (3,1)
1882 node[pos=0]{0} node[pos=0.5]{1/2} node[pos=0.9]{9/10};
1883 \end{codeexample}
1884
1885 For the |arc| operation, the position is simply the corresponding position
1886 on the arc:
1887 %
1888 \begin{codeexample}[]
1889 \tikz {
1890 \draw [help lines] (0,0) grid (3,2);
1891 \draw (2,0) arc [x radius=1, y radius=2, start angle=0, end angle=180]
1892 node foreach \t in {0,0.125,...,1} [pos=\t,auto] {\t};
1893 }
1894 \end{codeexample}
1895
1896 The next case is the curve-to operation (the |..| operation). In this case,
1897 the ``middle'' of the curve, that is, the position |0.5| is not necessarily
1898 the point at the exact half distance on the line. Rather, it is some point
1899 at ``time'' 0.5 of a point traveling from the start of the curve, where it
1900 is at time 0, to the end of the curve, which it reaches at time 0.5. The
1901 ``speed'' of the point depends on the length of the support vectors (the
1902 vectors that connect the start and end points to the control points). The
1903 exact math is a bit complicated (depending on your point of view, of
1904 course); you may wish to consult a good book on computer graphics and
1905 Bézier curves if you are intrigued.
1906 %
1907 \begin{codeexample}[]
1908 \tikz \draw (0,0) .. controls +(right:3.5cm) and +(right:3.5cm) .. (0,3)
1909 node foreach \p in {0,0.125,...,1} [pos=\p]{\p};
1910 \end{codeexample}
1911
1912 Another interesting case are the horizontal/vertical line-to operations
1913 \verb!|-! and \verb!-|!. For them, the position (or time) |0.5| is exactly
1914 the corner point.
1915 %
1916 \begin{codeexample}[]
1917 \tikz \draw (0,0) |- (3,1)
1918 node[pos=0]{0} node[pos=0.5]{1/2} node[pos=0.9]{9/10};
1919 \end{codeexample}
1920
1921 \begin{codeexample}[]
1922 \tikz \draw (0,0) -| (3,1)
1923 node[pos=0]{0} node[pos=0.5]{1/2} node[pos=0.9]{9/10};
1924 \end{codeexample}
1925
1926 For all other path construction operations, \emph{the position placement
1927 does not work}, currently.
1928 \end{key}
1929
1930 \begin{key}{/tikz/auto=\opt{\meta{direction}} (default \normalfont is scope's setting)}
1931 This option causes an anchor position to be calculated automatically
1932 according to the following rule. Consider a line between two points. If the
1933 \meta{direction} is |left|, then the anchor is chosen such that the node is
1934 to the left of this line. If the \meta{direction} is |right|, then the node
1935 is to the right of this line. Leaving out \meta{direction} causes automatic
1936 placement to be enabled with the last value of |left| or |right| used. A
1937 \meta{direction} of |false| disables automatic placement. This happens also
1938 whenever an anchor is given explicitly by the |anchor| option or by one of
1939 the |above|, |below|, etc.\ options.
1940
1941 This option only has an effect for nodes that are placed on lines or
1942 curves.
1943 %
1944 \begin{codeexample}[]
1945 \begin{tikzpicture}
1946 [scale=.8,auto=left,every node/.style={circle,fill=blue!20}]
1947 \node (a) at (-1,-2) {a};
1948 \node (b) at ( 1,-2) {b};
1949 \node (c) at ( 2,-1) {c};
1950 \node (d) at ( 2, 1) {d};
1951 \node (e) at ( 1, 2) {e};
1952 \node (f) at (-1, 2) {f};
1953 \node (g) at (-2, 1) {g};
1954 \node (h) at (-2,-1) {h};
1955
1956 \foreach \from/\to in {a/b,b/c,c/d,d/e,e/f,f/g,g/h,h/a}
1957 \draw [->] (\from) -- (\to)
1958 node[midway,fill=red!20] {\from--\to};
1959 \end{tikzpicture}
1960 \end{codeexample}
1961 %
1962 \end{key}
1963
1964 \begin{key}{/tikz/swap}
1965 This option exchanges the roles of |left| and |right| in automatic
1966 placement. That is, if |left| is the current |auto| placement, |right| is
1967 set instead and the other way round.
1968 %
1969 \begin{codeexample}[preamble={\usetikzlibrary{automata}}]
1970 \begin{tikzpicture}[auto]
1971 \draw[help lines,use as bounding box] (0,-.5) grid (4,5);
1972
1973 \draw (0.5,0) .. controls (9,6) and (-5,6) .. (3.5,0)
1974 node foreach \pos in {0,0.1,0.2,0.3,0.4,0.5,0.6,0.7,0.8,0.9,1}
1975 [pos=\pos,swap,fill=red!20] {\pos}
1976 node foreach \pos in {0.025,0.2,0.4,0.6,0.8,0.975}
1977 [pos=\pos,fill=blue!20] {\pos};
1978 \end{tikzpicture}
1979 \end{codeexample}
1980 %
1981 \begin{codeexample}[preamble={\usetikzlibrary{automata}}]
1982 \begin{tikzpicture}[shorten >=1pt,node distance=2cm,auto]
1983 \draw[help lines] (0,0) grid (3,2);
1984
1985 \node[state] (q_0) {$q_0$};
1986 \node[state] (q_1) [above right of=q_0] {$q_1$};
1987 \node[state] (q_2) [below right of=q_0] {$q_2$};
1988 \node[state] (q_3) [below right of=q_1] {$q_3$};
1989
1990 \path[->] (q_0) edge node {0} (q_1)
1991 edge node [swap] {1} (q_2)
1992 (q_1) edge node {1} (q_3)
1993 edge [loop above] node {0} ()
1994 (q_2) edge node [swap] {0} (q_3)
1995 edge [loop below] node {1} ();
1996 \end{tikzpicture}
1997 \end{codeexample}
1998 %
1999 \end{key}
2000
2001 \begin{key}{/tikz/'}
2002 This is a very short alias for |swap|.
2003 \end{key}
2004
2005 \begin{key}{/tikz/sloped}
2006 This option causes the node to be rotated such that a horizontal line
2007 becomes a tangent to the curve. The rotation is normally done in such a way
2008 that text is never ``upside down''. To get upside-down text, use can use
2009 |[rotate=180]| or |[allow upside down]|, see below.
2010 %
2011 \begin{codeexample}[]
2012 \tikz \draw (0,0) .. controls +(up:2cm) and +(left:2cm) .. (1,3)
2013 node foreach \p in {0,0.25,...,1} [sloped,above,pos=\p]{\p};
2014 \end{codeexample}
2015 %
2016 \begin{codeexample}[]
2017 \begin{tikzpicture}[->]
2018 \draw (0,0) -- (2,0.5) node[midway,sloped,above] {$x$};
2019 \draw (2,-.5) -- (0,0) node[midway,sloped,below] {$y$};
2020 \end{tikzpicture}
2021 \end{codeexample}
2022 %
2023 \end{key}
2024
2025
2026 \begin{key}{/tikz/allow upside down=\meta{boolean} (default true, initially false)}
2027 If set to |true|, \tikzname\ will not ``righten'' upside down text.
2028 %
2029 \begin{codeexample}[]
2030 \tikz [allow upside down]
2031 \draw (0,0) .. controls +(up:2cm) and +(left:2cm) .. (1,3)
2032 node foreach \p in {0,0.25,...,1} [sloped,above,pos=\p]{\p};
2033 \end{codeexample}
2034 %
2035 \begin{codeexample}[]
2036 \begin{tikzpicture}[->,allow upside down]
2037 \draw (0,0) -- (2,0.5) node[midway,sloped,above] {$x$};
2038 \draw (2,-.5) -- (0,0) node[midway,sloped,below] {$y$};
2039 \end{tikzpicture}
2040 \end{codeexample}
2041 %
2042 \end{key}
2043
2044 There exist styles for specifying positions a bit less ``technically'':
2045
2046 \begin{stylekey}{/tikz/midway}
2047 This has the same effect as |pos=0.5|.
2048 %
2049 \begin{codeexample}[]
2050 \tikz \draw (0,0) .. controls +(up:2cm) and +(left:3cm) .. (1,5)
2051 node[at end] {\texttt{at end}}
2052 node[very near end] {\texttt{very near end}}
2053 node[near end] {\texttt{near end}}
2054 node[midway] {\texttt{midway}}
2055 node[near start] {\texttt{near start}}
2056 node[very near start] {\texttt{very near start}}
2057 node[at start] {\texttt{at start}};
2058 \end{codeexample}
2059 %
2060 \end{stylekey}
2061
2062 \begin{stylekey}{/tikz/near start}
2063 Set to |pos=0.25|.
2064 \end{stylekey}
2065
2066 \begin{stylekey}{/tikz/near end}
2067 Set to |pos=0.75|.
2068 \end{stylekey}
2069
2070 \begin{stylekey}{/tikz/very near start}
2071 Set to |pos=0.125|.
2072 \end{stylekey}
2073
2074 \begin{stylekey}{/tikz/very near end}
2075 Set to |pos=0.875|.
2076 \end{stylekey}
2077
2078 \begin{stylekey}{/tikz/at start}
2079 Set to |pos=0|.
2080 \end{stylekey}
2081
2082 \begin{stylekey}{/tikz/at end}
2083 Set to |pos=1|.
2084 \end{stylekey}
2085
2086
2087 \subsection{Placing Nodes on a Line or Curve Implicitly}
2088 \label{section-nodes-placing-2}
2089
2090 When you wish to place a node on the line |(0,0) -- (1,1)|, it is natural to
2091 specify the node not following the |(1,1)|, but ``somewhere in the middle''.
2092 This is, indeed, possible and you can write |(0,0) -- node{a} (1,1)| to place a
2093 node midway between |(0,0)| and |(1,1)|.
2094
2095 What happens is the following: The syntax of the line-to path operation is
2096 actually |--| \opt{|node|\meta{node specification}}\meta{coordinate}. (It is
2097 even possible to give multiple nodes in this way.) When the optional |node| is
2098 encountered, that is, when the |--| is directly followed by |node|, then the
2099 specification(s) are read and ``stored away''. Then, after the
2100 \meta{coordinate} has finally been reached, they are inserted again, but with
2101 the |pos| option set.
2102
2103 There are two things to note about this: When a node specification is
2104 ``stored'', its catcodes become fixed. This means that you cannot use overly
2105 complicated verbatim text in them. If you really need, say, a verbatim text,
2106 you will have to put it in a normal node following the coordinate and add the
2107 |pos| option.
2108
2109 Second, which |pos| is chosen for the node? The position is inherited from the
2110 surrounding scope. However, this holds only for nodes specified in this
2111 implicit way. Thus, if you add the option |[near end]| to a scope, this does
2112 not mean that \emph{all} nodes given in this scope will be put on near the end
2113 of lines. Only the nodes for which an implicit |pos| is added will be placed
2114 near the end. Typically, this is what you want. Here are some examples that
2115 should make this clearer:
2116 %
2117 \begin{codeexample}[]
2118 \begin{tikzpicture}[near end]
2119 \draw (0cm,4em) -- (3cm,4em) node{A};
2120 \draw (0cm,3em) -- node{B} (3cm,3em);
2121 \draw (0cm,2em) -- node[midway] {C} (3cm,2em);
2122 \draw (0cm,1em) -- (3cm,1em) node[midway] {D} ;
2123 \end{tikzpicture}
2124 \end{codeexample}
2125
2126 Like the line-to operation, the curve-to operation |..| also allows you to
2127 specify nodes ``inside'' the operation. After both the first |..| and also
2128 after the second |..| you can place node specifications. Like for the |--|
2129 operation, these will be collected and then reinserted after the operation with
2130 the |pos| option set.
2131
2132
2133 \subsection{The Label and Pin Options}
2134
2135 \subsubsection{Overview}
2136
2137 In addition to the |node| path operation, the two options |label| and |pin| can
2138 be used to ``add a node next to another node''. As an example, suppose we want
2139 to draw a graph in which the nodes are small circles:
2140 %
2141 \begin{codeexample}[preamble={\usetikzlibrary{positioning}}]
2142 \tikz [circle] {
2143 \node [draw] (s) {};
2144 \node [draw] (a) [right=of s] {} edge (s);
2145 \node [draw] (b) [right=of a] {} edge (a);
2146 \node [draw] (t) [right=of b] {} edge (b);
2147 }
2148 \end{codeexample}
2149
2150 Now, in the above example, suppose we wish to indicate that the first node is
2151 the start node and the last node is the target node. We could write
2152 |\node (s) {$s$};|, but this would enlarge the first node. Rather, we want the
2153 ``$s$'' to be placed next to the node. For this, we need to create
2154 \emph{another} node, but next to the existing node. The |label| and |pin|
2155 option allow us to do exactly this without having to use the cumbersome |node|
2156 syntax:
2157 %
2158 \begin{codeexample}[preamble={\usetikzlibrary{positioning}}]
2159 \tikz [circle] {
2160 \node [draw] (s) [label=$s$] {};
2161 \node [draw] (a) [right=of s] {} edge (s);
2162 \node [draw] (b) [right=of a] {} edge (a);
2163 \node [draw] (t) [right=of b, label=$t$] {} edge (b);
2164 }
2165 \end{codeexample}
2166
2167
2168 \subsubsection{The Label Option}
2169
2170 \begin{key}{/tikz/label=\opt{|[|\meta{options}|]|\meta{angle}|:|}\meta{text}}
2171 \label{label-option}%
2172 When this option is given to a |node| operation, it causes \emph{another}
2173 node to be added to the path after the current node has been finished. This
2174 extra node will have the text \meta{text}. It is placed, in principle, in
2175 the direction \meta{angle} relative to the main node, but the exact rules
2176 are a bit complex. Suppose the |node| currently under construction is
2177 called |main node| and let us call the label node |label node|. Then the
2178 following happens:
2179 %
2180 \begin{enumerate}
2181 \item The \meta{angle} is used to determine a position on the border of
2182 the |main node|. If the \meta{angle} is missing, the value of the
2183 following key is used instead:
2184 %
2185 \begin{key}{/tikz/label position=\meta{angle} (initially above)}
2186 Sets the default position for labels.
2187 \end{key}
2188 %
2189 The \meta{angle} determines the position on the border of the shape
2190 in two different ways. Normally, the border position is given by
2191 |main node.|\meta{angle}. This means that the \meta{angle} can
2192 either be a number like |0| or |-340|, but it can also be an anchor
2193 like |north|. Additionally, the special angles |above|, |below|,
2194 |left|, |right|, |above left|, and so on are automatically replaced
2195 by the corresponding angles |90|, |270|, |180|, |0|, |135|, and so
2196 on.
2197
2198 A special case arises when the following key is set:
2199 %
2200 \begin{key}{/tikz/absolute=\meta{true or false} (default true)}
2201 When this key is set, the \meta{angle} is interpreted
2202 differently: We still use a point on the border of the
2203 |main node|, but the angle is measured ``absolutely'', that is,
2204 an angle of |0| refers to the point on the border that lies on
2205 a straight line from the |main node|'s center to the right
2206 (relative to the paper, not relative to the local coordinate
2207 system of either the node or the scope).
2208
2209 The difference can be seen in the following example:
2210 %
2211 \begin{codeexample}[]
2212 \tikz [rotate=-80,every label/.style={draw,red}]
2213 \node [transform shape,rectangle,draw,label=right:label] {main node};
2214 \end{codeexample}
2215 %
2216 \begin{codeexample}[]
2217 \tikz [rotate=-80,every label/.style={draw,red},absolute]
2218 \node [transform shape,rectangle,draw,label=right:label] {main node};
2219 \end{codeexample}
2220 \end{key}
2221 \item Then, an anchor point for the |label node| is computed. It is
2222 determined in such a way that the |label node| will ``face away''
2223 from the border of the |main node|. The anchor that is chosen
2224 depends on the position of the border point that is chosen and its
2225 position relative to the center of the |main node| and on whether
2226 the |transform shape| option is set. In detail, when the computed
2227 border point is at $0^\circ$, the anchor |west| will be used.
2228 Similarly, when the border point is at $90^\circ$, the anchor
2229 |south| will be used, and so on for $180^\circ$ and $270^\circ$.
2230
2231 For angles between these ``major'' angles, like $30^\circ$ or
2232 $110^\circ$, combined anchors, like |south west| for $30^\circ$ or
2233 |south east| for $110^\circ$, are used. However, for angles close
2234 to the major angles, (differing by up to $2^\circ$ from the major
2235 angle), the anchor for the major angle is used. Thus, a label at a
2236 border point for $2^\circ$ will have the anchor |west|, while a
2237 label for $3^\circ$ will have the anchor |south west|, resulting in
2238 a ``jump'' of the anchor. You can set the anchor ``by hand'' using
2239 the |anchor| key or indirect keys like |left|.
2240 %
2241 \begin{codeexample}[]
2242 \tikz
2243 \node [circle, draw,
2244 label=default,
2245 label=60:$60^\circ$,
2246 label=below:$-90^\circ$,
2247 label=3:$3^\circ$,
2248 label=2:$2^\circ$,
2249 label={[below]180:$180^\circ$},
2250 label={[centered]135:$135^\circ$}] {my circle};
2251 \end{codeexample}
2252 \item One \meta{angle} is special: If you set the \meta{angle} to
2253 |center|, then the label will be placed on the center of the main
2254 node. This is mainly useful for adding a label text to an existing
2255 node, especially if it has been rotated.
2256 %
2257 \begin{codeexample}[]
2258 \tikz \node [transform shape,rotate=90,
2259 rectangle,draw,label={[red]center:R}] {main node};
2260 \end{codeexample}
2261 \end{enumerate}
2262
2263 You can pass \meta{options} to the node |label node|. For this, you provide
2264 the options in square brackets before the \meta{angle}. If you do so, you
2265 need to add braces around the whole argument of the |label| option and this
2266 is also the case if you have brackets or commas or semicolons or anything
2267 special in the \meta{text}.
2268 %
2269 \begin{codeexample}[]
2270 \tikz \node [circle,draw,label={[red]above:X}] {my circle};
2271 \end{codeexample}
2272
2273 \begin{codeexample}[]
2274 \begin{tikzpicture}
2275 \node [circle,draw,label={[name=label node]above left:$a,b$}] {};
2276 \draw (label node) -- +(1,1);
2277 \end{tikzpicture}
2278 \end{codeexample}
2279
2280 If you provide multiple |label| options, then multiple extra label nodes
2281 are added in the order they are given.
2282
2283 The following styles influence how labels are drawn:
2284 %
2285 \begin{key}{/tikz/label distance=\meta{distance} (initially 0pt)}
2286 The \meta{distance} is additionally inserted between the main node and
2287 the label node.
2288 %
2289 \begin{codeexample}[]
2290 \tikz[label distance=5mm]
2291 \node [circle,draw,label=right:X,
2292 label=above right:Y,
2293 label=above:Z] {my circle};
2294 \end{codeexample}
2295 \end{key}
2296 %
2297 \begin{stylekey}{/tikz/every label (initially \normalfont empty)}
2298 This style is used in every node created by the |label| option. The
2299 default is |draw=none,fill=none|.
2300 \end{stylekey}
2301 \end{key}
2302
2303 See Section~\ref{section-label-quotes} for an easier syntax for specifying
2304 nodes.
2305
2306
2307 \subsubsection{The Pin Option}
2308
2309 \begin{key}{/tikz/pin=\opt{|[|\meta{options}|]|}\meta{angle}|:|\meta{text}}
2310 This option is quite similar to the |label| option, but there is one
2311 difference: In addition to adding an extra node to the picture, it also
2312 adds an edge from this node to the main node. This causes the node to look
2313 like a pin that has been added to the main node:
2314 %
2315 \begin{codeexample}[]
2316 \tikz \node [circle,fill=blue!50,minimum size=1cm,pin=60:$q_0$] {};
2317 \end{codeexample}
2318
2319 The meaning of the \meta{options} and the \meta{angle} and the \meta{text}
2320 is exactly the same as for the |node| option. Only, the options and styles
2321 the influence the way pins look are different:
2322 %
2323 \begin{key}{/tikz/pin distance=\meta{distance} (initially 3ex)}
2324 This \meta{distance} is used instead of the |label distance| for the
2325 distance between the main node and the label node.
2326 %
2327 \begin{codeexample}[]
2328 \tikz[pin distance=1cm]
2329 \node [circle,draw,pin=right:X,
2330 pin=above right:Y,
2331 pin=above:Z] {my circle};
2332 \end{codeexample}
2333 %
2334 \end{key}
2335
2336 \begin{stylekey}{/tikz/every pin (initially {draw=none,fill=none})}
2337 This style is used in every node created by the |pin| option.
2338 \end{stylekey}
2339
2340 \begin{key}{/tikz/pin position=\meta{angle} (initially above)}
2341 The default pin position. Works like |label position|.
2342 \end{key}
2343
2344 \begin{stylekey}{/tikz/every pin edge (initially help lines)}
2345 This style is used in every edge created by the |pin| options.
2346 %
2347 \begin{codeexample}[preamble={\usetikzlibrary{decorations.pathmorphing}}]
2348 \tikz [pin distance=15mm,
2349 every pin edge/.style={<-,shorten <=1pt,decorate,
2350 decoration={snake,pre length=4pt}}]
2351 \node [circle,draw,pin=right:X,
2352 pin=above right:Y,
2353 pin=above:Z] {my circle};
2354 \end{codeexample}
2355 \end{stylekey}
2356
2357 \begin{key}{/tikz/pin edge=\meta{options} (initially \normalfont empty)}
2358 This option can be used to set the options that are to be used in the
2359 edge created by the |pin| option.
2360 %
2361 \begin{codeexample}[]
2362 \tikz[pin distance=10mm]
2363 \node [circle,draw,pin={[pin edge={blue,thick}]right:X},
2364 pin=above:Z] {my circle};
2365 \end{codeexample}
2366 %
2367 \begin{codeexample}[]
2368 \tikz [every pin edge/.style={},
2369 initial/.style={pin={[pin distance=5mm,
2370 pin edge={<-,shorten <=1pt}]left:start}}]
2371 \node [circle,draw,initial] {my circle};
2372 \end{codeexample}
2373 \end{key}
2374 \end{key}
2375
2376
2377 \subsubsection{The Quotes Syntax}
2378 \label{section-label-quotes}
2379
2380 The |label| and |pin| options provide a syntax for creating nodes next to
2381 existing nodes, but this syntax is often a bit too verbose. By including the
2382 following library, you get access to an even more concise syntax:
2383
2384 \begin{tikzlibrary}{quotes}
2385 Enables the quotes syntax for labels, pins, edge nodes, and pic texts.
2386 \end{tikzlibrary}
2387
2388 Let us start with the basics of what this library does: Once loaded, inside the
2389 options of a |node| command, instead of the usual \meta{key}|=|\meta{value}
2390 pairs, you may also provide strings of the following form (the actual syntax is
2391 slightly more general, see the detailed descriptions later on):
2392 %
2393 \begin{quote}
2394 |"|\meta{text}|"|\opt{\meta{options}}
2395 \end{quote}
2396 %
2397 The \meta{options} must be surrounded in curly braces when they contain a
2398 comma, otherwise the curly braces are optional. The \meta{options} may be
2399 preceded by an optional space.
2400
2401 When a \meta{string} of the above form is encountered inside the options of a
2402 |node|, then it is internally transformed to
2403 %
2404 % (the double vertical bar after = is needed to avoid the two opening brackets
2405 % being typeset in italics)
2406 \begin{quote}
2407 |label=||{[|\meta{options}|]|\meta{text}|}|
2408 \end{quote}
2409
2410 Let us have a look at an example:
2411 %
2412 \begin{codeexample}[preamble={\usetikzlibrary{quotes}}]
2413 \tikz \node ["my label" red, draw] {my node};
2414 \end{codeexample}
2415 %
2416 The above has the same effect as the following:
2417 %
2418 \begin{codeexample}[]
2419 \tikz \node [label={[red]my label}, draw] {my node};
2420 \end{codeexample}
2421
2422 Here are further examples, one where no \meta{options} are added to the
2423 |label|, one where a position is specified, and examples with more complicated
2424 options in curly braces:
2425 %
2426 \begin{codeexample}[preamble={\usetikzlibrary{quotes}}]
2427 \begin{tikzpicture}
2428 \matrix [row sep=5mm] {
2429 \node [draw, "label"] {A}; \\
2430 \node [draw, "label" left] {B}; \\
2431 \node [draw, "label" centered] {C}; \\
2432 \node [draw, "label" color=red] {D}; \\
2433 \node [draw, "label" {red,draw,thick}] {E}; \\
2434 };
2435 \end{tikzpicture}
2436 \end{codeexample}
2437
2438 Let us now have a more detailed look at what commands this library
2439 provides:
2440
2441 \begin{key}{/tikz/quotes mean label}
2442 When this option is used (which is the default when this library is
2443 loaded), then, as described above, inside the options of a node a special
2444 syntax check is done.
2445
2446 \medskip
2447 \noindent\textbf{The syntax.}
2448 For each string in the list of options it is tested whether it starts with
2449 a quotation mark (note that this will never happen for normal keys since
2450 the normal keys of \tikzname\ do not start with quotation marks). When this
2451 happens, the \meta{string} should not be a key--value pair, but, rather,
2452 must have the form:
2453 %
2454 \begin{quote}
2455 |"|\meta{text}|"|\opt{|'|}\opt{\meta{options}}
2456 \end{quote}
2457
2458 (We will discuss the optional apostrophe in a moment. It is not really
2459 important for the current option, but only for edge labels, which are
2460 discussed later).
2461
2462 \medskip
2463 \noindent\textbf{Transformation to a label option.}
2464 When a \meta{string} has the above form, it is treated (almost) as if you
2465 had written
2466 %
2467 \begin{quote}
2468 |label={[|\meta{options}|]|\meta{text}|}|
2469 \end{quote}
2470 %
2471 instead. The ``almost'' refers to the following additional feature: In
2472 reality, before the \meta{options} are executed inside the |label| command,
2473 the direction keys |above|, |left|, |below right| and so on are redefined
2474 so that |above| is a shorthand for |label position=90| and similarly for
2475 the other keys. The net effect is that in order to specify the position of
2476 the \meta{text} relative to the main node you can just put something like
2477 |left| or |above right| inside the \meta{options}:
2478 %
2479 \begin{codeexample}[preamble={\usetikzlibrary{quotes}}]
2480 \tikz
2481 \node ["$90^\circ$" above, "$180^\circ$" left, circle, draw] {circle};
2482 \end{codeexample}
2483
2484 Alternatively, you can also use \meta{direction}|:|\meta{actual text} as
2485 your \meta{text}. This works since the |label| command allows you to
2486 specify a direction at the beginning when it is separated by a colon:
2487 %
2488 \begin{codeexample}[preamble={\usetikzlibrary{quotes}}]
2489 \tikz
2490 \node ["90:$90^\circ$", "left:$180^\circ$", circle, draw] {circle};
2491 \end{codeexample}
2492 %
2493 Arguably, placing |above| or |left| behind the \meta{text} seems more
2494 natural than having it inside the \meta{text}.
2495
2496 In addition to the above, before the \meta{options} are executed, the
2497 following style is also executed:
2498 %
2499 \begin{stylekey}{/tikz/every label quotes}
2500 \begin{codeexample}[preamble={\usetikzlibrary{quotes}}]
2501 \tikz [every label quotes/.style=red]
2502 \node ["90:$90^\circ$", "left:$180^\circ$", circle, draw] {circle};
2503 \end{codeexample}
2504 \end{stylekey}
2505
2506 \medskip
2507 \noindent\textbf{Handling commas and colons inside the text.}
2508 The \meta{text} may not contain a comma, unless it is inside curly braces.
2509 The reason is that the key handler separates the total options of a |node|
2510 along the commas it finds. So, in order to have text containing a comma,
2511 just add curly braces around either the comma or just around the whole
2512 \meta{text}:
2513 %
2514 \begin{codeexample}[preamble={\usetikzlibrary{quotes}}]
2515 \tikz \node ["{yes, we can}", draw] {foo};
2516 \end{codeexample}
2517 %
2518 The same is true for a colon, only in this case you may need to surround
2519 specifically the colon by curly braces to stop the |label| option from
2520 interpreting everything before the colon as a direction:
2521 %
2522 \begin{codeexample}[preamble={\usetikzlibrary{quotes}}]
2523 \tikz \node ["yes{:} we can", draw] {foo};
2524 \end{codeexample}
2525
2526 \medskip
2527 \noindent\textbf{The optional apostrophe.}
2528 Following the closing quotation marks in a \meta{string} there may (but
2529 need not) be a single quotation mark (an apostrophe), possibly surrounded
2530 by whitespaces. If it is present, it is simply added to the \meta{options}
2531 as another option (and, indeed, a single apostrophe is a legal option in
2532 \tikzname, it is a shorthand for |swap|):
2533
2534 \begin{tabular}{ll}
2535 String & has the same effect as \\\hline
2536 |"foo"'| & |"foo" {'}| \\
2537 |"foo"' red| & |"foo" {',red}| \\
2538 |"foo"'{red}| & |"foo" {',red}| \\
2539 |"foo"{',red}| & |"foo" {',red}| \\
2540 |"foo"{red,'}| & |"foo" {red,'}| \\
2541 |"foo"{'red}| & |"foo" {'red}| (illegal; there is no key |'red|)\\
2542 |"foo" red'| & |"foo" {red'}| (illegal; there is no key |red'|)\\
2543 \end{tabular}
2544 \end{key}
2545
2546 \begin{key}{/tikz/quotes mean pin}
2547 This option has exactly the same effect as |quotes mean label|, only
2548 instead of transforming quoted text to the |label| option, they get
2549 transformed to the |pin| option:
2550 %
2551 \begin{codeexample}[preamble={\usetikzlibrary{quotes}}]
2552 \tikz [quotes mean pin]
2553 \node ["$90^\circ$" above, "$180^\circ$" left, circle, draw] {circle};
2554 \end{codeexample}
2555 %
2556 Instead of |every label quotes|, the following style is executed
2557 with each such pin:
2558 %
2559 \begin{stylekey}{/tikz/every pin quotes}
2560 \end{stylekey}
2561 \end{key}
2562
2563 If instead of |label|s or |pin|s you would like quoted strings to be
2564 interpreted in a different manner, you can also define your own handlers:
2565
2566 \begin{key}{/tikz/node quotes mean=\meta{replacement}}
2567 This key allows you to define your own handler for quotes options. Inside
2568 the options of a |node|, whenever a key--value pair with the syntax
2569 %
2570 \begin{quote}
2571 |"|\meta{text}|"|\opt{|'|}\opt{\meta{options}}
2572 \end{quote}
2573 %
2574 is encountered, the following happens: The above string gets replaced by
2575 \meta{replacement} where inside the \meta{replacement} the parameter |#1|
2576 is \meta{text} and |#2| is \meta{options}. If the apostrophe is present
2577 (see also the discussion of |quotes mean label|), the \meta{options} start
2578 with |',|.
2579
2580 The \meta{replacement} is then parsed normally as options (using
2581 |\pgfkeys|).
2582
2583 Here is an example, where the quotes are used to define labels that are
2584 automatically named according to the |text|:
2585 %
2586 \begin{codeexample}[preamble={\usetikzlibrary{quotes}}]
2587 \tikzset{node quotes mean={label={[#2,name={#1}]#1}}}
2588
2589 \tikz {
2590 \node ["1", "2" label position=left, circle, draw] {circle};
2591 \draw (1) -- (2);
2592 }
2593 \end{codeexample}
2594 %
2595 \end{key}
2596
2597 Some further options provided by the |quotes| library concern labels next to
2598 edges rather than nodes and they are described in
2599 Section~\ref{section-edge-quotes}.
2600
2601
2602 \subsection{Connecting Nodes: Using Nodes as Coordinates}
2603 \label{section-nodes-connecting}
2604
2605 Once you have defined a node and given it a name, you can use this name to
2606 reference it. This can be done in two ways, see also
2607 Section~\ref{section-node-coordinates}. Suppose you have said
2608 |\path(0,0) node(x) {Hello World!};| in order to define a node named |x|.
2609 %
2610 \begin{enumerate}
2611 \item Once the node |x| has been defined, you can use |(x.|\meta{anchor}|)|
2612 wherever you would normally use a normal coordinate. This will yield
2613 the position at which the given \meta{anchor} is in the picture. Note
2614 that transformations do not apply to this coordinate, that is,
2615 |(x.north)| will be the northern anchor of |x| even if you have said
2616 |scale=3| or |xshift=4cm|. This is usually what you would expect.
2617 \item You can also just use |(x)| as a coordinate. In most cases, this
2618 gives the same coordinate as |(x.center)|. Indeed, if the |shape| of
2619 |x| is |coordinate|, then |(x)| and |(x.center)| have exactly the same
2620 effect.
2621
2622 However, for most other shapes, some path construction operations like
2623 |--| try to be ``clever'' when they are asked to draw a line from such
2624 a coordinate or to such a coordinate. When you say |(x)--(1,1)|, the
2625 |--| path operation will not draw a line from the center of |x|, but
2626 \emph{from the border} of |x| in the direction going towards |(1,1)|.
2627 Likewise, |(1,1)--(x)| will also have the line end on the border in the
2628 direction coming from |(1,1)|.
2629
2630 If the specified coordinate is almost identical to the node center, for
2631 example |(x)--(0,0)|, no line will be drawn and a warning message will
2632 be printed.
2633
2634 In addition to |--|, the curve-to path operation |..| and the path
2635 operations \verb!-|! and \verb!|-! will also handle nodes without
2636 anchors correctly. Here is an example, see also
2637 Section~\ref{section-node-coordinates}:
2638 %
2639 \begin{codeexample}[]
2640 \begin{tikzpicture}
2641 \path (0,0) node (x) {Hello World!}
2642 (3,1) node[circle,draw](y) {$\int_1^2 x \mathrm d x$};
2643
2644 \draw[->,blue] (x) -- (y);
2645 \draw[->,red] (x) -| node[near start,below] {label} (y);
2646 \draw[->,orange] (x) .. controls +(up:1cm) and +(left:1cm) .. node[above,sloped] {label} (y);
2647 \end{tikzpicture}
2648 \end{codeexample}
2649 %
2650 \end{enumerate}
2651
2652
2653 \subsection{Connecting Nodes: Using the Edge Operation}
2654 \label{section-nodes-edges}
2655
2656 \subsubsection{Basic Syntax of the Edge Operation}
2657
2658 The |edge| operation works like a |to| operation that is added after the main
2659 path has been drawn, much like a node is added after the main path has been
2660 drawn. This allows each |edge| to have a different appearance. As the |node|
2661 operation, an |edge| temporarily suspends the construction of the current path
2662 and a new path $p$ is constructed. This new path $p$ will be drawn after the
2663 main path has been drawn. Note that $p$ can be totally different from the main
2664 path with respect to its options. Also note that if there are several |edge|
2665 and/or |node| operations in the main path, each creates its own path(s) and
2666 they are drawn in the order that they are encountered on the main path.
2667
2668 \begin{pathoperation}{edge}{\opt{|[|\meta{options}|]|} \opt{\meta{nodes}} |(|\meta{coordinate}|)|}
2669 The effect of the |edge| operation is that after the main path the
2670 following path is added to the picture:
2671 %
2672 \begin{quote}
2673 |\path[every edge,|\meta{options}|] (\tikztostart) |\meta{path}|;|
2674 \end{quote}
2675 %
2676 Here, \meta{path} is the |to path|. Note that, unlike the path added by the
2677 |to| operation, the |(\tikztostart)| is added before the \meta{path} (which
2678 is unnecessary for the |to| operation, since this coordinate is already
2679 part of the main path).
2680
2681 The |\tikztostart| is the last coordinate on the path just before the
2682 |edge| operation, just as for the |node| or |to| operations. However, there
2683 is one exception to this rule: If the |edge| operation is directly preceded
2684 by a |node| operation, then this just-declared node is the start coordinate
2685 (and not, as would normally be the case, the coordinate where this
2686 just-declared node is placed -- a small, but subtle difference). In this
2687 regard, |edge| differs from both |node| and |to|.
2688
2689 If there are several |edge| operations in a row, the start coordinate is
2690 the same for all of them as their target coordinates are not, after all,
2691 part of the main path. The start coordinate is, thus, the coordinate
2692 preceding the first |edge| operation. This is similar to nodes insofar as
2693 the |edge| operation does not modify the current path at all. In
2694 particular, it does not change the last coordinate visited, see the
2695 following example:
2696 %
2697 \begin{codeexample}[]
2698 \begin{tikzpicture}
2699 \node (a) at (0:1) {$a$};
2700 \node (b) at (90:1) {$b$} edge [->] (a);
2701 \node (c) at (180:1) {$c$} edge [->] (a)
2702 edge [<-] (b);
2703 \node (d) at (270:1) {$d$} edge [->] (a)
2704 edge [dotted] (b)
2705 edge [<-] (c);
2706 \end{tikzpicture}
2707 \end{codeexample}
2708
2709 A different way of specifying the above graph using the |edge| operation is
2710 the following:
2711 %
2712 \begin{codeexample}[]
2713 \begin{tikzpicture}
2714 \node foreach \name/\angle in {a/0,b/90,c/180,d/270}
2715 (\name) at (\angle:1) {$\name$};
2716
2717 \path[->] (b) edge (a)
2718 edge (c)
2719 edge [-,dotted] (d)
2720 (c) edge (a)
2721 edge (d)
2722 (d) edge (a);
2723 \end{tikzpicture}
2724 \end{codeexample}
2725
2726 As can be seen, the path of the |edge| operation inherits the options from
2727 the main path, but you can locally overrule them.
2728 %
2729 \begin{codeexample}[]
2730 \begin{tikzpicture}
2731 \node foreach \name/\angle in {a/0,b/90,c/180,d/270}
2732 (\name) at (\angle:1.5) {$\name$};
2733
2734 \path[->] (b) edge node[above right] {$5$} (a)
2735 edge (c)
2736 edge [-,dotted] node[below,sloped] {missing} (d)
2737 (c) edge (a)
2738 edge (d)
2739 (d) edge [red] node[above,sloped] {very}
2740 node[below,sloped] {bad} (a);
2741 \end{tikzpicture}
2742 \end{codeexample}
2743
2744 Instead of |every to|, the style |every edge| is installed at the beginning
2745 of the main path.
2746 %
2747 \begin{stylekey}{/tikz/every edge (initially draw)}
2748 Executed for each |edge|.
2749 %
2750 \begin{codeexample}[]
2751 \begin{tikzpicture}[every edge/.style={draw,dashed}]
2752 \path (0,0) edge (3,2);
2753 \end{tikzpicture}
2754 \end{codeexample}
2755 \end{stylekey}
2756 \end{pathoperation}
2757
2758
2759 \subsubsection{Nodes on Edges: Quotes Syntax}
2760 \label{section-edge-quotes}
2761
2762 The standard way of specifying nodes that are placed ``on'' an edge (or on a
2763 to-path; all of the following is also true for to--paths) is to put node
2764 specifications after the |edge| keyword, but before the target coordinate.
2765 Another way is to use the |edge node| option and its friends. Yet another way
2766 is to use the quotes syntax.
2767
2768 The syntax is essentially the same as for labels added to nodes as described in
2769 Section~\ref{section-label-quotes} and you also need to load the |quotes|
2770 library.
2771
2772 In detail, when the |quotes| library is loaded, each time a key--value pair in
2773 a list of options passed to an |edge| or a |to| path command starts with |"|,
2774 the key--value pair must actually be a string of the following form:
2775 %
2776 \begin{quote}
2777 |"|\meta{text}|"|\opt{|'|}\opt{\meta{options}}
2778 \end{quote}
2779 %
2780 This string is transformed into the following:
2781 %
2782 \begin{quote}
2783 |edge node=node [every edge quotes,|\meta{options}|]{|\meta{text}|}|
2784 \end{quote}
2785 %
2786 As described in Section~\ref{section-label-quotes}, the apostrophe becomes part
2787 of the \meta{options}, when present.
2788
2789 The following style is important for the placement of the labels:
2790
2791 \begin{stylekey}{/tikz/every edge quotes (initially auto)}
2792 This style is |auto| by default, which causes labels specified using the
2793 quotes-syntax to be placed next to the edges. Unless the setting of |auto|
2794 has been changed, they will be placed to the left.
2795 %
2796 \begin{codeexample}[preamble={\usetikzlibrary{quotes}}]
2797 \tikz \draw (0,0) edge ["left", ->] (2,0);
2798 \end{codeexample}
2799
2800 In order to place all labels to the right by default, change this style to
2801 |auto=right|:
2802 %
2803 \begin{codeexample}[preamble={\usetikzlibrary{quotes}}]
2804 \tikz [every edge quotes/.style={auto=right}]
2805 \draw (0,0) edge ["right", ->] (2,0);
2806 \end{codeexample}
2807
2808 To place all nodes ``on'' the edge, just make this style empty (and,
2809 possibly, make your labels opaque):
2810 %
2811 \begin{codeexample}[preamble={\usetikzlibrary{quotes}}]
2812 \tikz [every edge quotes/.style={fill=white,font=\footnotesize}]
2813 \draw (0,0) edge ["mid", ->] (2,1);
2814 \end{codeexample}
2815 %
2816 \end{stylekey}
2817
2818 You may often wish to place some edge nodes to the right of edges and some to
2819 the left. For this, the special treatment of the apostrophe is particularly
2820 convenient: Recall that in \tikzname\ there is an option just called |'|, which
2821 is a shorthand for |swap|. Now, following the closing quotation mark come the
2822 options of an edge node. Thus, if the closing quotation mark is followed by an
2823 apostrophe, the |swap| option will be added to the edge label, causing it is be
2824 placed on the other side. Because of the special treatment, you can even add
2825 another option like |near end| after the apostrophe without having to add curly
2826 braces and commas:
2827 %
2828 \begin{codeexample}[preamble={\usetikzlibrary{quotes}}]
2829 \tikz
2830 \draw (0,0) edge ["left", "right"',
2831 "start" near start,
2832 "end"' near end] (4,0);
2833 \end{codeexample}
2834
2835 In order to modify the distance between the edge labels and the edge, you
2836 should consider introducing some styles:
2837 %
2838 \begin{codeexample}[preamble={\usetikzlibrary{quotes}}]
2839 \tikz [tight/.style={inner sep=1pt}, loose/.style={inner sep=.7em}]
2840 \draw (0,0) edge ["left" tight,
2841 "right"' loose,
2842 "start" near start] (4,0);
2843 \end{codeexample}
2844
2845
2846 \subsection{Referencing Nodes Outside the Current Picture}
2847 \label{section-cross-picture-tikz}
2848
2849 \subsubsection{Referencing a Node in a Different Picture}
2850
2851 It is possible (but not quite trivial) to reference nodes in pictures other
2852 than the current one. This means that you can create a picture and a node
2853 therein and, later, you can draw a line from some other position to this node.
2854
2855 To reference nodes in different pictures, proceed as follows:
2856 %
2857 \begin{enumerate}
2858 \item You need to add the |remember picture| option to all pictures that
2859 contain nodes that you wish to reference and also to all pictures from
2860 which you wish to reference a node in another picture.
2861 \item You need to add the |overlay| option to paths or to whole pictures
2862 that contain references to nodes in different pictures. (This option
2863 switches the computation of the bounding box off.)
2864 \item You need to use a driver that supports picture remembering and you
2865 need to run \TeX\ twice.
2866 \end{enumerate}
2867 %
2868 (For more details on what is going on behind the scenes, see
2869 Section~\ref{section-cross-pictures-pgf}.)
2870
2871 Let us have a look at the effect of these options.
2872 %
2873 \begin{key}{/tikz/remember picture=\meta{boolean} (initially false)}
2874 This option tells \tikzname\ that it should attempt to remember the
2875 position of the current picture on the page. This attempt may fail
2876 depending on which backend driver is used. Also, even if remembering works,
2877 the position may only be available on a second run of \TeX.
2878
2879 Provided that remembering works, you may consider saying
2880 %
2881 \begin{codeexample}[code only]
2882 \tikzset{every picture/.append style={remember picture}}
2883 \end{codeexample}
2884 %
2885 to make \tikzname\ remember all pictures. This will add one line in the
2886 |.aux| file for each picture in your document -- which typically is not
2887 very much. Then, you do not have to worry about remembered pictures at all.
2888 \end{key}
2889
2890 \begin{key}{/tikz/overlay=\meta{boolean} (default true)}
2891 This option is mainly intended for use when nodes in other pictures are
2892 referenced, but you can also use it in other situations. The effect of this
2893 option is that everything within the current scope is not taken into
2894 consideration when the bounding box of the current picture is computed.
2895
2896 You need to specify this option on all paths (or at least on all parts of
2897 paths) that contain a reference to a node in another picture. The reason is
2898 that, otherwise, \tikzname\ will attempt to make the current picture large
2899 enough to encompass \emph{the node in the other picture}. However, on a
2900 second run of \TeX\ this will create an even bigger picture, leading to
2901 larger and larger pictures. Unless you know what you are doing, I suggest
2902 specifying the |overlay| option with all pictures that contain references
2903 to other pictures.
2904 \end{key}
2905
2906 Let us now have a look at a few examples. These examples work only if this
2907 document is processed with a driver that supports picture remembering.
2908 \medskip
2909
2910 \noindent%
2911 \begin{minipage}{\textwidth}
2912 Inside the current text we place two pictures, containing nodes named |n1| and
2913 |n2|, using
2914 %
2915 \begin{codeexample}[code only]
2916 \tikz[remember picture] \node[circle,fill=red!50] (n1) {};
2917 \end{codeexample}
2918 %
2919 which yields \tikz[remember picture] \node[circle,fill=red!50] (n1) {};, and
2920 %
2921 \begin{codeexample}[code only]
2922 \tikz[remember picture] \node[fill=blue!50] (n2) {};
2923 \end{codeexample}
2924 %
2925 yielding the node \tikz[remember picture] \node[fill=blue!50] (n2) {};. To
2926 connect these nodes, we create another picture using the |overlay| option and
2927 also the |remember picture| option.
2928 %
2929 \begin{codeexample}[]
2930 \begin{tikzpicture}[remember picture,overlay]
2931 \draw[->,very thick] (n1) -- (n2);
2932 \end{tikzpicture}
2933 \end{codeexample}
2934 %
2935 Note that the last picture is seemingly empty. What happens is that it has zero
2936 size and contains an arrow that lies well outside its bounds. As a last
2937 example, we connect a node in another picture to the first two nodes. Here, we
2938 provide the |overlay| option only with the line that we do not wish to count as
2939 part of the picture.
2940 %
2941 \begin{codeexample}[]
2942 \begin{tikzpicture}[remember picture]
2943 \node (c) [circle,draw] {Big circle};
2944
2945 \draw [overlay,->,very thick,red,opacity=.5]
2946 (c) to[bend left] (n1) (n1) -| (n2);
2947 \end{tikzpicture}
2948 \end{codeexample}
2949 \end{minipage}
2950
2951
2952 \subsubsection{Referencing the Current Page Node -- Absolute Positioning}
2953
2954 There is a special node called |current page| that can be used to access the
2955 current page. It is a node of shape rectangle whose |south west| anchor is the
2956 lower left corner of the page and whose |north east| anchor is the upper right
2957 corner of the page. While this node is handled in a special way internally, you
2958 can reference it as if it were defined in some remembered picture other than
2959 the current one. Thus, by giving the |remember picture| and the |overlay|
2960 options to a picture, you can position nodes \emph{absolutely} on a page.
2961
2962 The first example places some text in the lower left corner of the current
2963 page:
2964 %
2965 \begin{codeexample}[]
2966 \begin{tikzpicture}[remember picture,overlay]
2967 \node [xshift=1cm,yshift=1cm] at (current page.south west)
2968 [text width=7cm,fill=red!20,rounded corners,above right]
2969 {
2970 This is an absolutely positioned text in the
2971 lower left corner. No shipout-hackery is used.
2972 };
2973 \end{tikzpicture}
2974 \end{codeexample}
2975
2976 The next example adds a circle in the middle of the page.
2977 %
2978 \begin{codeexample}[]
2979 \begin{tikzpicture}[remember picture,overlay]
2980 \draw [line width=1mm,opacity=.25]
2981 (current page.center) circle (3cm);
2982 \end{tikzpicture}
2983 \end{codeexample}
2984
2985 The final example overlays some text over the page (depending on where this
2986 example is found on the page, the text may also be behind the page).
2987 %
2988 \begin{codeexample}[]
2989 \begin{tikzpicture}[remember picture,overlay]
2990 \node [rotate=60,scale=10,text opacity=0.2]
2991 at (current page.center) {Example};
2992 \end{tikzpicture}
2993 \end{codeexample}
2994
2995
2996 \subsection{Late Code and Late Options}
2997 \label{section-node-also}
2998
2999 All options given to a node only locally affect this one node. While this is a
3000 blessing in most cases, you may sometimes want to cause options to have effects
3001 ``later'' on. The other way round, you may sometimes note ``only later'' that
3002 some options should be added to the options of a node. For this, the following
3003 version of the |node| path command can be used:
3004
3005 \begin{pathoperation}{node also}{\opt{|[|\meta{late options}|]|}|(|\meta{name}|)|}
3006 Note that the \meta{name} is compulsory and that \emph{no} text may be
3007 given. Also, the ordering of options and node label must be as above.
3008
3009 The effect of the above is the following effect: The node \meta{name} must
3010 already be existing. Now, the \meta{late options} are executed in a local
3011 scope. Most of these options will have no effect since you \emph{cannot
3012 change the appearance of the node,} that is, you cannot change a red node
3013 into a green node using these ``late'' options. However, giving the
3014 |append after command| and |prefix after command| options inside the
3015 \meta{late options} (directly or indirectly) does have the desired effect:
3016 The given path gets executed with the |\tikzlastnode| set to the determined
3017 node.
3018
3019 The net effect of all this is that you can provide, say, the |label| option
3020 inside the \meta{options} to a add a label to a node that has already been
3021 constructed.
3022 %
3023 \begin{codeexample}[]
3024 \begin{tikzpicture}
3025 \node [draw,circle] (a) {Hello};
3026 \node also [label=above:world] (a);
3027 \end{tikzpicture}
3028 \end{codeexample}
3029 %
3030 \end{pathoperation}
3031
3032 As explained in Section~\ref{section-paths}, you can use the options
3033 |append after command| and |prefix after command| to add a path after a node.
3034 The following macro may be useful there:
3035 %
3036 \begin{command}{\tikzlastnode}
3037 Expands to the last node on the path.
3038 \end{command}
3039
3040 Instead of the |node also| syntax, you can also use the following option:
3041
3042 \begin{key}{/tikz/late options=\meta{options}}
3043 This option can be given on a path (but not as an argument to a |node| path
3044 command) and has the same effect as the |node also| path command. Inside
3045 the \meta{options}, you should use the |name| option to specify the node
3046 for which you wish to add late options:
3047 %
3048 \begin{codeexample}[]
3049 \begin{tikzpicture}
3050 \node [draw,circle] (a) {Hello};
3051 \path [late options={name=a, label=above:world}];
3052 \end{tikzpicture}
3053 \end{codeexample}
3054 %
3055 \end{key}
3056
3057
3058 %%% Local Variables:
3059 %%% mode: latex
3060 %%% TeX-master: "pgfmanual"
3061 %%% End: