summaryrefslogtreecommitdiff
path: root/graphics/pgf/base/doc/text-en/pgfmanual-en-base-nodes.tex
blob: 19499ec55174ea94de24e44e1e40acb6b86e1046 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
% Copyright 2019 by Till Tantau
%
% This file may be distributed and/or modified
%
% 1. under the LaTeX Project Public License and/or
% 2. under the GNU Free Documentation License.
%
% See the file doc/generic/pgf/licenses/LICENSE for more details.


\section{Nodes and Shapes}

\label{section-shapes}

This section describes the |shapes| module.

\begin{pgfmodule}{shapes}
    This module defines commands both for creating nodes and for creating
    shapes. The package is loaded automatically by |pgf|, but you can load it
    manually if you have  only included |pgfcore|.
\end{pgfmodule}


\subsection{Overview}

\pgfname\ comes with a sophisticated set of commands for creating \emph{nodes}
and \emph{shapes}. A \emph{node} is a graphical object that consists
(typically) of (one or more) text labels and some additional stroked or filled
paths. Each node has a certain \emph{shape}, which may be something simple like
a |rectangle| or a |circle|, but it may also be something complicated like a
|uml class diagram| (this shape is currently not implemented, though).
Different nodes that have the same shape may look quite different, however,
since shapes (need not) specify whether the shape path is stroked or filled.


\subsubsection{Creating and Referencing Nodes}

You create a node by calling the macro |\pgfnode| or the more general
|\pgfmultipartnode|. This macro takes several parameters and draws the
requested shape at a certain position. In addition, it will ``remember'' the
node's position within the current |{pgfpicture}|. You can then, later on,
refer to the node's position. Coordinate transformations are ``fully
supported'', which means that if you used coordinate transformations to shift
or rotate the shape of a node, the node's position will still be correctly
determined by \pgfname. This is \emph{not} the case if you use canvas
transformations instead.


\subsubsection{Anchors}

An important property of a node or a shape in general are its \emph{anchors}.
Anchors are ``important'' positions in a shape. For example, the |center|
anchor lies at the center of a shape, the |north| anchor is usually ``at the
top, in the middle'' of a shape, the |text| anchor is the lower left corner of
the shape's text label (if present), and so on.

Anchors are important both when you create a node and when you reference it.
When you create a node, you specify the node's ``position'' by asking \pgfname\
to place the shape in such a way that a certain anchor lies at a certain point.
For example, you might ask that the node is placed such that the |north| anchor
is at the origin. This will effectively cause the node to be placed below the
origin.

When you reference a node, you always reference an anchor of the node. For
example, when you request the ``|north| anchor of the node just placed'' you
will get the origin. However, you can also request the ``|south| anchor of this
node'', which will give you a point somewhere below the origin. When a
coordinate transformation was in force at the time of creation of a node, all
anchors are also transformed accordingly.


\subsubsection{Layers of a Shape}

The simplest shape, the |coordinate|, has just one anchor, namely the |center|,
and a label (which is usually empty). More complicated shapes like the
|rectangle| shape also have a \emph{background path}. This is a \pgfname-path
that is defined by the shape. The shape does not prescribe what should happen
with the path: When a node is created, this path may be stroked (resulting in a
frame around the label), filled (resulting in a background color for the text),
or just discarded.

Although most shapes consist just of a background path plus some label text,
when a shape is drawn, up to seven different layers are drawn:
%
\begin{enumerate}
    \item The ``behind the background layer''. Unlike the background path,
        which can be used in different ways by different nodes, the graphic
        commands given for this layer will always stroke or always fill the
        path they construct. They might also insert some text that is ``behind
        everything''.
    \item The background path layer. How this path is used depends on the
        arguments of the |\pgfnode| command.
    \item The ``before the background path layer''. This layer works like the
        first one, only the commands of this layer are executed after the
        background path has been used (in whatever way the creator of the node
        chose).
    \item The label layer. This layer inserts the node's text box(es).
    \item The ``behind the foreground layer''. This layer, like the first
        layer, once more contains graphic commands that are ``simply
        executed''.
    \item The foreground path layer. This path is treated in the same way as
        the background path, only it is drawn after the label text has been
        drawn.
    \item The ``before the foreground layer''.
\end{enumerate}

Which of these layers are actually used depends on the shape.


\subsubsection{Node Parts}

A shape typically does not consist only of different background and foreground
paths, but it may also have text labels. Indeed, for many shapes the text
labels are the more important part of the shape.

Most shapes will have only one text label. In this case, this text label is
simply passed as a parameter to the |\pgfnode| command. When the node is drawn,
the text label is shifted around such that its lower left corner is at the
|text| anchor of the node.

More complicated shapes may have more than one text label. Nodes of such shapes
are called \emph{multipart nodes}. The different \emph{node parts} are simply
the different text labels. For example, a |uml class| shape might have a
|class name| part, a |method| part and an |attributes| part. Indeed, single
part nodes are a special case of multipart nodes: They only have one part named
|text|.

When a shape is declared, you must specify the node parts. There is a simple
command called |\nodeparts| that takes a list of the part names as input. When
you create a node of a multipart shape, for each part of the node you must have
set up a \TeX-box containing the text of the part. For a part named |XYZ| you
must set up the box |\pgfnodepartXYZbox|. The box will be placed at the anchor
|XYZ|. See the description of |\pgfmultipartnode| for more details.


\subsection{Creating Nodes}

\subsubsection{Creating Simple Nodes}

\begin{command}{\pgfnode\marg{shape}\marg{anchor}\marg{label text}\marg{name}\marg{path usage command}}
    This command creates a new node. The \meta{shape} of the node must have
    been declared previously using |\pgfdeclareshape|.

    The shape is shifted such that the \meta{anchor} is at the origin. In order
    to place the shape somewhere else, use the coordinate transformation prior
    to calling this command.

    The \meta{name} is a name for later reference. If no name is given, nothing
    will be ``saved'' for the node, it will just be drawn.

    The \meta{path usage command} is executed for the background and the
    foreground path (if the shape defines them).
    %
\begin{codeexample}[]
\begin{tikzpicture}
  \draw[help lines] (0,0) grid (4,3);
  {
    \pgftransformshift{\pgfpoint{1.5cm}{1cm}}
    \pgfnode{rectangle}{north}{Hello World}{hellonode}{\pgfusepath{stroke}}
  }
  {
    \color{red!20}
    \pgftransformrotate{10}
    \pgftransformshift{\pgfpoint{3cm}{1cm}}
    \pgfnode{rectangle}{center}
      {\color{black}Hello World}{hellonode}{\pgfusepath{fill}}
  }
\end{tikzpicture}
\end{codeexample}

    As can be seen, all coordinate transformations are also applied to the text
    of the shape. Sometimes, it is desirable that the transformations are
    applied to the point where the shape will be anchored, but you do not wish
    the shape itself to be transformed. In this case, you should call
    |\pgftransformresetnontranslations| prior to calling the |\pgfnode|
    command.
    %
\begin{codeexample}[]
\begin{tikzpicture}
  \draw[help lines] (0,0) grid (4,3);
  {
    \color{red!20}
    \pgftransformrotate{10}
    \pgftransformshift{\pgfpoint{3cm}{1cm}}
    \pgftransformresetnontranslations
    \pgfnode{rectangle}{center}
      {\color{black}Hello World}{hellonode}{\pgfusepath{fill}}
  }
\end{tikzpicture}
\end{codeexample}

    The \meta{label text} is typeset inside the \TeX-box |\pgfnodeparttextbox|.
    This box is shown at the |text| anchor of the node, if the node has a
    |text| part. See the description of |\pgfmultipartnode| for details.
\end{command}


\subsubsection{Creating Multi-Part Nodes}

\begin{command}{\pgfmultipartnode\marg{shape}\marg{anchor}\marg{name}\marg{path usage command}}
    This command is the more general (and less user-friendly) version of the
    |\pgfnode| command. While the |\pgfnode| command can only be used for
    shapes that have a single part (which is the case for most shapes), this
    command can also be used with multi-part nodes.

    When this command is called, for each node part of the node you must have
    set up one \TeX-box. Suppose the shape has two parts: The |text| part and
    the |lower| part. Then, prior to calling |\pgfmultipartnode|, you must have
    set up the boxes |\pgfnodeparttextbox| and |\pgfnodepartlowerbox|. These
    boxes may contain any \TeX-text. The shape code will then compute the
    positions of the shape's anchors based on the sizes of the these shapes.
    Finally, when the node is drawn, the boxes are placed at the anchor
    positions |text| and |lower|.
    %
\begin{codeexample}[preamble={\usetikzlibrary{shapes}}]
\setbox\pgfnodeparttextbox=\hbox{$q_1$}
\setbox\pgfnodepartlowerbox=\hbox{01}
\begin{pgfpicture}
  \pgfmultipartnode{circle split}{center}{my state}{\pgfusepath{stroke}}
\end{pgfpicture}
\end{codeexample}

    \emph{Note:} Be careful when using the |\setbox| command inside a
    |{pgfpicture}| command. You will have to use |\pgfinterruptpath| at the
    beginning of the box and |\endpgfinterruptpath| at the end of the box to
    make sure that the box is typeset correctly. In the above example this
    problem was sidestepped by moving the box construction outside the
    environment.

    \emph{Note:} It is not necessary to use |\newbox| for every node part
    name. Although you need a different box for each part of a single shape,
    two different shapes may very well use the same box even when the names of
    the parts are different. Suppose you have a |circle split| shape that has a
    |lower| part and you have a |uml class| shape that has a |methods| part.
    Then, in order to avoid exhausting \TeX's limited number of box registers,
    you can say
    %
\begin{codeexample}[code only]
\newbox\pgfnodepartlowerbox
\let\pgfnodepartmethodsbox=\pgfnodepartlowerbox
\end{codeexample}
    %
    Also, when you have a node part name with spaces like |class name|, it may
    be useful to create an alias:
    %
\begin{codeexample}[code only]
\newbox\mybox
\expandafter\let\csname pgfnodepartclass namebox\endcsname=\mybox
\end{codeexample}
    %
\end{command}

\begin{command}{\pgfcoordinate\marg{name}\marg{coordinate}}
    This command creates a node of shape |coordinate| at the given
    \meta{coordinate}. Exactly the same effect can be achieved using first a
    shift of the coordinate system to \meta{coordinate}, followed by creating a
    node of shape |coordinate| named \meta{name}. However, this command is
    easier and more natural to use and, more importantly, it is much faster.
\end{command}

\begin{command}{\pgfnodealias\marg{new name}\marg{existing node}}
    This command does not actually create a new node. Rather, it allows you to
    subsequently access the node \meta{existing node} using the name \meta{new
    name}.
\end{command}

\begin{command}{\pgfnoderename\marg{new name}\marg{existing node}}
    This command renames an existing node.
\end{command}

There are a number of values that have an influence on the size of a node.
These values are stored in the following keys.

\begin{key}{/pgf/minimum width=\meta{dimension} (initially 1pt)}
\keyalias{tikz}
    This key stores the \emph{recommended} minimum width of a shape. Thus, when
    a shape is drawn and when the shape's width would be smaller than
    \meta{dimension}, the shape's width is enlarged by adding some empty space.

    Note that this value is just a recommendation. A shape may choose to ignore
    this key.
    %
\begin{codeexample}[]
\begin{tikzpicture}
  \draw[help lines] (-2,0) grid (2,1);

  \pgfset{minimum width=3cm}
  \pgfnode{rectangle}{center}{Hello World}{}{\pgfusepath{stroke}}
\end{tikzpicture}
\end{codeexample}
    %
\end{key}

\begin{key}{/pgf/minimum height=\meta{dimension} (initially 1pt)}
\keyalias{tikz}
    Works like |/pgf/minimum width|.
\end{key}

\begin{key}{/pgf/minimum size=\meta{dimension}}
\keyalias{tikz}
    This style both |/pgf/minimum width| and |/pgf/minimum height| to \meta{dimension}.
\end{key}

\begin{key}{/pgf/inner xsep=\meta{dimension} (initially 0.3333em)}
\keyalias{tikz}
    This key stores the \emph{recommended} horizontal inner separation between
    the label text and the background path. As before, this value is just a
    recommendation and a shape may choose to ignore this key.
    %
\begin{codeexample}[]
\begin{tikzpicture}
  \draw[help lines] (-2,0) grid (2,1);

  \pgfset{inner xsep=1cm}
  \pgfnode{rectangle}{center}{Hello World}{}{\pgfusepath{stroke}}
\end{tikzpicture}
\end{codeexample}
    %
\end{key}

\begin{key}{/pgf/inner ysep=\meta{dimension} (initially 0.3333em)}
\keyalias{tikz}
    Works like |/pgf/inner xsep|.
\end{key}

\begin{key}{/pgf/inner sep=\meta{dimension}}
\keyalias{tikz}
    This style sets both |/pgf/inner xsep| and |/pgf/inner ysep| to
    \meta{dimension}.
\end{key}

\begin{key}{/pgf/outer xsep=\meta{dimension} (initially .5\string\pgflinewidth)}
\keyalias{tikz}
    This key stores the recommended horizontal separation between the
    background path and the ``outer anchors''. For example, if \meta{dimension}
    is |1cm| then the |east| anchor will be 1cm to the right of the right
    border of the background path. As before, this value is just a
    recommendation.
    %
\begin{codeexample}[]
\begin{tikzpicture}
  \draw[help lines] (-2,0) grid (2,1);

  \pgfset{outer xsep=.5cm}
  \pgfnode{rectangle}{center}{Hello World}{x}{\pgfusepath{stroke}}

  \pgfpathcircle{\pgfpointanchor{x}{north}}{2pt}
  \pgfpathcircle{\pgfpointanchor{x}{south}}{2pt}
  \pgfpathcircle{\pgfpointanchor{x}{east}}{2pt}
  \pgfpathcircle{\pgfpointanchor{x}{west}}{2pt}
  \pgfpathcircle{\pgfpointanchor{x}{north east}}{2pt}
  \pgfusepath{fill}
\end{tikzpicture}
\end{codeexample}
    %
\end{key}

\begin{key}{/pgf/outer ysep=\meta{dimension} (initially .5\string\pgflinewidth)}
\keyalias{tikz}
    Works like |/pgf/outer xsep|.
\end{key}

\begin{key}{/pgf/outer sep=\meta{dimension}}
\keyalias{tikz}
    This style sets both |/pgf/outer xsep| and |/pgf/outer ysep| to
    \meta{dimension}.
\end{key}


\subsubsection{Deferred Node Positioning}
\label{section-shapes-deferred-node-positioning}

Normally, when a node is created using a command like |\pgfnode|, the node is
immediately inserted into the current picture. In particular, you have no
chance to change the position of a created node after it has been created.
Using |\pgfpositionnodelater| in concert with |\pgfpositionnodenow|, you can
create a node whose position is determined only at some later time.

\begin{command}{\pgfpositionnodelater\marg{macro name}}
    This command is not a replacement for |\pgfnode|. Rather, when this command
    is used in a scope, all subsequent node creations in this scope will be
    affected in the following way:  When a node is created, it is not inserted
    into the current picture. Instead, it is stored in the box
    |\pgfpositionnodelaterbox|. Furthermore, the node is not relevant for the
    picture's bounding box, but a bounding box for the node is computed and
    stored in the macros |\pgfpositionnodelaterminx| to
    |\pgfpositionnodelatermaxy|. Then, the \meta{macro name} is called with the
    following macros set up:

    \begin{command}{\pgfpositionnodelaterbox}
        A box register number (|0| currently) that stores the node's paths and
        texts. You should move the contents of this box to a box of your choice
        inside \meta{macro name}.
    \end{command}

    \begin{command}{\pgfpositionnodelatername}
        The name of the just-created-node. This name will be the originally
        ``desired'' name of the box plus the fixed prefix
        |not yet positionedPGFINTERNAL|. The idea is to ensure that the
        original name is not inadvertently used before the node is actually
        positioned. When |\pgfpositionnodenow| is called, it will change the
        name to the
        original name.
    \end{command}

    \begin{command}{\pgfpositionnodelaterminx}
        The minimal $x$-position of a bounding box of the node. This bounding
        box refers to the node when it is positioned with the anchor at the
        origin. It is guaranteed, that this macro will contain a dimension in
        the format \meta{number}|pt|.
    \end{command}
    %
    \begin{command}{\pgfpositionnodelaterminy}
    \end{command}
    %
    \begin{command}{\pgfpositionnodelatermaxx}
    \end{command}
    %
    \begin{command}{\pgfpositionnodelatermaxy}
    \end{command}

    Once a late node has been created, you can add arbitrary code in the same
    picture. Then, at some later point, you call |\pgfpositionnodenow| to
    finally position the node at a given position.  At this point, the above
    macros must have the exact same values they had when \meta{macro name} was
    called. Note that the above macros are local to a scope that ends right
    after the call to \meta{macro name}, so it is your job to copy the values
    to safety inside \meta{macro name}.

    The following two macros will also be set inside the call to \meta{macro
    name}, but they are only ``informative'' in the sense that you need
    \emph{not} restore these macros when |\pgfpositionnodenow| is called.

    \begin{command}{\pgfpositionnodelaterpath}
        This macro stores the path of the background of the node. See
        Section~\ref{section-soft-paths} for an overview of how these paths are
        encode.
    \end{command}

    By setting \meta{macro name} to |\relax| (which is the default), you can
    switch off the whole mechanism. When a picture is interrupted, this is done
    automatically.
\end{command}

\begin{command}{\pgfpositionnodenow\marg{coordinate}}
    This command is used to position a node that has previously been created
    using the command |\pgfpositionnodelater|. When |\pgfpositionnodenow| is
    called, the macros and boxes mentioned in the description of
    |\pgfpositionnodenow| must be set to the value they had when the
    \meta{macro name} was called. Provided this is the case, this command will
    insert the box into the current picture, shifted by \meta{coordinate}.
    Then, the late code (see below) is called. Subsequently, you can refer to
    the node with its original name as if it had just been created.
    %
\begin{codeexample}[]
\newbox\mybox

\def\mysaver{
  \global\setbox\mybox=\box\pgfpositionnodelaterbox
  \global\let\myname=\pgfpositionnodelatername
  \global\let\myminx=\pgfpositionnodelaterminx
  \global\let\myminy=\pgfpositionnodelaterminy
  \global\let\mymaxx=\pgfpositionnodelatermaxx
  \global\let\mymaxy=\pgfpositionnodelatermaxy
}

\begin{tikzpicture}
  {
    \pgfpositionnodelater{\mysaver}
    \node [fill=blue!20,below,rotate=30] (hi) {Hello world};
  }
  \draw [help lines] (0,0) grid (3,2);

  \let\pgfpositionnodelatername=\myname
  \let\pgfpositionnodelaterminx=\myminx
  \let\pgfpositionnodelaterminy=\myminy
  \let\pgfpositionnodelatermaxx=\mymaxx
  \let\pgfpositionnodelatermaxy=\mymaxy
  \setbox\pgfpositionnodelaterbox=\box\mybox
  \pgfpositionnodenow{\pgfqpoint{2cm}{2cm}}

  \draw (hi) -- (0,0);
\end{tikzpicture}
\end{codeexample}
    %
\end{command}

\begin{command}{\pgfnodepostsetupcode\marg{node name}\marg{code}}
    When you call this macro inside a scope for which the
    |\pgfpositionnodelater| has been called, the \meta{code} will be stored
    internally. Later, when the node named \meta{node name} is actually
    positioned using |\pgfpositionnodenow|, the \meta{code} will be executed.
    When this macro is called multiple times with the same \meta{node name},
    the \meta{code} accumulates. However, When |\pgfpositionnodenow| is called,
    the code stored for the node is cleared.

    The main purpose of this mechanism is to allow \tikzname\ to store
    so-called ``late options'' with a node that will be positioned only later.
\end{command}


\subsection{Using Anchors}

Each shape defines a set of anchors. We saw already that the anchors are used
when the shape is drawn: the shape is placed in such a way that the given
anchor is at the origin (which in turn is typically translated somewhere else).

One has to look up the set of anchors of each shape, there is no ``default''
set of anchors, except for the |center| anchor, which should always be present.
Also, most shapes will declare anchors like |north| or |east|, but this is not
guaranteed.


\subsubsection{Referencing Anchors of Nodes in the Same Picture}

Once a node has been defined, you can refer to its anchors using the following
commands:

\begin{command}{\pgfpointanchor\marg{node}\marg{anchor}}
    This command is another ``point command'' like the commands described in
    Section~\ref{section-points}. It returns the coordinate of the given
    \meta{anchor} in the given \meta{node}. The command can be used in commands
    like |\pgfpathmoveto|.
    %
\begin{codeexample}[]
\begin{pgfpicture}
  \pgftransformrotate{30}
  \pgfnode{rectangle}{center}{Hello World!}{x}{\pgfusepath{stroke}}

  \pgfpathcircle{\pgfpointanchor{x}{north}}{2pt}
  \pgfpathcircle{\pgfpointanchor{x}{south}}{2pt}
  \pgfpathcircle{\pgfpointanchor{x}{east}}{2pt}
  \pgfpathcircle{\pgfpointanchor{x}{west}}{2pt}
  \pgfpathcircle{\pgfpointanchor{x}{north east}}{2pt}
  \pgfusepath{fill}
\end{pgfpicture}
\end{codeexample}

    In the above example, you may have noticed something curious: The rotation
    transformation is still in force when the anchors are invoked, but it does
    not seem to have an effect. You might expect that the rotation should apply
    to the already rotated points once more.

    However, |\pgfpointanchor| returns a point that takes the current
    transformation matrix into account: \emph{The inverse transformation to the
    current coordinate transformation is applied to an anchor point before
    returning it.}

    This behavior may seem a bit strange, but you will find it very natural in
    most cases. If you really want to apply a transformation to an anchor point
    (for example, to ``shift it away'' a little bit), you have to invoke
    |\pgfpointanchor| without any transformations in force. Here is an example:
    %
\makeatletter
\begin{codeexample}[pre={\makeatletter}]
\begin{pgfpicture}
  \pgftransformrotate{30}
  \pgfnode{rectangle}{center}{Hello World!}{x}{\pgfusepath{stroke}}

  {
    \pgftransformreset
    \pgfpointanchor{x}{east}
    \xdef\mycoordinate{\noexpand\pgfpoint{\the\pgf@x}{\the\pgf@y}}
  }

  \pgfpathcircle{\mycoordinate}{2pt}
  \pgfusepath{fill}
\end{pgfpicture}
\end{codeexample}

    A special situation arises when the \meta{node} lies in a picture different
    from the current picture. In this case, if you have not told \pgfname\ that
    the picture should be ``remembered'', the \meta{node} will be treated as if
    it lay in the current picture. For example, if the \meta{node} was at
    position $(3,2)$ in the original picture, it is treated as if it lay at
    position $(3,2)$ in the current picture. However, if you have told
    \pgfname\ to remember the picture position of the node's picture and also
    of the current picture, then |\pgfpointanchor| will return a coordinate
    that corresponds to the position of the node's anchor on the page,
    transformed into the current coordinate system. For examples and more
    details see Section~\ref{section-cross-pictures-pgf}.
\end{command}

\begin{command}{\pgfpointshapeborder\marg{node}\marg{point}}
    This command returns the point on the border of the shape that lies on a
    straight line from the center of the node to \meta{point}. For complex
    shapes it is not guaranteed that this point will actually lie on the
    border, it may be on the border of a ``simplified'' version of the shape.
    %
\begin{codeexample}[]
\begin{pgfpicture}
  \begin{pgfscope}
    \pgftransformrotate{30}
    \pgfnode{rectangle}{center}{Hello World!}{x}{\pgfusepath{stroke}}
  \end{pgfscope}
  \pgfpathcircle{\pgfpointshapeborder{x}{\pgfpoint{2cm}{1cm}}}{2pt}
  \pgfpathcircle{\pgfpoint{2cm}{1cm}}{2pt}
  \pgfpathcircle{\pgfpointshapeborder{x}{\pgfpoint{-1cm}{1cm}}}{2pt}
  \pgfpathcircle{\pgfpoint{-1cm}{1cm}}{2pt}
  \pgfusepath{fill}
\end{pgfpicture}
\end{codeexample}
    %
    \emph{Remark:} If the given \meta{point} is almost identical to the center
    of \meta{node}, the node center is returned and a warning message will be
    printed.
\end{command}


\subsubsection{Referencing Anchors of Nodes in Different Pictures}
\label{section-cross-pictures-pgf}

As a picture is typeset, \pgfname\ keeps track of the positions of all nodes
inside the picture. What \pgfname\ does not remember is the position of the
picture \emph{itself} on the page. Thus, if you define a node in one picture
and then try to reference this node while another picture is typeset, \pgfname\
will only know the position of the nodes that you try to typeset inside the
original picture, but it will not know where this picture lies. What is missing
is the relative positioning of the two pictures.

To overcome this problem, you need to tell \pgfname\ that it should remember
the position of pictures on a page. If these positions are remembered, then
\pgfname\ can compute the offset between the pictures and make nodes in
different pictures accessible.

Determining the positions of pictures on the page is, alas, not-so-easy.
Because of this, \pgfname\ does not do so automatically. Rather, you have to
proceed as follows:
%
\begin{enumerate}
    \item You have to use a backend driver that supports position tracking.
        pdf\TeX\ is one such driver, |dvips| currently is not.
    \item You have to say |\pgfrememberpicturepositiononpagetrue| somewhere
        before or inside every picture
        %
        \begin{itemize}
            \item in which you wish to reference a node and
            \item from which you wish to reference a node in another picture.
        \end{itemize}
        %
        The second item is important since \pgfname\ does not only need to know
        the position of the picture in which the node you wish to reference
        lies, but it also needs to know where the current picture lies.
    \item You typically have to run \TeX\ twice (depending on the backend
        driver) since the position information typically gets written into an
        external file on the first run and is available only on the second run.
    \item You have to switch off automatic bounding bound computations. The
        reason is that the node in the other picture should not influence the
        size of the bounding box of the current picture. You should say
        |\pgfusepath{use as bounding box}| before using a coordinate in another
        picture.
\end{enumerate}


\subsection{Special Nodes}

There are several special nodes that are always defined and which you should
not attempt to redefine.

\begin{predefinednode}{current bounding box}
    This node is of shape |rectangle|. Unlike normal nodes, its size changes
    constantly and always reflects the size of the bounding box of the current
    picture. This means that, for instance, that
    %
\begin{codeexample}[code only]
\pgfpointanchor{current bounding box}{south east}
\end{codeexample}
    %
    returns the lower left corner of the bounding box of the current picture.
\end{predefinednode}

\begin{predefinednode}{current path bounding box}
    This node is also of shape |rectangle|. Its size is the size of the
    bounding box of the current path.
\end{predefinednode}

\begin{predefinednode}{current subpath start}
    This node is of shape |coordinate| and is at the beginning of the current
    subpath. This is the position of the last move-to operation.
\end{predefinednode}

\begin{predefinednode}{current page}
    This node is inside a virtual remembered picture. The size of this node is
    the size of the current page. This means that if you create a remembered
    picture and inside this picture you reference an anchor of this node, you
    reference an absolute position on the page. To demonstrate the effect, the
    following code puts some text in the lower left corner of the current page.
    Note that this works only if the backend driver supports it, otherwise the
    text is inserted right here.
    %
{%
\pgfrememberpicturepositiononpagetrue%
\begin{pgfpicture}
    \pgfusepath{use as bounding box}
    \pgftransformshift{\pgfpointanchor{current page}{south west}}
    \pgftransformshift{\pgfpoint{1cm}{1cm}}
    \pgftext[left,base]{
        \textcolor{red}{
            Text absolutely positioned in
            the lower left corner.}
    }
\end{pgfpicture}
}%
\begin{codeexample}[code only]
\pgfrememberpicturepositiononpagetrue
\begin{pgfpicture}
  \pgfusepath{use as bounding box}
  \pgftransformshift{\pgfpointanchor{current page}{south west}}
  \pgftransformshift{\pgfpoint{1cm}{1cm}}
  \pgftext[left,base]{
    \textcolor{red}{
      Text absolutely positioned in
      the lower left corner.}
  }
\end{pgfpicture}
\end{codeexample}
    %
\end{predefinednode}

There is also an option that allows you to create new special nodes quite
similar to the above:
%
\begin{key}{/pgf/local bounding box=\meta{node name}}
\keyalias{tikz}
    This defines a new node \meta{node name} whose size is the bounding box
    around all objects in the current scope starting at the position where this
    option was given. After the end of the scope, the \meta{node name} is still
    available. You can use this option to keep track of the size of a certain
    area. Note that excessive use of this option (keeping track of dozens of
    bounding boxes at the same time) will slow things down.
    %
\begin{codeexample}[preamble={\usetikzlibrary{scopes}}]
\begin{tikzpicture}
  \draw [help lines] (0,0) grid (3,2);
  { [local bounding box=outer box]
    \draw (1,1) circle (.5) [local bounding box=inner box] (2,2) circle (.5);
  }
  \draw      (outer box.south west) rectangle (outer box.north east);
  \draw[red] (inner box.south west) rectangle (inner box.north east);
\end{tikzpicture}
\end{codeexample}
    %
\end{key}


\subsection{Declaring New Shapes}

There are only three predefined shapes, see
Section~\ref{section-predefined-shapes}, so there must be some way of defining
new shapes. Defining a shape is, unfortunately, a not-quite-trivial process.
The reason is that shapes need to be both very flexible (their size will vary
greatly according to circumstances) and they need to be constructed reasonably
``fast''. \pgfname\ must be able to handle pictures with several hundreds of
nodes and documents with thousands of nodes in total. It would not do if
\pgfname\ had to compute and store, say, dozens of anchor positions for every
node.


\subsubsection{What Must Be Defined For a Shape?}

In order to define a new shape, you must provide:
%
\begin{itemize}
    \item a \emph{shape name},
    \item code for computing the  \emph{saved anchors} and \emph{saved
    dimensions},
    \item code for computing \emph{anchor} positions in terms of the saved
        anchors,
    \item optionally code for the \emph{background path} and \emph{foreground
        path},
    \item optionally code for \emph{things to be drawn before or behind} the
        background and foreground paths.
    \item optionally a list of node parts.
\end{itemize}


\subsubsection{Normal Anchors Versus Saved Anchors}

Anchors  are special places in a shape. For example, the |north east| anchor,
which is a normal anchor, lies at the upper right corner of the |rectangle|
shape, as does |\northeast|, which is a saved anchor. The difference is the
following: \emph{saved anchors are computed and stored for each node, anchors
are only computed as needed.} The user only has access to the normal anchors,
but a normal anchor can just ``copy'' or ``pass through'' the location of a
saved anchor.

The idea behind all this is that a shape can declare a very large number of
normal anchors, but when a node of this shape is created, these anchors are not
actually computed. However, this causes a problem: When we wish to reference an
anchor of a node at some later time, we must still be able to compute the
position of the anchor. For this, we may need a lot of information: What was
the transformation matrix that was in force when the node was created? What was
the size of the text box? What were the values of the different separation
dimensions? And so on.

To solve this problem, \pgfname\ will always compute the locations of all
\emph{saved anchors} and store these positions. Then, when an normal anchor
position is requested later on, the anchor position can be given just from
knowing where the locations of the saved anchors are.

As an example, consider the |rectangle| shape. For this shape two anchors are
saved: The |\northeast| corner and the |\southwest| corner. A normal anchor
like |north west| can now easily be expressed in terms of these coordinates:
Take the $x$-position of the |\southwest| point  and the $y$-position of the
|\northeast| point. The |rectangle| shape currently defines 13 normal anchors,
but needs only two saved anchors. Adding new anchors like a  |south south east|
anchor would not increase the memory and computation requirements of pictures.

All anchors (both saved and normal) are specified in a local \emph{shape
coordinate space}. This is also true for the background and foreground paths.
The |\pgfnode| macro will automatically apply appropriate transformations to
the coordinates so that the shape is shifted to the right anchor or otherwise
transformed.


\subsubsection{Command for Declaring New Shapes}

The following command declares a new shape:
%
\begin{command}{\pgfdeclareshape\marg{shape name}\marg{shape specification}}
    This command declares a new shape named \meta{shape name}. The shape name
    can later be used in commands like |\pgfnode|.

    The \meta{shape specification} is some \TeX\ code containing calls to
    special commands that are only defined inside the \meta{shape
    specification} (similarly to commands like |\draw| that are only available
    inside the |{tikzpicture}| environment).

    \example Here is the code of the |coordinate| shape:
    %
\begin{codeexample}[code only]
\pgfdeclareshape{coordinate}
{
  \savedanchor\centerpoint{%
    \pgf@x=.5\wd\pgfnodeparttextbox%
    \pgf@y=.5\ht\pgfnodeparttextbox%
    \advance\pgf@y by -.5\dp\pgfnodeparttextbox%
  }
  \anchor{center}{\centerpoint}
  \anchorborder{\centerpoint}
}
\end{codeexample}

    The special commands are explained next. In the examples given for the
    special commands a new shape will be constructed, which we might call
    |simple rectangle|. It should behave like the normal rectangle shape, only
    without bothering about the fine details like inner and outer separations.
    The skeleton for the shape is the following.
    %
\begin{codeexample}[code only]
\pgfdeclareshape{simple rectangle}{
  ...
}
\end{codeexample}

    \begin{command}{\nodeparts\marg{list of node parts}}
        This command declares which parts make up nodes of this shape. A
        \emph{node part} is a (possibly empty) text label that is drawn when a
        node of the shape is created.

        By default, a shape has just one node part called |text|. However,
        there can be several node parts. For example, the |circle split| shape
        has two parts: the |text| part, which shows that the upper text, and a
        |lower| part, which shows the lower text. For the |circle split| shape
        the |\nodeparts| command was called with the argument |{text,lower}|.

        When a multipart node is created, the text labels are drawn in the
        sequences listed in the \meta{list of node parts}. For each node part,
        you must have declared one anchor and the \TeX-box of the part is
        placed at this anchor. For a node part called |XYZ| the \TeX-box
        |\pgfnodepartXYZbox| is placed at anchor |XYZ|.
    \end{command}

    \begin{command}{\savedanchor\marg{command}\marg{code}}
        This command declares a saved anchor. The argument \meta{command}
        should be a \TeX\ macro name like |\centerpoint|.

        The \meta{code} will be executed each time |\pgfnode| (or
        |\pgfmultipartnode|) is called to  create a node of the shape
        \meta{shape name}. When the \meta{code} is executed, the \TeX-boxes of
        the node parts will contain the text labels of the node. Possibly,
        these box are void. For example, if there is just a |text| part, the
        node |\pgfnodeparttextbox| will be set up when the \meta{code} is
        executed.

        The \meta{code} can use the width, height, and depth of the box(es) to
        compute the location of the saved anchor. In addition, the \meta{code}
        can take into account the values of dimensions like |\pgfshapeminwidth|
        or |\pgfshapeinnerxsep|. Furthermore, the \meta{code} can take into
        consideration the values of any further shape-specific variables that
        are set at the moment when |\pgfnode| is called.

        The net effect of the \meta{code} should be to set the two \TeX\
        dimensions |\pgf@x| and |\pgf@y|. One way to achieve this is to say
        |\pgfpoint{|\meta{x value}|}{|\meta{y value}|}| at the end of the
        \meta{code}, but you can also just set these variables. The values that
        |\pgf@x| and |\pgf@y| have after the code has been executed, let us
        call them $x$ and $y$, will be recorded and stored together with the
        node that is created by the command |\pgfnode|.

        The macro \meta{command} is defined to be |\pgfpoint{|$x$|}{|$y$|}|.
        However, the \meta{command} is only locally defined while anchor
        positions are being computed. Thus, it is possible to use very simple
        names for \meta{command}, like |\center| or |\a|, without causing a
        name-clash. (To be precise, very simple \meta{command} names will clash
        with existing names, but only locally inside the computation of anchor
        positions; and we do not need the normal |\center| command during these
        computations.)

        For our |simple rectangle| shape, we will need only one saved anchor:
        The upper right corner. The lower left corner could either be the
        origin or the ``mirrored'' upper right corner, depending on whether we
        want the text label to have its lower left corner at the origin or
        whether the text label should be centered on the origin. Either will be
        fine, for the final shape this will make no difference since the shape
        will be shifted anyway. So, let us assume that the text label is
        centered on the origin (this will be specified later on using the
        |text| anchor). We get the following code for the upper right corner:
        %
\begin{codeexample}[code only]
\savedanchor{\upperrightcorner}{
  \pgf@y=.5\ht\pgfnodeparttextbox % height of the box, ignoring the depth
  \pgf@x=.5\wd\pgfnodeparttextbox % width of the box
}
\end{codeexample}

        If we wanted to take, say, the |\pgfshapeminwidth| into account, we
        could use the following code:
        %
\begin{codeexample}[code only]
\savedanchor{\upperrightcorner}{
  \pgf@y=.\ht\pgfnodeparttextbox % height of the box
  \pgf@x=.\wd\pgfnodeparttextbox % width of the box
  \setlength{\pgf@xa}{\pgfshapeminwidth}
  \ifdim\pgf@x<.5\pgf@xa
    \pgf@x=.5\pgf@xa
  \fi
}
\end{codeexample}
        %
        Note that we could not have written |.5\pgfshapeminwidth| since the
        minimum width is stored in a ``plain text macro'', not as a real
        dimension. So if |\pgfshapeminwidth| depth were 2cm, writing
        |.5\pgfshapeminwidth| would yield the same as |.52cm|.

        In the ``real'' |rectangle| shape the code is somewhat more complex,
        but you get the basic idea.
    \end{command}
    %
    \begin{command}{\saveddimen\marg{command}\marg{code}}
        This command is similar to |\savedanchor|, only instead of setting
        \meta{command} to |\pgfpoint{|$x$|}{|$y$|}|, the \meta{command} is set
        just to (the value of) $x$.

        In the |simple rectangle| shape we might use a saved dimension to store
        the depth of the shape box.
        %
\begin{codeexample}[code only]
\saveddimen{\depth}{
  \pgf@x=\dp\pgfnodeparttextbox
}
\end{codeexample}
    \end{command}
    %
    \begin{command}{\savedmacro\marg{command}\marg{code}}
        This command is similar to |\saveddimen|, only at some point in
        \meta{code}, \meta{command} should be defined appropriately, (this
        could be a value, or some text).

        In the |regular polygon| shape, a saved macro is used to store the
        number of sides of the polygon.
        %
\begin{codeexample}[code only]
\savedmacro{\sides}{\let\sides\pgfpolygonsides}
\end{codeexample}
    \end{command}
    %
    \begin{command}{\anchor\marg{name}\marg{code}}
        This command declares an anchor named \meta{name}. Unlike for saved
        anchors, the \meta{code} will not be executed each time a node is
        declared. Rather, the \meta{code} is only executed when the anchor is
        specifically requested; either for anchoring the node during its
        creation or as a position in the shape referenced later on.

        The \meta{name} is a quite arbitrary string that is not ``passed down''
        to the system level. Thus, names like |south| or |1| or |::| would all
        be fine.

        A saved anchor is not automatically also a normal anchor. If you wish
        to give the users access to a saved anchor you must declare a normal
        anchor that just returns the position of the saved anchor.

        When the \meta{code} is executed, all saved anchor macros will be
        defined. Thus, you can reference them in your \meta{code}. The effect
        of the \meta{code} should be to set the values of |\pgf@x| and |\pgf@y|
        to the coordinates of the anchor.

        Let us consider some example for the |simple rectangle| shape. First,
        we would like to make the upper right corner publicly available, for
        example as |north east|:
        %
\begin{codeexample}[code only]
\anchor{north east}{\upperrightcorner}
\end{codeexample}

        The |\upperrightcorner| macro will set |\pgf@x| and |\pgf@y| to the
        coordinates of the upper right corner. Thus, |\pgf@x| and |\pgf@y| will
        have exactly the right values at the end of the anchor's code.

        Next, let us define a |north west| anchor. For this anchor, we can
        negate the |\pgf@x| variable:
        %
\begin{codeexample}[code only]
\anchor{north west}{
  \upperrightcorner
  \pgf@x=-\pgf@x
}
\end{codeexample}

        Finally, it is a good idea to always define a |center| anchor, which
        will be the default location for a shape.
        %
\begin{codeexample}[code only]
\anchor{center}{\pgfpointorigin}
\end{codeexample}

        You might wonder whether we should not take into consideration that the
        node is not placed at the origin, but has been shifted somewhere.
        However, the anchor positions are always specified in the shape's
        ``private'' coordinate system. The ``outer'' transformation that has
        been applied to the shape upon its creation is applied automatically to
        the coordinates returned by the anchor's \meta{code}.

        Our |simple rectangle| only has one text label (node part) called
        |text|. This is the default situation, so we do not need to do
        anything. For the |text| node part we must set up a |text| anchor. Upon
        creation of a node, this anchor will be made to coincide with the left
        endpoint of the baseline of the text label (within the private
        coordinate system of the shape). By default, the |text| anchor is at
        the origin, but you may change this. For example, we would say
        %
\begin{codeexample}[code only]
\anchor{text}{%
  \upperrightcorner%
  \pgf@x=-\pgf@x%
  \pgf@y=-\pgf@y%
}
\end{codeexample}
        to center the text label on the origin in the shape coordinate space.
        Note that we could \emph{not} have written the following:
        %
\begin{codeexample}[code only]
\anchor{text}{\pgfpoint{-.5\wd\pgfnodeparttextbox}{-.5\ht\pgfnodeparttextbox}}
\end{codeexample}
        %
        Do you see why this is wrong? The problem is that the box
        |\pgfnodeparttextbox| will most likely not have the correct size when
        the anchor is computed. After all, the anchor position might be
        recomputed at a time when several other nodes have been created.

        If a shape has several node parts, we would have to define an anchor
        for each part.
  \end{command}

  \begin{command}{\deferredanchor\marg{name}\marg{code}}
        This command declares an anchor named \meta{name}. It works like
        |\anchor|. However, unlike for anchors declared by |\anchor|,
        \meta{name} will \emph{not} be expanded during the shape declaration
        (i.e.\ not during |\pgfdeclareshape|). Rather, the \meta{name} is
        expanded when the \emph{node} is actually used (with |\pgfnode| or more
        likely with |\node|). This may be useful if the anchor name is context
        dependent (depending, for example, on the value of a key).
        %
\begin{codeexample}[code only]
\makeatletter
\def\foo{foo}
\pgfdeclareshape{simple shape}{%
  \savedanchor{\center}{%
    \pgfpointorigin}
  \anchor{center}{\center}
  \savedanchor{\anchorfoo}{%
    \pgf@x=1cm
    \pgf@y=0cm}
  \deferredanchor{anchor \foo}{\anchorfoo}}

\begin{tikzpicture}
  \node[simple shape] (Test1) at (0,0) {};
  \fill (Test1.anchor foo) circle (2pt) node[below] {anchor foo anchor};
  %
  \def\foo{bar}
  \node[simple shape] (Test2) at (2,2) {};
  \fill (Test2.anchor bar) circle (2pt) node[below] {anchor bar anchor};
\end{tikzpicture}
\end{codeexample}
    \end{command}
    %
    \begin{command}{\anchorborder\marg{code}}
        A \emph{border anchor} is an anchor point on the border of the shape.
        What exactly is considered as the ``border'' of the shape depends on
        the shape.

        When the user requests a point on the border of the shape using the
        |\pgfpointshapeborder| command, the \meta{code} will be executed to
        discern this point. When the execution of  the \meta{code} starts, the
        dimensions |\pgf@x| and |\pgf@y| will have been set to a location $p$
        in the shape's coordinate system, and relative to the anchor |center|.
        Note that |\pgfpointshapeborder| will produce an error if the shape does
        not contain the |center| anchor.
        
        It is now the job of the \meta{code} to set up |\pgf@x| and |\pgf@y|
        such that they specify the point on the shape's border that lies on a
        straight line from the shape's center to the point $p$. Usually, this is
        a somewhat complicated computation, involving many case distinctions and
        some basic math. Note that the output coordinates must be returned in the
        shape's coordinate system, \emph{no longer} relative to the |center|
        anchor. While these different points of reference are only noticeable if
        the |center| anchor is not at the origin of the shape's coordinate system,
        it implies that ``doing nothing'' as a border anchor, i.e., returning the
        point that was fed to |\pgfpointshapeborder| requires adding the |center|
        anchor to the input coordinates.

        For our |simple rectangle| we must compute a point on the border of a
        rectangle whose one corner is the origin (ignoring the depth for
        simplicity) and whose other corner is |\upperrightcorner|. The
        following code might be used:
        %
\begin{codeexample}[code only]
\anchorborder{%
  % Call a function that computes a border point. Since this
  % function will modify dimensions like \pgf@x, we must move them to
  % other dimensions.
  \@tempdima=\pgf@x
  \@tempdimb=\pgf@y
  \pgfpointborderrectangle{\pgfpoint{\@tempdima}{\@tempdimb}}{\upperrightcorner}
}
\end{codeexample}
    \end{command}
    %
    \begin{command}{\backgroundpath\marg{code}}
        This command specifies the path that ``makes up'' the background of the
        shape. Note that the shape cannot prescribe what is going to happen
        with the path: It might be drawn, shaded, filled, or even thrown away.
        If you want to specify that something should ``always'' happen when
        this shape is drawn (for example, if the shape is a stop-sign, we
        \emph{always} want it to be filled with a red color), you can use
        commands like |\beforebackgroundpath|, explained below.

        When the \meta{code} is executed, all saved anchors will be in effect.
        The \meta{code} should contain path construction commands.

        For our |simple rectangle|, the following code might be used:
        %
\begin{codeexample}[code only]
\backgroundpath{
  \pgfpathrectanglecorners
    {\upperrightcorner}
    {\pgfpointscale{-1}{\upperrightcorner}}
}
\end{codeexample}
        %
        As the name suggests, the background path is used ``behind'' the text
        labels. Thus, this path is used first, then the text labels are drawn,
        possibly obscuring part of the path.
    \end{command}
    %
    \begin{command}{\foregroundpath\marg{code}}
        This command works like |\backgroundpath|, only it is invoked after the
        text labels have been drawn. This means that this path can possibly
        obscure (part of) the text labels.
    \end{command}
    %
    \begin{command}{\behindbackgroundpath\marg{code}}
        Unlike the previous two commands, \meta{code} should not only construct
        a path, it should also use this path in whatever way is appropriate.
        For example, the \meta{code} might fill some area with a uniform color.

        Whatever the \meta{code} does, it does it first. This means that any
        drawing done by \meta{code} will be even behind the background path.

        Note that the \meta{code} is protected with a |{pgfscope}|.
    \end{command}
    %
    \begin{command}{\beforebackgroundpath\marg{code}}
        This command works like |\behindbackgroundpath|, only the \meta{code}
        is executed after the background path has been used, but before the
        texts label are drawn.
    \end{command}
    %
    \begin{command}{\behindforegroundpath\marg{code}}
        The \meta{code} is executed after the text labels have been drawn, but
        before the foreground path is used.
    \end{command}
    %
    \begin{command}{\beforeforegroundpath\marg{code}}
        This \meta{code} is executed at the very end.
    \end{command}
    %
    \begin{command}{\inheritsavedanchors|[from=|\marg{another shape name}|]|}
        This command allows you to inherit the code for saved anchors from
        \meta{another shape name}. The idea is that if you wish to create a new
        shape that is just a small modification of a another shape, you can
        recycle the code used for \meta{another shape name}.

        The effect of this command is the same as if you had called
        |\savedanchor| and |\saveddimen| for each saved anchor or saved
        dimension declared in \meta{another shape name}. Thus, it is not
        possible to ``selectively'' inherit only some saved anchors, you always
        have to inherit all saved anchors from another shape. However, you can
        inherit the saved anchors of more than one shape by calling this
        command several times.
    \end{command}
    %
    \begin{command}{\inheritbehindbackgroundpath|[from=|\marg{another shape name}|]|}
        This command can be used to inherit the code used for the drawings
        behind the background path from \meta{another shape name}.
    \end{command}
    %
    \begin{command}{\inheritbackgroundpath|[from=|\marg{another shape name}|]|}
        Inherits the background path code from \meta{another shape name}.
    \end{command}
    %
    \begin{command}{\inheritbeforebackgroundpath|[from=|\marg{another shape name}|]|}
        Inherits the before background path code from \meta{another shape
        name}.
    \end{command}
    %
    \begin{command}{\inheritbehindforegroundpath|[from=|\marg{another shape name}|]|}
        Inherits the behind foreground path code from \meta{another shape
        name}.
    \end{command}
    %
    \begin{command}{\inheritforegroundpath|[from=|\marg{another shape name}|]|}
        Inherits the foreground path code from \meta{another shape name}.
    \end{command}
    %
    \begin{command}{\inheritbeforeforegroundpath|[from=|\marg{another shape name}|]|}
        Inherits the before foreground path code from \meta{another shape
        name}.
    \end{command}
    %
    \begin{command}{\inheritanchor|[from=|\marg{another shape name}|]|\marg{name}}
        Inherits the code of one specific anchor named \meta{name} from
        \meta{another shape name}. Thus, unlike saved anchors, which must be
        inherited collectively, normal anchors can and must be inherited
        individually.
    \end{command}
    %
    \begin{command}{\inheritanchorborder|[from=|\marg{another shape name}|]|}
        Inherits the border anchor code from \meta{another shape name}.
    \end{command}

    The following example shows how a shape can be defined that relies heavily
    on inheritance:
    %
\makeatletter
\begin{codeexample}[
    preamble={\usetikzlibrary{shapes.geometric}},
    pre={\makeatletter},
]
\pgfdeclareshape{document}{
  \inheritsavedanchors[from=rectangle] % this is nearly a rectangle
  \inheritanchorborder[from=rectangle]
  \inheritanchor[from=rectangle]{center}
  \inheritanchor[from=rectangle]{north}
  \inheritanchor[from=rectangle]{south}
  \inheritanchor[from=rectangle]{west}
  \inheritanchor[from=rectangle]{east}
  % ... and possibly more
  \backgroundpath{% this is new
    % store lower right in xa/ya and upper right in xb/yb
    \southwest \pgf@xa=\pgf@x \pgf@ya=\pgf@y
    \northeast \pgf@xb=\pgf@x \pgf@yb=\pgf@y
    % compute corner of ``flipped page''
    \pgf@xc=\pgf@xb \advance\pgf@xc by-5pt % this should be a parameter
    \pgf@yc=\pgf@yb \advance\pgf@yc by-5pt
    % construct main path
    \pgfpathmoveto{\pgfpoint{\pgf@xa}{\pgf@ya}}
    \pgfpathlineto{\pgfpoint{\pgf@xa}{\pgf@yb}}
    \pgfpathlineto{\pgfpoint{\pgf@xc}{\pgf@yb}}
    \pgfpathlineto{\pgfpoint{\pgf@xb}{\pgf@yc}}
    \pgfpathlineto{\pgfpoint{\pgf@xb}{\pgf@ya}}
    \pgfpathclose
    % add little corner
    \pgfpathmoveto{\pgfpoint{\pgf@xc}{\pgf@yb}}
    \pgfpathlineto{\pgfpoint{\pgf@xc}{\pgf@yc}}
    \pgfpathlineto{\pgfpoint{\pgf@xb}{\pgf@yc}}
    \pgfpathlineto{\pgfpoint{\pgf@xc}{\pgf@yc}}
 }
}\hskip-1.2cm
\begin{tikzpicture}
  \node[shade,draw,shape=document,inner sep=2ex] (x) {Remark};
  \node[fill=yellow!80!black,draw,ellipse,double]
    at ([shift=(-80:3cm)]x) (y) {Use Case};

  \draw[dashed] (x) -- (y);
\end{tikzpicture}
\end{codeexample}
    %
\end{command}


%%% Local Variables:
%%% mode: latex
%%% TeX-master: "pgfmanual"
%%% End: