Debian Codegraph @

texmf-dist/doc/generic/pgf/pgfmanual-en-base-nodes.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 Shapes}
12
13 \label{section-shapes}
14
15 This section describes the |shapes| module.
16
17 \begin{pgfmodule}{shapes}
18 This module defines commands both for creating nodes and for creating
19 shapes. The package is loaded automatically by |pgf|, but you can load it
20 manually if you have only included |pgfcore|.
21 \end{pgfmodule}
22
23
24 \subsection{Overview}
25
26 \pgfname\ comes with a sophisticated set of commands for creating \emph{nodes}
27 and \emph{shapes}. A \emph{node} is a graphical object that consists
28 (typically) of (one or more) text labels and some additional stroked or filled
29 paths. Each node has a certain \emph{shape}, which may be something simple like
30 a |rectangle| or a |circle|, but it may also be something complicated like a
31 |uml class diagram| (this shape is currently not implemented, though).
32 Different nodes that have the same shape may look quite different, however,
33 since shapes (need not) specify whether the shape path is stroked or filled.
34
35
36 \subsubsection{Creating and Referencing Nodes}
37
38 You create a node by calling the macro |\pgfnode| or the more general
39 |\pgfmultipartnode|. This macro takes several parameters and draws the
40 requested shape at a certain position. In addition, it will ``remember'' the
41 node's position within the current |{pgfpicture}|. You can then, later on,
42 refer to the node's position. Coordinate transformations are ``fully
43 supported'', which means that if you used coordinate transformations to shift
44 or rotate the shape of a node, the node's position will still be correctly
45 determined by \pgfname. This is \emph{not} the case if you use canvas
46 transformations instead.
47
48
49 \subsubsection{Anchors}
50
51 An important property of a node or a shape in general are its \emph{anchors}.
52 Anchors are ``important'' positions in a shape. For example, the |center|
53 anchor lies at the center of a shape, the |north| anchor is usually ``at the
54 top, in the middle'' of a shape, the |text| anchor is the lower left corner of
55 the shape's text label (if present), and so on.
56
57 Anchors are important both when you create a node and when you reference it.
58 When you create a node, you specify the node's ``position'' by asking \pgfname\
59 to place the shape in such a way that a certain anchor lies at a certain point.
60 For example, you might ask that the node is placed such that the |north| anchor
61 is at the origin. This will effectively cause the node to be placed below the
62 origin.
63
64 When you reference a node, you always reference an anchor of the node. For
65 example, when you request the ``|north| anchor of the node just placed'' you
66 will get the origin. However, you can also request the ``|south| anchor of this
67 node'', which will give you a point somewhere below the origin. When a
68 coordinate transformation was in force at the time of creation of a node, all
69 anchors are also transformed accordingly.
70
71
72 \subsubsection{Layers of a Shape}
73
74 The simplest shape, the |coordinate|, has just one anchor, namely the |center|,
75 and a label (which is usually empty). More complicated shapes like the
76 |rectangle| shape also have a \emph{background path}. This is a \pgfname-path
77 that is defined by the shape. The shape does not prescribe what should happen
78 with the path: When a node is created, this path may be stroked (resulting in a
79 frame around the label), filled (resulting in a background color for the text),
80 or just discarded.
81
82 Although most shapes consist just of a background path plus some label text,
83 when a shape is drawn, up to seven different layers are drawn:
84 %
85 \begin{enumerate}
86 \item The ``behind the background layer''. Unlike the background path,
87 which can be used in different ways by different nodes, the graphic
88 commands given for this layer will always stroke or always fill the
89 path they construct. They might also insert some text that is ``behind
90 everything''.
91 \item The background path layer. How this path is used depends on the
92 arguments of the |\pgfnode| command.
93 \item The ``before the background path layer''. This layer works like the
94 first one, only the commands of this layer are executed after the
95 background path has been used (in whatever way the creator of the node
96 chose).
97 \item The label layer. This layer inserts the node's text box(es).
98 \item The ``behind the foreground layer''. This layer, like the first
99 layer, once more contains graphic commands that are ``simply
100 executed''.
101 \item The foreground path layer. This path is treated in the same way as
102 the background path, only it is drawn after the label text has been
103 drawn.
104 \item The ``before the foreground layer''.
105 \end{enumerate}
106
107 Which of these layers are actually used depends on the shape.
108
109
110 \subsubsection{Node Parts}
111
112 A shape typically does not consist only of different background and foreground
113 paths, but it may also have text labels. Indeed, for many shapes the text
114 labels are the more important part of the shape.
115
116 Most shapes will have only one text label. In this case, this text label is
117 simply passed as a parameter to the |\pgfnode| command. When the node is drawn,
118 the text label is shifted around such that its lower left corner is at the
119 |text| anchor of the node.
120
121 More complicated shapes may have more than one text label. Nodes of such shapes
122 are called \emph{multipart nodes}. The different \emph{node parts} are simply
123 the different text labels. For example, a |uml class| shape might have a
124 |class name| part, a |method| part and an |attributes| part. Indeed, single
125 part nodes are a special case of multipart nodes: They only have one part named
126 |text|.
127
128 When a shape is declared, you must specify the node parts. There is a simple
129 command called |\nodeparts| that takes a list of the part names as input. When
130 you create a node of a multipart shape, for each part of the node you must have
131 set up a \TeX-box containing the text of the part. For a part named |XYZ| you
132 must set up the box |\pgfnodepartXYZbox|. The box will be placed at the anchor
133 |XYZ|. See the description of |\pgfmultipartnode| for more details.
134
135
136 \subsection{Creating Nodes}
137
138 \subsubsection{Creating Simple Nodes}
139
140 \begin{command}{\pgfnode\marg{shape}\marg{anchor}\marg{label text}\marg{name}\marg{path usage command}}
141 This command creates a new node. The \meta{shape} of the node must have
142 been declared previously using |\pgfdeclareshape|.
143
144 The shape is shifted such that the \meta{anchor} is at the origin. In order
145 to place the shape somewhere else, use the coordinate transformation prior
146 to calling this command.
147
148 The \meta{name} is a name for later reference. If no name is given, nothing
149 will be ``saved'' for the node, it will just be drawn.
150
151 The \meta{path usage command} is executed for the background and the
152 foreground path (if the shape defines them).
153 %
154 \begin{codeexample}[]
155 \begin{tikzpicture}
156 \draw[help lines] (0,0) grid (4,3);
157 {
158 \pgftransformshift{\pgfpoint{1.5cm}{1cm}}
159 \pgfnode{rectangle}{north}{Hello World}{hellonode}{\pgfusepath{stroke}}
160 }
161 {
162 \color{red!20}
163 \pgftransformrotate{10}
164 \pgftransformshift{\pgfpoint{3cm}{1cm}}
165 \pgfnode{rectangle}{center}
166 {\color{black}Hello World}{hellonode}{\pgfusepath{fill}}
167 }
168 \end{tikzpicture}
169 \end{codeexample}
170
171 As can be seen, all coordinate transformations are also applied to the text
172 of the shape. Sometimes, it is desirable that the transformations are
173 applied to the point where the shape will be anchored, but you do not wish
174 the shape itself to be transformed. In this case, you should call
175 |\pgftransformresetnontranslations| prior to calling the |\pgfnode|
176 command.
177 %
178 \begin{codeexample}[]
179 \begin{tikzpicture}
180 \draw[help lines] (0,0) grid (4,3);
181 {
182 \color{red!20}
183 \pgftransformrotate{10}
184 \pgftransformshift{\pgfpoint{3cm}{1cm}}
185 \pgftransformresetnontranslations
186 \pgfnode{rectangle}{center}
187 {\color{black}Hello World}{hellonode}{\pgfusepath{fill}}
188 }
189 \end{tikzpicture}
190 \end{codeexample}
191
192 The \meta{label text} is typeset inside the \TeX-box |\pgfnodeparttextbox|.
193 This box is shown at the |text| anchor of the node, if the node has a
194 |text| part. See the description of |\pgfmultipartnode| for details.
195 \end{command}
196
197
198 \subsubsection{Creating Multi-Part Nodes}
199
200 \begin{command}{\pgfmultipartnode\marg{shape}\marg{anchor}\marg{name}\marg{path usage command}}
201 This command is the more general (and less user-friendly) version of the
202 |\pgfnode| command. While the |\pgfnode| command can only be used for
203 shapes that have a single part (which is the case for most shapes), this
204 command can also be used with multi-part nodes.
205
206 When this command is called, for each node part of the node you must have
207 set up one \TeX-box. Suppose the shape has two parts: The |text| part and
208 the |lower| part. Then, prior to calling |\pgfmultipartnode|, you must have
209 set up the boxes |\pgfnodeparttextbox| and |\pgfnodepartlowerbox|. These
210 boxes may contain any \TeX-text. The shape code will then compute the
211 positions of the shape's anchors based on the sizes of the these shapes.
212 Finally, when the node is drawn, the boxes are placed at the anchor
213 positions |text| and |lower|.
214 %
215 \begin{codeexample}[preamble={\usetikzlibrary{shapes}}]
216 \setbox\pgfnodeparttextbox=\hbox{$q_1$}
217 \setbox\pgfnodepartlowerbox=\hbox{01}
218 \begin{pgfpicture}
219 \pgfmultipartnode{circle split}{center}{my state}{\pgfusepath{stroke}}
220 \end{pgfpicture}
221 \end{codeexample}
222
223 \emph{Note:} Be careful when using the |\setbox| command inside a
224 |{pgfpicture}| command. You will have to use |\pgfinterruptpath| at the
225 beginning of the box and |\endpgfinterruptpath| at the end of the box to
226 make sure that the box is typeset correctly. In the above example this
227 problem was sidestepped by moving the box construction outside the
228 environment.
229
230 \emph{Note:} It is not necessary to use |\newbox| for every node part
231 name. Although you need a different box for each part of a single shape,
232 two different shapes may very well use the same box even when the names of
233 the parts are different. Suppose you have a |circle split| shape that has a
234 |lower| part and you have a |uml class| shape that has a |methods| part.
235 Then, in order to avoid exhausting \TeX's limited number of box registers,
236 you can say
237 %
238 \begin{codeexample}[code only]
239 \newbox\pgfnodepartlowerbox
240 \let\pgfnodepartmethodsbox=\pgfnodepartlowerbox
241 \end{codeexample}
242 %
243 Also, when you have a node part name with spaces like |class name|, it may
244 be useful to create an alias:
245 %
246 \begin{codeexample}[code only]
247 \newbox\mybox
248 \expandafter\let\csname pgfnodepartclass namebox\endcsname=\mybox
249 \end{codeexample}
250 %
251 \end{command}
252
253 \begin{command}{\pgfcoordinate\marg{name}\marg{coordinate}}
254 This command creates a node of shape |coordinate| at the given
255 \meta{coordinate}. Exactly the same effect can be achieved using first a
256 shift of the coordinate system to \meta{coordinate}, followed by creating a
257 node of shape |coordinate| named \meta{name}. However, this command is
258 easier and more natural to use and, more importantly, it is much faster.
259 \end{command}
260
261 \begin{command}{\pgfnodealias\marg{new name}\marg{existing node}}
262 This command does not actually create a new node. Rather, it allows you to
263 subsequently access the node \meta{existing node} using the name \meta{new
264 name}.
265 \end{command}
266
267 \begin{command}{\pgfnoderename\marg{new name}\marg{existing node}}
268 This command renames an existing node.
269 \end{command}
270
271 There are a number of values that have an influence on the size of a node.
272 These values are stored in the following keys.
273
274 \begin{key}{/pgf/minimum width=\meta{dimension} (initially 1pt)}
275 \keyalias{tikz}
276 This key stores the \emph{recommended} minimum width of a shape. Thus, when
277 a shape is drawn and when the shape's width would be smaller than
278 \meta{dimension}, the shape's width is enlarged by adding some empty space.
279
280 Note that this value is just a recommendation. A shape may choose to ignore
281 this key.
282 %
283 \begin{codeexample}[]
284 \begin{tikzpicture}
285 \draw[help lines] (-2,0) grid (2,1);
286
287 \pgfset{minimum width=3cm}
288 \pgfnode{rectangle}{center}{Hello World}{}{\pgfusepath{stroke}}
289 \end{tikzpicture}
290 \end{codeexample}
291 %
292 \end{key}
293
294 \begin{key}{/pgf/minimum height=\meta{dimension} (initially 1pt)}
295 \keyalias{tikz}
296 Works like |/pgf/minimum width|.
297 \end{key}
298
299 \begin{key}{/pgf/minimum size=\meta{dimension}}
300 \keyalias{tikz}
301 This style both |/pgf/minimum width| and |/pgf/minimum height| to \meta{dimension}.
302 \end{key}
303
304 \begin{key}{/pgf/inner xsep=\meta{dimension} (initially 0.3333em)}
305 \keyalias{tikz}
306 This key stores the \emph{recommended} horizontal inner separation between
307 the label text and the background path. As before, this value is just a
308 recommendation and a shape may choose to ignore this key.
309 %
310 \begin{codeexample}[]
311 \begin{tikzpicture}
312 \draw[help lines] (-2,0) grid (2,1);
313
314 \pgfset{inner xsep=1cm}
315 \pgfnode{rectangle}{center}{Hello World}{}{\pgfusepath{stroke}}
316 \end{tikzpicture}
317 \end{codeexample}
318 %
319 \end{key}
320
321 \begin{key}{/pgf/inner ysep=\meta{dimension} (initially 0.3333em)}
322 \keyalias{tikz}
323 Works like |/pgf/inner xsep|.
324 \end{key}
325
326 \begin{key}{/pgf/inner sep=\meta{dimension}}
327 \keyalias{tikz}
328 This style sets both |/pgf/inner xsep| and |/pgf/inner ysep| to
329 \meta{dimension}.
330 \end{key}
331
332 \begin{key}{/pgf/outer xsep=\meta{dimension} (initially .5\string\pgflinewidth)}
333 \keyalias{tikz}
334 This key stores the recommended horizontal separation between the
335 background path and the ``outer anchors''. For example, if \meta{dimension}
336 is |1cm| then the |east| anchor will be 1cm to the right of the right
337 border of the background path. As before, this value is just a
338 recommendation.
339 %
340 \begin{codeexample}[]
341 \begin{tikzpicture}
342 \draw[help lines] (-2,0) grid (2,1);
343
344 \pgfset{outer xsep=.5cm}
345 \pgfnode{rectangle}{center}{Hello World}{x}{\pgfusepath{stroke}}
346
347 \pgfpathcircle{\pgfpointanchor{x}{north}}{2pt}
348 \pgfpathcircle{\pgfpointanchor{x}{south}}{2pt}
349 \pgfpathcircle{\pgfpointanchor{x}{east}}{2pt}
350 \pgfpathcircle{\pgfpointanchor{x}{west}}{2pt}
351 \pgfpathcircle{\pgfpointanchor{x}{north east}}{2pt}
352 \pgfusepath{fill}
353 \end{tikzpicture}
354 \end{codeexample}
355 %
356 \end{key}
357
358 \begin{key}{/pgf/outer ysep=\meta{dimension} (initially .5\string\pgflinewidth)}
359 \keyalias{tikz}
360 Works like |/pgf/outer xsep|.
361 \end{key}
362
363 \begin{key}{/pgf/outer sep=\meta{dimension}}
364 \keyalias{tikz}
365 This style sets both |/pgf/outer xsep| and |/pgf/outer ysep| to
366 \meta{dimension}.
367 \end{key}
368
369
370 \subsubsection{Deferred Node Positioning}
371 \label{section-shapes-deferred-node-positioning}
372
373 Normally, when a node is created using a command like |\pgfnode|, the node is
374 immediately inserted into the current picture. In particular, you have no
375 chance to change the position of a created node after it has been created.
376 Using |\pgfpositionnodelater| in concert with |\pgfpositionnodenow|, you can
377 create a node whose position is determined only at some later time.
378
379 \begin{command}{\pgfpositionnodelater\marg{macro name}}
380 This command is not a replacement for |\pgfnode|. Rather, when this command
381 is used in a scope, all subsequent node creations in this scope will be
382 affected in the following way: When a node is created, it is not inserted
383 into the current picture. Instead, it is stored in the box
384 |\pgfpositionnodelaterbox|. Furthermore, the node is not relevant for the
385 picture's bounding box, but a bounding box for the node is computed and
386 stored in the macros |\pgfpositionnodelaterminx| to
387 |\pgfpositionnodelatermaxy|. Then, the \meta{macro name} is called with the
388 following macros set up:
389
390 \begin{command}{\pgfpositionnodelaterbox}
391 A box register number (|0| currently) that stores the node's paths and
392 texts. You should move the contents of this box to a box of your choice
393 inside \meta{macro name}.
394 \end{command}
395
396 \begin{command}{\pgfpositionnodelatername}
397 The name of the just-created-node. This name will be the originally
398 ``desired'' name of the box plus the fixed prefix
399 |not yet positionedPGFINTERNAL|. The idea is to ensure that the
400 original name is not inadvertently used before the node is actually
401 positioned. When |\pgfpositionnodenow| is called, it will change the
402 name to the
403 original name.
404 \end{command}
405
406 \begin{command}{\pgfpositionnodelaterminx}
407 The minimal $x$-position of a bounding box of the node. This bounding
408 box refers to the node when it is positioned with the anchor at the
409 origin. It is guaranteed, that this macro will contain a dimension in
410 the format \meta{number}|pt|.
411 \end{command}
412 %
413 \begin{command}{\pgfpositionnodelaterminy}
414 \end{command}
415 %
416 \begin{command}{\pgfpositionnodelatermaxx}
417 \end{command}
418 %
419 \begin{command}{\pgfpositionnodelatermaxy}
420 \end{command}
421
422 Once a late node has been created, you can add arbitrary code in the same
423 picture. Then, at some later point, you call |\pgfpositionnodenow| to
424 finally position the node at a given position. At this point, the above
425 macros must have the exact same values they had when \meta{macro name} was
426 called. Note that the above macros are local to a scope that ends right
427 after the call to \meta{macro name}, so it is your job to copy the values
428 to safety inside \meta{macro name}.
429
430 The following two macros will also be set inside the call to \meta{macro
431 name}, but they are only ``informative'' in the sense that you need
432 \emph{not} restore these macros when |\pgfpositionnodenow| is called.
433
434 \begin{command}{\pgfpositionnodelaterpath}
435 This macro stores the path of the background of the node. See
436 Section~\ref{section-soft-paths} for an overview of how these paths are
437 encode.
438 \end{command}
439
440 By setting \meta{macro name} to |\relax| (which is the default), you can
441 switch off the whole mechanism. When a picture is interrupted, this is done
442 automatically.
443 \end{command}
444
445 \begin{command}{\pgfpositionnodenow\marg{coordinate}}
446 This command is used to position a node that has previously been created
447 using the command |\pgfpositionnodelater|. When |\pgfpositionnodenow| is
448 called, the macros and boxes mentioned in the description of
449 |\pgfpositionnodenow| must be set to the value they had when the
450 \meta{macro name} was called. Provided this is the case, this command will
451 insert the box into the current picture, shifted by \meta{coordinate}.
452 Then, the late code (see below) is called. Subsequently, you can refer to
453 the node with its original name as if it had just been created.
454 %
455 \begin{codeexample}[]
456 \newbox\mybox
457
458 \def\mysaver{
459 \global\setbox\mybox=\box\pgfpositionnodelaterbox
460 \global\let\myname=\pgfpositionnodelatername
461 \global\let\myminx=\pgfpositionnodelaterminx
462 \global\let\myminy=\pgfpositionnodelaterminy
463 \global\let\mymaxx=\pgfpositionnodelatermaxx
464 \global\let\mymaxy=\pgfpositionnodelatermaxy
465 }
466
467 \begin{tikzpicture}
468 {
469 \pgfpositionnodelater{\mysaver}
470 \node [fill=blue!20,below,rotate=30] (hi) {Hello world};
471 }
472 \draw [help lines] (0,0) grid (3,2);
473
474 \let\pgfpositionnodelatername=\myname
475 \let\pgfpositionnodelaterminx=\myminx
476 \let\pgfpositionnodelaterminy=\myminy
477 \let\pgfpositionnodelatermaxx=\mymaxx
478 \let\pgfpositionnodelatermaxy=\mymaxy
479 \setbox\pgfpositionnodelaterbox=\box\mybox
480 \pgfpositionnodenow{\pgfqpoint{2cm}{2cm}}
481
482 \draw (hi) -- (0,0);
483 \end{tikzpicture}
484 \end{codeexample}
485 %
486 \end{command}
487
488 \begin{command}{\pgfnodepostsetupcode\marg{node name}\marg{code}}
489 When you call this macro inside a scope for which the
490 |\pgfpositionnodelater| has been called, the \meta{code} will be stored
491 internally. Later, when the node named \meta{node name} is actually
492 positioned using |\pgfpositionnodenow|, the \meta{code} will be executed.
493 When this macro is called multiple times with the same \meta{node name},
494 the \meta{code} accumulates. However, When |\pgfpositionnodenow| is called,
495 the code stored for the node is cleared.
496
497 The main purpose of this mechanism is to allow \tikzname\ to store
498 so-called ``late options'' with a node that will be positioned only later.
499 \end{command}
500
501
502 \subsection{Using Anchors}
503
504 Each shape defines a set of anchors. We saw already that the anchors are used
505 when the shape is drawn: the shape is placed in such a way that the given
506 anchor is at the origin (which in turn is typically translated somewhere else).
507
508 One has to look up the set of anchors of each shape, there is no ``default''
509 set of anchors, except for the |center| anchor, which should always be present.
510 Also, most shapes will declare anchors like |north| or |east|, but this is not
511 guaranteed.
512
513
514 \subsubsection{Referencing Anchors of Nodes in the Same Picture}
515
516 Once a node has been defined, you can refer to its anchors using the following
517 commands:
518
519 \begin{command}{\pgfpointanchor\marg{node}\marg{anchor}}
520 This command is another ``point command'' like the commands described in
521 Section~\ref{section-points}. It returns the coordinate of the given
522 \meta{anchor} in the given \meta{node}. The command can be used in commands
523 like |\pgfpathmoveto|.
524 %
525 \begin{codeexample}[]
526 \begin{pgfpicture}
527 \pgftransformrotate{30}
528 \pgfnode{rectangle}{center}{Hello World!}{x}{\pgfusepath{stroke}}
529
530 \pgfpathcircle{\pgfpointanchor{x}{north}}{2pt}
531 \pgfpathcircle{\pgfpointanchor{x}{south}}{2pt}
532 \pgfpathcircle{\pgfpointanchor{x}{east}}{2pt}
533 \pgfpathcircle{\pgfpointanchor{x}{west}}{2pt}
534 \pgfpathcircle{\pgfpointanchor{x}{north east}}{2pt}
535 \pgfusepath{fill}
536 \end{pgfpicture}
537 \end{codeexample}
538
539 In the above example, you may have noticed something curious: The rotation
540 transformation is still in force when the anchors are invoked, but it does
541 not seem to have an effect. You might expect that the rotation should apply
542 to the already rotated points once more.
543
544 However, |\pgfpointanchor| returns a point that takes the current
545 transformation matrix into account: \emph{The inverse transformation to the
546 current coordinate transformation is applied to an anchor point before
547 returning it.}
548
549 This behavior may seem a bit strange, but you will find it very natural in
550 most cases. If you really want to apply a transformation to an anchor point
551 (for example, to ``shift it away'' a little bit), you have to invoke
552 |\pgfpointanchor| without any transformations in force. Here is an example:
553 %
554 \makeatletter
555 \begin{codeexample}[pre={\makeatletter}]
556 \begin{pgfpicture}
557 \pgftransformrotate{30}
558 \pgfnode{rectangle}{center}{Hello World!}{x}{\pgfusepath{stroke}}
559
560 {
561 \pgftransformreset
562 \pgfpointanchor{x}{east}
563 \xdef\mycoordinate{\noexpand\pgfpoint{\the\pgf@x}{\the\pgf@y}}
564 }
565
566 \pgfpathcircle{\mycoordinate}{2pt}
567 \pgfusepath{fill}
568 \end{pgfpicture}
569 \end{codeexample}
570
571 A special situation arises when the \meta{node} lies in a picture different
572 from the current picture. In this case, if you have not told \pgfname\ that
573 the picture should be ``remembered'', the \meta{node} will be treated as if
574 it lay in the current picture. For example, if the \meta{node} was at
575 position $(3,2)$ in the original picture, it is treated as if it lay at
576 position $(3,2)$ in the current picture. However, if you have told
577 \pgfname\ to remember the picture position of the node's picture and also
578 of the current picture, then |\pgfpointanchor| will return a coordinate
579 that corresponds to the position of the node's anchor on the page,
580 transformed into the current coordinate system. For examples and more
581 details see Section~\ref{section-cross-pictures-pgf}.
582 \end{command}
583
584 \begin{command}{\pgfpointshapeborder\marg{node}\marg{point}}
585 This command returns the point on the border of the shape that lies on a
586 straight line from the center of the node to \meta{point}. For complex
587 shapes it is not guaranteed that this point will actually lie on the
588 border, it may be on the border of a ``simplified'' version of the shape.
589 %
590 \begin{codeexample}[]
591 \begin{pgfpicture}
592 \begin{pgfscope}
593 \pgftransformrotate{30}
594 \pgfnode{rectangle}{center}{Hello World!}{x}{\pgfusepath{stroke}}
595 \end{pgfscope}
596 \pgfpathcircle{\pgfpointshapeborder{x}{\pgfpoint{2cm}{1cm}}}{2pt}
597 \pgfpathcircle{\pgfpoint{2cm}{1cm}}{2pt}
598 \pgfpathcircle{\pgfpointshapeborder{x}{\pgfpoint{-1cm}{1cm}}}{2pt}
599 \pgfpathcircle{\pgfpoint{-1cm}{1cm}}{2pt}
600 \pgfusepath{fill}
601 \end{pgfpicture}
602 \end{codeexample}
603 %
604 \emph{Remark:} If the given \meta{point} is almost identical to the center
605 of \meta{node}, the node center is returned and a warning message will be
606 printed.
607 \end{command}
608
609
610 \subsubsection{Referencing Anchors of Nodes in Different Pictures}
611 \label{section-cross-pictures-pgf}
612
613 As a picture is typeset, \pgfname\ keeps track of the positions of all nodes
614 inside the picture. What \pgfname\ does not remember is the position of the
615 picture \emph{itself} on the page. Thus, if you define a node in one picture
616 and then try to reference this node while another picture is typeset, \pgfname\
617 will only know the position of the nodes that you try to typeset inside the
618 original picture, but it will not know where this picture lies. What is missing
619 is the relative positioning of the two pictures.
620
621 To overcome this problem, you need to tell \pgfname\ that it should remember
622 the position of pictures on a page. If these positions are remembered, then
623 \pgfname\ can compute the offset between the pictures and make nodes in
624 different pictures accessible.
625
626 Determining the positions of pictures on the page is, alas, not-so-easy.
627 Because of this, \pgfname\ does not do so automatically. Rather, you have to
628 proceed as follows:
629 %
630 \begin{enumerate}
631 \item You have to use a backend driver that supports position tracking.
632 pdf\TeX\ is one such driver, |dvips| currently is not.
633 \item You have to say |\pgfrememberpicturepositiononpagetrue| somewhere
634 before or inside every picture
635 %
636 \begin{itemize}
637 \item in which you wish to reference a node and
638 \item from which you wish to reference a node in another picture.
639 \end{itemize}
640 %
641 The second item is important since \pgfname\ does not only need to know
642 the position of the picture in which the node you wish to reference
643 lies, but it also needs to know where the current picture lies.
644 \item You typically have to run \TeX\ twice (depending on the backend
645 driver) since the position information typically gets written into an
646 external file on the first run and is available only on the second run.
647 \item You have to switch off automatic bounding bound computations. The
648 reason is that the node in the other picture should not influence the
649 size of the bounding box of the current picture. You should say
650 |\pgfusepath{use as bounding box}| before using a coordinate in another
651 picture.
652 \end{enumerate}
653
654
655 \subsection{Special Nodes}
656
657 There are several special nodes that are always defined and which you should
658 not attempt to redefine.
659
660 \begin{predefinednode}{current bounding box}
661 This node is of shape |rectangle|. Unlike normal nodes, its size changes
662 constantly and always reflects the size of the bounding box of the current
663 picture. This means that, for instance, that
664 %
665 \begin{codeexample}[code only]
666 \pgfpointanchor{current bounding box}{south east}
667 \end{codeexample}
668 %
669 returns the lower left corner of the bounding box of the current picture.
670 \end{predefinednode}
671
672 \begin{predefinednode}{current path bounding box}
673 This node is also of shape |rectangle|. Its size is the size of the
674 bounding box of the current path.
675 \end{predefinednode}
676
677 \begin{predefinednode}{current subpath start}
678 This node is of shape |coordinate| and is at the beginning of the current
679 subpath. This is the position of the last move-to operation.
680 \end{predefinednode}
681
682 \begin{predefinednode}{current page}
683 This node is inside a virtual remembered picture. The size of this node is
684 the size of the current page. This means that if you create a remembered
685 picture and inside this picture you reference an anchor of this node, you
686 reference an absolute position on the page. To demonstrate the effect, the
687 following code puts some text in the lower left corner of the current page.
688 Note that this works only if the backend driver supports it, otherwise the
689 text is inserted right here.
690 %
691 {%
692 \pgfrememberpicturepositiononpagetrue%
693 \begin{pgfpicture}
694 \pgfusepath{use as bounding box}
695 \pgftransformshift{\pgfpointanchor{current page}{south west}}
696 \pgftransformshift{\pgfpoint{1cm}{1cm}}
697 \pgftext[left,base]{
698 \textcolor{red}{
699 Text absolutely positioned in
700 the lower left corner.}
701 }
702 \end{pgfpicture}
703 }%
704 \begin{codeexample}[code only]
705 \pgfrememberpicturepositiononpagetrue
706 \begin{pgfpicture}
707 \pgfusepath{use as bounding box}
708 \pgftransformshift{\pgfpointanchor{current page}{south west}}
709 \pgftransformshift{\pgfpoint{1cm}{1cm}}
710 \pgftext[left,base]{
711 \textcolor{red}{
712 Text absolutely positioned in
713 the lower left corner.}
714 }
715 \end{pgfpicture}
716 \end{codeexample}
717 %
718 \end{predefinednode}
719
720 There is also an option that allows you to create new special nodes quite
721 similar to the above:
722 %
723 \begin{key}{/pgf/local bounding box=\meta{node name}}
724 \keyalias{tikz}
725 This defines a new node \meta{node name} whose size is the bounding box
726 around all objects in the current scope starting at the position where this
727 option was given. After the end of the scope, the \meta{node name} is still
728 available. You can use this option to keep track of the size of a certain
729 area. Note that excessive use of this option (keeping track of dozens of
730 bounding boxes at the same time) will slow things down.
731 %
732 \begin{codeexample}[preamble={\usetikzlibrary{scopes}}]
733 \begin{tikzpicture}
734 \draw [help lines] (0,0) grid (3,2);
735 { [local bounding box=outer box]
736 \draw (1,1) circle (.5) [local bounding box=inner box] (2,2) circle (.5);
737 }
738 \draw (outer box.south west) rectangle (outer box.north east);
739 \draw[red] (inner box.south west) rectangle (inner box.north east);
740 \end{tikzpicture}
741 \end{codeexample}
742 %
743 \end{key}
744
745
746 \subsection{Declaring New Shapes}
747
748 There are only three predefined shapes, see
749 Section~\ref{section-predefined-shapes}, so there must be some way of defining
750 new shapes. Defining a shape is, unfortunately, a not-quite-trivial process.
751 The reason is that shapes need to be both very flexible (their size will vary
752 greatly according to circumstances) and they need to be constructed reasonably
753 ``fast''. \pgfname\ must be able to handle pictures with several hundreds of
754 nodes and documents with thousands of nodes in total. It would not do if
755 \pgfname\ had to compute and store, say, dozens of anchor positions for every
756 node.
757
758
759 \subsubsection{What Must Be Defined For a Shape?}
760
761 In order to define a new shape, you must provide:
762 %
763 \begin{itemize}
764 \item a \emph{shape name},
765 \item code for computing the \emph{saved anchors} and \emph{saved
766 dimensions},
767 \item code for computing \emph{anchor} positions in terms of the saved
768 anchors,
769 \item optionally code for the \emph{background path} and \emph{foreground
770 path},
771 \item optionally code for \emph{things to be drawn before or behind} the
772 background and foreground paths.
773 \item optionally a list of node parts.
774 \end{itemize}
775
776
777 \subsubsection{Normal Anchors Versus Saved Anchors}
778
779 Anchors are special places in a shape. For example, the |north east| anchor,
780 which is a normal anchor, lies at the upper right corner of the |rectangle|
781 shape, as does |\northeast|, which is a saved anchor. The difference is the
782 following: \emph{saved anchors are computed and stored for each node, anchors
783 are only computed as needed.} The user only has access to the normal anchors,
784 but a normal anchor can just ``copy'' or ``pass through'' the location of a
785 saved anchor.
786
787 The idea behind all this is that a shape can declare a very large number of
788 normal anchors, but when a node of this shape is created, these anchors are not
789 actually computed. However, this causes a problem: When we wish to reference an
790 anchor of a node at some later time, we must still be able to compute the
791 position of the anchor. For this, we may need a lot of information: What was
792 the transformation matrix that was in force when the node was created? What was
793 the size of the text box? What were the values of the different separation
794 dimensions? And so on.
795
796 To solve this problem, \pgfname\ will always compute the locations of all
797 \emph{saved anchors} and store these positions. Then, when an normal anchor
798 position is requested later on, the anchor position can be given just from
799 knowing where the locations of the saved anchors are.
800
801 As an example, consider the |rectangle| shape. For this shape two anchors are
802 saved: The |\northeast| corner and the |\southwest| corner. A normal anchor
803 like |north west| can now easily be expressed in terms of these coordinates:
804 Take the $x$-position of the |\southwest| point and the $y$-position of the
805 |\northeast| point. The |rectangle| shape currently defines 13 normal anchors,
806 but needs only two saved anchors. Adding new anchors like a |south south east|
807 anchor would not increase the memory and computation requirements of pictures.
808
809 All anchors (both saved and normal) are specified in a local \emph{shape
810 coordinate space}. This is also true for the background and foreground paths.
811 The |\pgfnode| macro will automatically apply appropriate transformations to
812 the coordinates so that the shape is shifted to the right anchor or otherwise
813 transformed.
814
815
816 \subsubsection{Command for Declaring New Shapes}
817
818 The following command declares a new shape:
819 %
820 \begin{command}{\pgfdeclareshape\marg{shape name}\marg{shape specification}}
821 This command declares a new shape named \meta{shape name}. The shape name
822 can later be used in commands like |\pgfnode|.
823
824 The \meta{shape specification} is some \TeX\ code containing calls to
825 special commands that are only defined inside the \meta{shape
826 specification} (similarly to commands like |\draw| that are only available
827 inside the |{tikzpicture}| environment).
828
829 \example Here is the code of the |coordinate| shape:
830 %
831 \begin{codeexample}[code only]
832 \pgfdeclareshape{coordinate}
833 {
834 \savedanchor\centerpoint{%
835 \pgf@x=.5\wd\pgfnodeparttextbox%
836 \pgf@y=.5\ht\pgfnodeparttextbox%
837 \advance\pgf@y by -.5\dp\pgfnodeparttextbox%
838 }
839 \anchor{center}{\centerpoint}
840 \anchorborder{\centerpoint}
841 }
842 \end{codeexample}
843
844 The special commands are explained next. In the examples given for the
845 special commands a new shape will be constructed, which we might call
846 |simple rectangle|. It should behave like the normal rectangle shape, only
847 without bothering about the fine details like inner and outer separations.
848 The skeleton for the shape is the following.
849 %
850 \begin{codeexample}[code only]
851 \pgfdeclareshape{simple rectangle}{
852 ...
853 }
854 \end{codeexample}
855
856 \begin{command}{\nodeparts\marg{list of node parts}}
857 This command declares which parts make up nodes of this shape. A
858 \emph{node part} is a (possibly empty) text label that is drawn when a
859 node of the shape is created.
860
861 By default, a shape has just one node part called |text|. However,
862 there can be several node parts. For example, the |circle split| shape
863 has two parts: the |text| part, which shows that the upper text, and a
864 |lower| part, which shows the lower text. For the |circle split| shape
865 the |\nodeparts| command was called with the argument |{text,lower}|.
866
867 When a multipart node is created, the text labels are drawn in the
868 sequences listed in the \meta{list of node parts}. For each node part,
869 you must have declared one anchor and the \TeX-box of the part is
870 placed at this anchor. For a node part called |XYZ| the \TeX-box
871 |\pgfnodepartXYZbox| is placed at anchor |XYZ|.
872 \end{command}
873
874 \begin{command}{\savedanchor\marg{command}\marg{code}}
875 This command declares a saved anchor. The argument \meta{command}
876 should be a \TeX\ macro name like |\centerpoint|.
877
878 The \meta{code} will be executed each time |\pgfnode| (or
879 |\pgfmultipartnode|) is called to create a node of the shape
880 \meta{shape name}. When the \meta{code} is executed, the \TeX-boxes of
881 the node parts will contain the text labels of the node. Possibly,
882 these box are void. For example, if there is just a |text| part, the
883 node |\pgfnodeparttextbox| will be set up when the \meta{code} is
884 executed.
885
886 The \meta{code} can use the width, height, and depth of the box(es) to
887 compute the location of the saved anchor. In addition, the \meta{code}
888 can take into account the values of dimensions like |\pgfshapeminwidth|
889 or |\pgfshapeinnerxsep|. Furthermore, the \meta{code} can take into
890 consideration the values of any further shape-specific variables that
891 are set at the moment when |\pgfnode| is called.
892
893 The net effect of the \meta{code} should be to set the two \TeX\
894 dimensions |\pgf@x| and |\pgf@y|. One way to achieve this is to say
895 |\pgfpoint{|\meta{x value}|}{|\meta{y value}|}| at the end of the
896 \meta{code}, but you can also just set these variables. The values that
897 |\pgf@x| and |\pgf@y| have after the code has been executed, let us
898 call them $x$ and $y$, will be recorded and stored together with the
899 node that is created by the command |\pgfnode|.
900
901 The macro \meta{command} is defined to be |\pgfpoint{|$x$|}{|$y$|}|.
902 However, the \meta{command} is only locally defined while anchor
903 positions are being computed. Thus, it is possible to use very simple
904 names for \meta{command}, like |\center| or |\a|, without causing a
905 name-clash. (To be precise, very simple \meta{command} names will clash
906 with existing names, but only locally inside the computation of anchor
907 positions; and we do not need the normal |\center| command during these
908 computations.)
909
910 For our |simple rectangle| shape, we will need only one saved anchor:
911 The upper right corner. The lower left corner could either be the
912 origin or the ``mirrored'' upper right corner, depending on whether we
913 want the text label to have its lower left corner at the origin or
914 whether the text label should be centered on the origin. Either will be
915 fine, for the final shape this will make no difference since the shape
916 will be shifted anyway. So, let us assume that the text label is
917 centered on the origin (this will be specified later on using the
918 |text| anchor). We get the following code for the upper right corner:
919 %
920 \begin{codeexample}[code only]
921 \savedanchor{\upperrightcorner}{
922 \pgf@y=.5\ht\pgfnodeparttextbox % height of the box, ignoring the depth
923 \pgf@x=.5\wd\pgfnodeparttextbox % width of the box
924 }
925 \end{codeexample}
926
927 If we wanted to take, say, the |\pgfshapeminwidth| into account, we
928 could use the following code:
929 %
930 \begin{codeexample}[code only]
931 \savedanchor{\upperrightcorner}{
932 \pgf@y=.\ht\pgfnodeparttextbox % height of the box
933 \pgf@x=.\wd\pgfnodeparttextbox % width of the box
934 \setlength{\pgf@xa}{\pgfshapeminwidth}
935 \ifdim\pgf@x<.5\pgf@xa
936 \pgf@x=.5\pgf@xa
937 \fi
938 }
939 \end{codeexample}
940 %
941 Note that we could not have written |.5\pgfshapeminwidth| since the
942 minimum width is stored in a ``plain text macro'', not as a real
943 dimension. So if |\pgfshapeminwidth| depth were 2cm, writing
944 |.5\pgfshapeminwidth| would yield the same as |.52cm|.
945
946 In the ``real'' |rectangle| shape the code is somewhat more complex,
947 but you get the basic idea.
948 \end{command}
949 %
950 \begin{command}{\saveddimen\marg{command}\marg{code}}
951 This command is similar to |\savedanchor|, only instead of setting
952 \meta{command} to |\pgfpoint{|$x$|}{|$y$|}|, the \meta{command} is set
953 just to (the value of) $x$.
954
955 In the |simple rectangle| shape we might use a saved dimension to store
956 the depth of the shape box.
957 %
958 \begin{codeexample}[code only]
959 \saveddimen{\depth}{
960 \pgf@x=\dp\pgfnodeparttextbox
961 }
962 \end{codeexample}
963 \end{command}
964 %
965 \begin{command}{\savedmacro\marg{command}\marg{code}}
966 This command is similar to |\saveddimen|, only at some point in
967 \meta{code}, \meta{command} should be defined appropriately, (this
968 could be a value, or some text).
969
970 In the |regular polygon| shape, a saved macro is used to store the
971 number of sides of the polygon.
972 %
973 \begin{codeexample}[code only]
974 \savedmacro{\sides}{\let\sides\pgfpolygonsides}
975 \end{codeexample}
976 \end{command}
977 %
978 \begin{command}{\anchor\marg{name}\marg{code}}
979 This command declares an anchor named \meta{name}. Unlike for saved
980 anchors, the \meta{code} will not be executed each time a node is
981 declared. Rather, the \meta{code} is only executed when the anchor is
982 specifically requested; either for anchoring the node during its
983 creation or as a position in the shape referenced later on.
984
985 The \meta{name} is a quite arbitrary string that is not ``passed down''
986 to the system level. Thus, names like |south| or |1| or |::| would all
987 be fine.
988
989 A saved anchor is not automatically also a normal anchor. If you wish
990 to give the users access to a saved anchor you must declare a normal
991 anchor that just returns the position of the saved anchor.
992
993 When the \meta{code} is executed, all saved anchor macros will be
994 defined. Thus, you can reference them in your \meta{code}. The effect
995 of the \meta{code} should be to set the values of |\pgf@x| and |\pgf@y|
996 to the coordinates of the anchor.
997
998 Let us consider some example for the |simple rectangle| shape. First,
999 we would like to make the upper right corner publicly available, for
1000 example as |north east|:
1001 %
1002 \begin{codeexample}[code only]
1003 \anchor{north east}{\upperrightcorner}
1004 \end{codeexample}
1005
1006 The |\upperrightcorner| macro will set |\pgf@x| and |\pgf@y| to the
1007 coordinates of the upper right corner. Thus, |\pgf@x| and |\pgf@y| will
1008 have exactly the right values at the end of the anchor's code.
1009
1010 Next, let us define a |north west| anchor. For this anchor, we can
1011 negate the |\pgf@x| variable:
1012 %
1013 \begin{codeexample}[code only]
1014 \anchor{north west}{
1015 \upperrightcorner
1016 \pgf@x=-\pgf@x
1017 }
1018 \end{codeexample}
1019
1020 Finally, it is a good idea to always define a |center| anchor, which
1021 will be the default location for a shape.
1022 %
1023 \begin{codeexample}[code only]
1024 \anchor{center}{\pgfpointorigin}
1025 \end{codeexample}
1026
1027 You might wonder whether we should not take into consideration that the
1028 node is not placed at the origin, but has been shifted somewhere.
1029 However, the anchor positions are always specified in the shape's
1030 ``private'' coordinate system. The ``outer'' transformation that has
1031 been applied to the shape upon its creation is applied automatically to
1032 the coordinates returned by the anchor's \meta{code}.
1033
1034 Our |simple rectangle| only has one text label (node part) called
1035 |text|. This is the default situation, so we do not need to do
1036 anything. For the |text| node part we must set up a |text| anchor. Upon
1037 creation of a node, this anchor will be made to coincide with the left
1038 endpoint of the baseline of the text label (within the private
1039 coordinate system of the shape). By default, the |text| anchor is at
1040 the origin, but you may change this. For example, we would say
1041 %
1042 \begin{codeexample}[code only]
1043 \anchor{text}{%
1044 \upperrightcorner%
1045 \pgf@x=-\pgf@x%
1046 \pgf@y=-\pgf@y%
1047 }
1048 \end{codeexample}
1049 to center the text label on the origin in the shape coordinate space.
1050 Note that we could \emph{not} have written the following:
1051 %
1052 \begin{codeexample}[code only]
1053 \anchor{text}{\pgfpoint{-.5\wd\pgfnodeparttextbox}{-.5\ht\pgfnodeparttextbox}}
1054 \end{codeexample}
1055 %
1056 Do you see why this is wrong? The problem is that the box
1057 |\pgfnodeparttextbox| will most likely not have the correct size when
1058 the anchor is computed. After all, the anchor position might be
1059 recomputed at a time when several other nodes have been created.
1060
1061 If a shape has several node parts, we would have to define an anchor
1062 for each part.
1063 \end{command}
1064
1065 \begin{command}{\deferredanchor\marg{name}\marg{code}}
1066 This command declares an anchor named \meta{name}. It works like
1067 |\anchor|. However, unlike for anchors declared by |\anchor|,
1068 \meta{name} will \emph{not} be expanded during the shape declaration
1069 (i.e.\ not during |\pgfdeclareshape|). Rather, the \meta{name} is
1070 expanded when the \emph{node} is actually used (with |\pgfnode| or more
1071 likely with |\node|). This may be useful if the anchor name is context
1072 dependent (depending, for example, on the value of a key).
1073 %
1074 \begin{codeexample}[code only]
1075 \makeatletter
1076 \def\foo{foo}
1077 \pgfdeclareshape{simple shape}{%
1078 \savedanchor{\center}{%
1079 \pgfpointorigin}
1080 \anchor{center}{\center}
1081 \savedanchor{\anchorfoo}{%
1082 \pgf@x=1cm
1083 \pgf@y=0cm}
1084 \deferredanchor{anchor \foo}{\anchorfoo}}
1085
1086 \begin{tikzpicture}
1087 \node[simple shape] (Test1) at (0,0) {};
1088 \fill (Test1.anchor foo) circle (2pt) node[below] {anchor foo anchor};
1089 %
1090 \def\foo{bar}
1091 \node[simple shape] (Test2) at (2,2) {};
1092 \fill (Test2.anchor bar) circle (2pt) node[below] {anchor bar anchor};
1093 \end{tikzpicture}
1094 \end{codeexample}
1095 \end{command}
1096 %
1097 \begin{command}{\anchorborder\marg{code}}
1098 A \emph{border anchor} is an anchor point on the border of the shape.
1099 What exactly is considered as the ``border'' of the shape depends on
1100 the shape.
1101
1102 When the user requests a point on the border of the shape using the
1103 |\pgfpointshapeborder| command, the \meta{code} will be executed to
1104 discern this point. When the execution of the \meta{code} starts, the
1105 dimensions |\pgf@x| and |\pgf@y| will have been set to a location $p$
1106 in the shape's coordinate system, and relative to the anchor |center|.
1107 Note that |\pgfpointshapeborder| will produce an error if the shape does
1108 not contain the |center| anchor.
1109
1110 It is now the job of the \meta{code} to set up |\pgf@x| and |\pgf@y|
1111 such that they specify the point on the shape's border that lies on a
1112 straight line from the shape's center to the point $p$. Usually, this is
1113 a somewhat complicated computation, involving many case distinctions and
1114 some basic math. Note that the output coordinates must be returned in the
1115 shape's coordinate system, \emph{no longer} relative to the |center|
1116 anchor. While these different points of reference are only noticeable if
1117 the |center| anchor is not at the origin of the shape's coordinate system,
1118 it implies that ``doing nothing'' as a border anchor, i.e., returning the
1119 point that was fed to |\pgfpointshapeborder| requires adding the |center|
1120 anchor to the input coordinates.
1121
1122 For our |simple rectangle| we must compute a point on the border of a
1123 rectangle whose one corner is the origin (ignoring the depth for
1124 simplicity) and whose other corner is |\upperrightcorner|. The
1125 following code might be used:
1126 %
1127 \begin{codeexample}[code only]
1128 \anchorborder{%
1129 % Call a function that computes a border point. Since this
1130 % function will modify dimensions like \pgf@x, we must move them to
1131 % other dimensions.
1132 \@tempdima=\pgf@x
1133 \@tempdimb=\pgf@y
1134 \pgfpointborderrectangle{\pgfpoint{\@tempdima}{\@tempdimb}}{\upperrightcorner}
1135 }
1136 \end{codeexample}
1137 \end{command}
1138 %
1139 \begin{command}{\backgroundpath\marg{code}}
1140 This command specifies the path that ``makes up'' the background of the
1141 shape. Note that the shape cannot prescribe what is going to happen
1142 with the path: It might be drawn, shaded, filled, or even thrown away.
1143 If you want to specify that something should ``always'' happen when
1144 this shape is drawn (for example, if the shape is a stop-sign, we
1145 \emph{always} want it to be filled with a red color), you can use
1146 commands like |\beforebackgroundpath|, explained below.
1147
1148 When the \meta{code} is executed, all saved anchors will be in effect.
1149 The \meta{code} should contain path construction commands.
1150
1151 For our |simple rectangle|, the following code might be used:
1152 %
1153 \begin{codeexample}[code only]
1154 \backgroundpath{
1155 \pgfpathrectanglecorners
1156 {\upperrightcorner}
1157 {\pgfpointscale{-1}{\upperrightcorner}}
1158 }
1159 \end{codeexample}
1160 %
1161 As the name suggests, the background path is used ``behind'' the text
1162 labels. Thus, this path is used first, then the text labels are drawn,
1163 possibly obscuring part of the path.
1164 \end{command}
1165 %
1166 \begin{command}{\foregroundpath\marg{code}}
1167 This command works like |\backgroundpath|, only it is invoked after the
1168 text labels have been drawn. This means that this path can possibly
1169 obscure (part of) the text labels.
1170 \end{command}
1171 %
1172 \begin{command}{\behindbackgroundpath\marg{code}}
1173 Unlike the previous two commands, \meta{code} should not only construct
1174 a path, it should also use this path in whatever way is appropriate.
1175 For example, the \meta{code} might fill some area with a uniform color.
1176
1177 Whatever the \meta{code} does, it does it first. This means that any
1178 drawing done by \meta{code} will be even behind the background path.
1179
1180 Note that the \meta{code} is protected with a |{pgfscope}|.
1181 \end{command}
1182 %
1183 \begin{command}{\beforebackgroundpath\marg{code}}
1184 This command works like |\behindbackgroundpath|, only the \meta{code}
1185 is executed after the background path has been used, but before the
1186 texts label are drawn.
1187 \end{command}
1188 %
1189 \begin{command}{\behindforegroundpath\marg{code}}
1190 The \meta{code} is executed after the text labels have been drawn, but
1191 before the foreground path is used.
1192 \end{command}
1193 %
1194 \begin{command}{\beforeforegroundpath\marg{code}}
1195 This \meta{code} is executed at the very end.
1196 \end{command}
1197 %
1198 \begin{command}{\inheritsavedanchors|[from=|\marg{another shape name}|]|}
1199 This command allows you to inherit the code for saved anchors from
1200 \meta{another shape name}. The idea is that if you wish to create a new
1201 shape that is just a small modification of a another shape, you can
1202 recycle the code used for \meta{another shape name}.
1203
1204 The effect of this command is the same as if you had called
1205 |\savedanchor| and |\saveddimen| for each saved anchor or saved
1206 dimension declared in \meta{another shape name}. Thus, it is not
1207 possible to ``selectively'' inherit only some saved anchors, you always
1208 have to inherit all saved anchors from another shape. However, you can
1209 inherit the saved anchors of more than one shape by calling this
1210 command several times.
1211 \end{command}
1212 %
1213 \begin{command}{\inheritbehindbackgroundpath|[from=|\marg{another shape name}|]|}
1214 This command can be used to inherit the code used for the drawings
1215 behind the background path from \meta{another shape name}.
1216 \end{command}
1217 %
1218 \begin{command}{\inheritbackgroundpath|[from=|\marg{another shape name}|]|}
1219 Inherits the background path code from \meta{another shape name}.
1220 \end{command}
1221 %
1222 \begin{command}{\inheritbeforebackgroundpath|[from=|\marg{another shape name}|]|}
1223 Inherits the before background path code from \meta{another shape
1224 name}.
1225 \end{command}
1226 %
1227 \begin{command}{\inheritbehindforegroundpath|[from=|\marg{another shape name}|]|}
1228 Inherits the behind foreground path code from \meta{another shape
1229 name}.
1230 \end{command}
1231 %
1232 \begin{command}{\inheritforegroundpath|[from=|\marg{another shape name}|]|}
1233 Inherits the foreground path code from \meta{another shape name}.
1234 \end{command}
1235 %
1236 \begin{command}{\inheritbeforeforegroundpath|[from=|\marg{another shape name}|]|}
1237 Inherits the before foreground path code from \meta{another shape
1238 name}.
1239 \end{command}
1240 %
1241 \begin{command}{\inheritanchor|[from=|\marg{another shape name}|]|\marg{name}}
1242 Inherits the code of one specific anchor named \meta{name} from
1243 \meta{another shape name}. Thus, unlike saved anchors, which must be
1244 inherited collectively, normal anchors can and must be inherited
1245 individually.
1246 \end{command}
1247 %
1248 \begin{command}{\inheritanchorborder|[from=|\marg{another shape name}|]|}
1249 Inherits the border anchor code from \meta{another shape name}.
1250 \end{command}
1251
1252 The following example shows how a shape can be defined that relies heavily
1253 on inheritance:
1254 %
1255 \makeatletter
1256 \begin{codeexample}[
1257 preamble={\usetikzlibrary{shapes.geometric}},
1258 pre={\makeatletter},
1259 ]
1260 \pgfdeclareshape{document}{
1261 \inheritsavedanchors[from=rectangle] % this is nearly a rectangle
1262 \inheritanchorborder[from=rectangle]
1263 \inheritanchor[from=rectangle]{center}
1264 \inheritanchor[from=rectangle]{north}
1265 \inheritanchor[from=rectangle]{south}
1266 \inheritanchor[from=rectangle]{west}
1267 \inheritanchor[from=rectangle]{east}
1268 % ... and possibly more
1269 \backgroundpath{% this is new
1270 % store lower right in xa/ya and upper right in xb/yb
1271 \southwest \pgf@xa=\pgf@x \pgf@ya=\pgf@y
1272 \northeast \pgf@xb=\pgf@x \pgf@yb=\pgf@y
1273 % compute corner of ``flipped page''
1274 \pgf@xc=\pgf@xb \advance\pgf@xc by-5pt % this should be a parameter
1275 \pgf@yc=\pgf@yb \advance\pgf@yc by-5pt
1276 % construct main path
1277 \pgfpathmoveto{\pgfpoint{\pgf@xa}{\pgf@ya}}
1278 \pgfpathlineto{\pgfpoint{\pgf@xa}{\pgf@yb}}
1279 \pgfpathlineto{\pgfpoint{\pgf@xc}{\pgf@yb}}
1280 \pgfpathlineto{\pgfpoint{\pgf@xb}{\pgf@yc}}
1281 \pgfpathlineto{\pgfpoint{\pgf@xb}{\pgf@ya}}
1282 \pgfpathclose
1283 % add little corner
1284 \pgfpathmoveto{\pgfpoint{\pgf@xc}{\pgf@yb}}
1285 \pgfpathlineto{\pgfpoint{\pgf@xc}{\pgf@yc}}
1286 \pgfpathlineto{\pgfpoint{\pgf@xb}{\pgf@yc}}
1287 \pgfpathlineto{\pgfpoint{\pgf@xc}{\pgf@yc}}
1288 }
1289 }\hskip-1.2cm
1290 \begin{tikzpicture}
1291 \node[shade,draw,shape=document,inner sep=2ex] (x) {Remark};
1292 \node[fill=yellow!80!black,draw,ellipse,double]
1293 at ([shift=(-80:3cm)]x) (y) {Use Case};
1294
1295 \draw[dashed] (x) -- (y);
1296 \end{tikzpicture}
1297 \end{codeexample}
1298 %
1299 \end{command}
1300
1301
1302 %%% Local Variables:
1303 %%% mode: latex
1304 %%% TeX-master: "pgfmanual"
1305 %%% End: