summaryrefslogtreecommitdiff
path: root/graphics/pgf/base/doc/text-en/pgfmanual-en-base-scopes.tex
blob: 51cce0ed8ef08ff4d55bccf0b459fa81a83c8ec6 (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
% 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[Hierarchical Structures: Package, Environments, Scopes, and Text]
        {Hierarchical Structures:\\
         Package, Environments, Scopes, and Text}

\subsection{Overview}

\pgfname\ uses two kinds of hierarchical structuring: First, the package itself
is structured hierarchically, consisting of different packages that are built
on top of each other. Second, \pgfname\ allows you to structure your graphics
hierarchically using environments and scopes.


\subsubsection{The Hierarchical Structure of the Package}

The \pgfname\ system consists of several layers:
%
\begin{description}
    \item[System layer.]
        The lowest layer is called the \emph{system layer}, though it might
        also be called ``driver layer'' or perhaps ``backend layer''. Its job
        is to provide an abstraction of the details of which driver is used to
        transform the |.dvi| file. The system layer is implemented by the
        package |pgfsys|, which will load appropriate driver files as needed.

        The system layer is documented in Part~\ref{part-system}.
    \item[Basic layer.]
        The basic layer is loaded by the package |pgfcore| and subsequent use
        of the command |\usepgfmodule| to load additional modules of the basic
        layer.

        The basic layer is documented in the present part.
    \item[Frontend layer.]
        The frontend layer is not loaded by a single package. Rather, different
        packages, like \tikzname\ or \textsc{pgfpict2e}, are different
        frontends to the basic layer.

        The \tikzname\ frontend is documented in Part~\ref{part-tikz}.
\end{description}

Each layer will automatically load the necessary files of the layers below it.

In addition to the packages of these layers, there are also some library
packages. These packages provide additional definitions of things like new
arrow tips or new plot handlers.

The library packages are documented in Part~\ref{part-libraries}.


\subsubsection{The Hierarchical Structure of Graphics}

Graphics in \pgfname\ are typically structured hierarchically. Hierarchical
structuring can be used to identify groups of graphical elements that are to be
treated ``in the same way''. For example, you might group together a number of
paths, all of which are to be drawn in red. Then, when you decide later on that
you like them to be drawn in, say, blue, all you have to do is to change the
color once.

The general mechanism underlying hierarchical structuring is known as
\emph{scoping} in computer science. The idea is that all changes to the general
``state'' of the graphic that are done inside a scope are local to that scope.
So, if you change the color inside a scope, this does not affect the color used
outside the scope. Likewise, when you change the line width in a scope, the
line width outside is not changed, and so on.

There are different ways of starting and ending scopes of graphic parameters.
Unfortunately, these scopes are sometimes ``in conflict'' with each other and
it is sometimes not immediately clear which scopes apply. In essence, the
following scoping mechanisms are available:
%
\begin{enumerate}
    \item The ``outermost'' scope supported by \pgfname\ is the |{pgfpicture}|
        environment. All changes to the graphic state done inside a
        |{pgfpicture}| are local to that picture.

        In general, it is \emph{not} possible to set graphic parameters
        globally outside any |{pgfpicture}| environments. Thus, you can
        \emph{not} say |\pgfsetlinewidth{1pt}| at the beginning of your
        document to have a default line width of one point. Rather, you have to
        (re)set all graphic parameters inside each |{pgfpicture}|. (If this is
        too bothersome, try defining some macro that does the job for you.)
    \item Inside a |{pgfpicture}| you can use a |{pgfscope}| environment to
        keep changes of the graphic state local to that environment.

        The effect of commands that change the graphic state are local to the
        current |{pgfscope}|, but not always to the current \TeX\ group. Thus,
        if you open a \TeX\ group (some text in curly braces) inside a
        |{pgfscope}|, and if you change, for example, the dash pattern, the
        effect of this changed dash pattern will persist till the end of the
        |{pgfscope}|.

        Unfortunately, this is not always the case. \emph{Some} graphic
        parameters only persist till the end of the current \TeX\ group. For
        example, when you use |\pgfsetarrows| to set the arrow tip inside a
        \TeX\ group, the effect lasts only till the end of the current \TeX\
        group.
    \item Some graphic parameters are not scoped by |{pgfscope}| but
        ``already'' by \TeX\ groups. For example, the effect of coordinate
        transformation commands is always local to the current \TeX\ group.

        Since every |{pgfscope}| automatically creates a \TeX\ group, all
        graphic parameters that are local to the current \TeX\ group are also
        local to the current |{pgfscope}|.
    \item Some graphic parameters can only be scoped using \TeX\ groups, since
        in some situations it is not possible to introduce a |{pgfscope}|. For
        example, a path always has to be completely constructed and used in the
        same |{pgfscope}|. However, we might wish to have different coordinate
        transformations apply to different points on the path. In this case, we
        can use \TeX\ groups to keep the effect local, but we could not use
        |{pgfscope}|.
    \item The |\pgftext| command can be used to create a scope in which \TeX\
        ``escapes back'' to normal \TeX\ mode. The text passed to the
        |\pgftext| is ``heavily guarded'' against having any effect on the
        scope in which it is used. For example, it is possible to use another
        |{pgfpicture}| environment inside the argument of |\pgftext|.
\end{enumerate}

Most of the complications can be avoided if you stick to the following
rules:
%
\begin{itemize}
    \item Give graphic commands only inside |{pgfpicture}| environments.
    \item Use |{pgfscope}| to structure graphics.
    \item Do not use \TeX\ groups inside graphics, \emph{except} for keeping
        the effect of coordinate transformations local.
\end{itemize}


\subsection{The Hierarchical Structure of the Package}

Before we come to the structuring commands provided by \pgfname\ to structure
your graphics, let us first have a look at the structure of the package itself.


\subsubsection{The Core Package}

To use \pgfname, include the following package:

\begin{package}{pgfcore}
    This package loads the complete core of the ``basic layer'' of \pgfname,
    but not any modules. That is, it will load all of the commands described in
    the current part of this manual, but it will not load frontends like
    \tikzname. It will also load the system layer. To load additional modules,
    use the |\usepgfmodule| command explained below.
\end{package}

The following package is just a convenience.

\begin{package}{pgf}
    This package loads the |pgfcore| and the two modules |shapes| and |plot|.

    In \LaTeX, the package takes two options:
    %
    \begin{packageoption}{draft}
        When this option is set, all images will be replaced by empty
        rectangles. This can speedup compilation.
    \end{packageoption}

    \begin{packageoption}{version=\meta{version}}
        Indicates that the commands of version \meta{version} need to be
        defined. If you set \meta{version} to |0.65|, then a large bunch of
        ``compatibility commands'' are loaded. If you set \meta{version} to
        |0.96|, then these compatibility commands will not be loaded.

        If this option is not given at all, then the commands of all versions
        are defined.
    \end{packageoption}
\end{package}


\subsubsection{The Modules}

\begin{command}{\usepgfmodule\marg{module names}}
    Once the core has been loaded, you can use this command to load further
    modules. The modules in the \meta{module names} list should be separated by
    commas. Instead of curly braces, you can also use square brackets, which is
    something Con\TeX t users will like. If you try to load a module a second
    time, nothing will happen.

    \example |\usepgfmodule{matrix,shapes}|

    What this command does is to load the file
    |pgfmodule|\meta{module}|.code.tex| for each \meta{module} in the list of
    \meta{module names}. Thus, to write your own module, all you need to do is
    to place a file of the appropriate name somewhere \TeX\ can find it.
    \LaTeX, plain \TeX, and Con\TeX t users can then use your library.
\end{command}

The following modules are available for use with |pgfcore|: \todosp{In the
meantime there are some more modules. Also mention them here?}
%
\begin{itemize}
    \item The |plot| module provides commands for plotting functions. The
        commands are explained in Section~\ref{section-plots}.
    \item The |shapes| module provides commands for drawing shapes and nodes.
        These commands are explained in Section~\ref{section-shapes}.
    \item The |decorations| module provides commands for adding decorations to
        paths. These commands are explained in
        Section~\ref{section-base-decorations}.
    \item The |matrix| module provides the |\pgfmatrix| command. The commands
        are documented in Section~\ref{section-base-matrices}.
\end{itemize}


\subsubsection{The Library Packages}

There is a special command for loading library packages. The difference between
a library and module is the following: A library just defines additional
objects using the basic layer, whereas a module adds completely new
functionality. For instance, a |decorations| library defines additional
decorations, while a decoration module defines the whole code for handling
decorations.

\begin{command}{\usepgflibrary\marg{list of libraries}}
    Use this command to load further libraries. The list of libraries should
    contain the names of libraries separated by commas. Instead of curly
    braces, you can also use square brackets. If you try to load a library a
    second time, nothing will happen.

    \example |\usepgflibrary{arrows}|

    This command causes the file |pgflibrary|\meta{library}|.code.tex| to be
    loaded for each \meta{library} in the \meta{list of libraries}. This means
    that in order to write your own library file, place a file of the
    appropriate name somewhere where \TeX\ can find it. \LaTeX, plain \TeX, and
    Con\TeX t users can then use your library.

    You should also consider adding a \tikzname\ library that simply includes
    your \pgfname\ library.
\end{command}


\subsection{The Hierarchical Structure of the Graphics}

\subsubsection{The Main Environment}

Most, but not all, commands of the \pgfname\ package must be given within a
|{pgfpicture}| environment. The only commands that (must) be given outside are
commands having to do with including images (like |\pgfuseimage|) and with
inserting complete shadings (like |\pgfuseshading|). However, just to keep life
entertaining, the |\pgfshadepath| command must be given \emph{inside} a
|{pgfpicture}| environment.

\begin{environment}{{pgfpicture}}
    This environment will insert a \TeX\ box containing the graphic drawn by
    the \meta{environment contents} at the current position.


    \medskip
    \textbf{The size of the bounding box.}
    The size of the box is determined in the following manner: While \pgfname\
    parses the \meta{environment contents}, it keeps track of a bounding box
    for the graphic. Essentially, this bounding box is the smallest box that
    contains all coordinates mentioned in the graphics. Some coordinates may be
    ``mentioned'' by \pgfname\ itself; for example, when you add circle to the
    current path, the support points of the curve making up the circle are also
    ``mentioned'' despite the fact that you will not ``see'' them in your code.

    Once the \meta{environment contents} have been parsed completely, a \TeX\
    box is created whose size is the size of the computed bounding box and this
    box is inserted at the current position.
    %
\begin{codeexample}[]
Hello \begin{pgfpicture}
  \pgfpathrectangle{\pgfpointorigin}{\pgfpoint{2ex}{1ex}}
  \pgfusepath{stroke}
\end{pgfpicture} World!
\end{codeexample}

    Sometimes, you may need more fine-grained control over the size of the
    bounding box. For example, the computed bounding box may be too large or
    you intensionally wish the box to be ``too small''. In these cases, you can
    use the command |\pgfusepath{use as bounding box}|, as described in
    Section~\ref{section-using-bb}.


    \medskip
    \textbf{The baseline of the bounding box.}
    When the box containing the graphic is inserted into the normal text, the
    baseline of the graphic is normally at the bottom of the graphic. For this
    reason, the following two sets of code lines have the same effect, despite
    the fact that the second graphic uses ``higher'' coordinates than the
    first:
    %
\begin{codeexample}[]
Rectangles \begin{pgfpicture}
  \pgfpathrectangle{\pgfpointorigin}{\pgfpoint{2ex}{1ex}}
  \pgfusepath{stroke}
\end{pgfpicture} and \begin{pgfpicture}
  \pgfpathrectangle{\pgfpoint{0ex}{1ex}}{\pgfpoint{2ex}{1ex}}
  \pgfusepath{stroke}
\end{pgfpicture}.
\end{codeexample}

    You can change the baseline using the |\pgfsetbaseline| command, see below.
    %
\begin{codeexample}[]
Rectangles \begin{pgfpicture}
  \pgfpathrectangle{\pgfpointorigin}{\pgfpoint{2ex}{1ex}}
  \pgfusepath{stroke}
  \pgfsetbaseline{0pt}
\end{pgfpicture} and \begin{pgfpicture}
  \pgfpathrectangle{\pgfpoint{0ex}{1ex}}{\pgfpoint{2ex}{1ex}}
  \pgfusepath{stroke}
  \pgfsetbaseline{0pt}
\end{pgfpicture}.
\end{codeexample}


    \medskip
    \textbf{Including text and images in a picture.}
    You cannot directly include text and images in a picture. Thus, you should
    \emph{not} simply write some text in a |{pgfpicture}| or use a command like
    |\includegraphics| or even |\pgfimage|. In all these cases, you need to
    place the text inside a |\pgftext| command. This will ``escape back'' to
    normal \TeX\ mode, see Section~\ref{section-text-command} for details.


    \medskip
    \textbf{Remembering a picture position for later reference.}
    After a picture has been typeset, its position on the page is normally
    forgotten by \pgfname\ and also by \TeX. This means that is not possible to
    reference a node in this picture later on. In particular, it is normally
    impossible to draw lines between nodes in different pictures automatically.

    In order to make \pgfname\ ``remember'' a picture, the \TeX-if
    |\ifpgfrememberpicturepositiononpage| should be set to |true|. It is only
    important that this \TeX-if is |true| at the end of the
    |{pgfpicture}|-en\-vi\-ron\-ment, so you can switch it on inside the
    environment. However, you can also just switch it on globally, then the
    positions of all pictures are remembered.

    There are several reasons why the remembering is not switched on by
    default. First, it does not work for all backend drivers (currently, it
    works only for pdf\TeX). Second, it requires two passes of \TeX\ over the
    file; on the first pass all positions will be wrong. Third, for every
    remembered picture a line is added to the |.aux|-file, which may result in
    a large number of extra lines.

    Despite all these ``problems'', for documents that are processed with
    pdf\TeX\ and in which there is only a small number of pictures (less than a
    hundred or so), you can switch on this option globally, it will not cause
    any significant slowing of \TeX.
\end{environment}

\begin{plainenvironment}{{pgfpicture}}
    The plain \TeX\ version of the environment. Note that in this version,
    also, a \TeX\ group is created around the environment.
\end{plainenvironment}

\begin{contextenvironment}{{pgfpicture}}
    This is the Con\TeX t version of the environment.
\end{contextenvironment}

{\let\ifpgfrememberpicturepositiononpage=\relax
\begin{command}{\ifpgfrememberpicturepositiononpage}
    Determines whether the position of pictures on the page should be recorded.
    The value of this \TeX-if at the end of a |{pgfpicture}| environment is
    important, not the value at the beginning.

    If this option is set to true of a picture, \pgfname\ will attempt to
    record the position of the picture on the page. (This attempt will fail
    with most drivers and when it works, it typically requires two runs of
    \TeX.) The position is not directly accessible. Rather, the nodes mechanism
    will use this position if you access a node from another picture. See
    Sections~\ref{section-cross-pictures-pgf}
    and~\ref{section-cross-picture-tikz} for more details.
\end{command}
}

\makeatletter
\begin{command}{\pgfsetbaseline\marg{dimension}}
    This command specifies a $y$-coordinate of the picture that should be used
    as the baseline of the whole picture. When a \pgfname\ picture has been
    typeset completely, \pgfname\ must decide at which height the baseline of
    the picture should lie. Normally, the baseline is set to the $y$-coordinate
    of the bottom of the picture, but it is often desirable to use a different
    height.
    %
\begin{codeexample}[]
Text
\begin{pgfpicture}
  \pgfpathcircle{\pgfpointorigin}{1ex}\pgfusepath{stroke}
\end{pgfpicture},
\begin{pgfpicture}
  \pgfsetbaseline{0pt}
  \pgfpathcircle{\pgfpointorigin}{1ex}\pgfusepath{stroke}
\end{pgfpicture},
\begin{pgfpicture}
  \pgfsetbaseline{.5ex}
  \pgfpathcircle{\pgfpointorigin}{1ex}\pgfusepath{stroke}
\end{pgfpicture},
\begin{pgfpicture}
  \pgfsetbaseline{-1ex}
  \pgfpathcircle{\pgfpointorigin}{1ex}\pgfusepath{stroke}
\end{pgfpicture}.
\end{codeexample}
    %
\end{command}

\begin{command}{\pgfsetbaselinepointnow\marg{point}}
    This command specifies the baseline indirectly, namely as the
    $y$-coordinate that the given \meta{point} has when the command is called.
\end{command}

\begin{command}{\pgfsetbaselinepointlater\marg{point}}
    This command also specifies the baseline indirectly, but the $y$-coordinate
    of the given \meta{point} is only computed at the end of the picture.
    %
\begin{codeexample}[]
Hello
\begin{pgfpicture}
  \pgfsetbaselinepointlater{\pgfpointanchor{X}{base}}
  % Note: no shape X, yet
  \pgfnode{cross out}{center}{world.}{X}{\pgfusepath{stroke}}
\end{pgfpicture}
\end{codeexample}
    %
\end{command}


\subsubsection{Graphic Scope Environments}

Inside a |{pgfpicture}| environment you can substructure your picture using the
following environment:

\begin{environment}{{pgfscope}}
    All changes to the graphic state done inside this environment are
    local to the environment. The graphic state includes the following:
    %
    \begin{itemize}
        \item The line width.
        \item The stroke and fill colors.
        \item The dash pattern.
        \item The line join and cap.
        \item The miter limit.
        \item The canvas transformation matrix.
        \item The clipping path.
    \end{itemize}
    %
    Other parameters may also influence how graphics are rendered, but they are
    \emph{not} part of the graphic state. For example, the arrow tip kind is
    not part of the graphic state and the effect of commands setting the arrow
    tip kind are local to the current \TeX\ group, not to the current
    |{pgfscope}|. However, since |{pgfscope}| starts and ends a \TeX\ group
    automatically, a |{pgfscope}| can be used to limit the effect of, say,
    commands that set the arrow tip kind.
    %
\begin{codeexample}[]
\begin{pgfpicture}
  \begin{pgfscope}
    {
      \pgfsetlinewidth{2pt}
      \pgfpathrectangle{\pgfpointorigin}{\pgfpoint{2ex}{2ex}}
      \pgfusepath{stroke}
    }
    \pgfpathrectangle{\pgfpoint{3ex}{0ex}}{\pgfpoint{2ex}{2ex}}
    \pgfusepath{stroke}
  \end{pgfscope}
  \pgfpathrectangle{\pgfpoint{6ex}{0ex}}{\pgfpoint{2ex}{2ex}}
  \pgfusepath{stroke}
\end{pgfpicture}
\end{codeexample}

\begin{codeexample}[]
\begin{pgfpicture}
  \begin{pgfscope}
    {
      \pgfsetarrows{->}
      \pgfpathmoveto{\pgfpointorigin}\pgfpathlineto{\pgfpoint{2ex}{2ex}}
      \pgfusepath{stroke}
    }
    \pgfpathmoveto{\pgfpoint{3ex}{0ex}}\pgfpathlineto{\pgfpoint{5ex}{2ex}}
    \pgfusepath{stroke}
  \end{pgfscope}
  \pgfpathmoveto{\pgfpoint{6ex}{0ex}}\pgfpathlineto{\pgfpoint{8ex}{2ex}}
  \pgfusepath{stroke}
\end{pgfpicture}
\end{codeexample}

    At the start of the scope, the current path must be empty, that is, you
    cannot open a scope while constructing a path.

    It is usually a good idea \emph{not} to introduce \TeX\ groups inside a
    |{pgfscope}| environment.
\end{environment}

\begin{plainenvironment}{{pgfscope}}
    Plain \TeX\ version of the |{pgfscope}| environment.
\end{plainenvironment}

\begin{contextenvironment}{{pgfscope}}
    This is the Con\TeX t version of the environment.
\end{contextenvironment}

The following scopes also encapsulate certain properties of the graphic state.
However, they are typically not used directly by the user.

\begin{environment}{{pgfinterruptpath}}
    This environment can be used to temporarily interrupt the construction of
    the current path. The effect will be that the path currently under
    construction will be ``stored away'' and restored at the end of the
    environment. Inside the environment you can construct a new path and do
    something with it.

    An example application of this environment is the arrow tip caching.
    Suppose you ask \pgfname\ to use a specific arrow tip kind. When the arrow
    tip needs to be rendered for the first time, \pgfname\ will ``cache'' the
    path that makes up the arrow tip. To do so, it interrupts the current path
    construction and then protocols the path of the arrow tip. The
    |{pgfinterruptpath}| environment is used to ensure that this does not
    interfere with the path to which the arrow tips should be attached.

    This command does \emph{not} install a |{pgfscope}|. In particular, it does
    not call any |\pgfsys@| commands at all, which would, indeed, be dangerous
    in the middle of a path construction.
\end{environment}

\begin{plainenvironment}{{pgfinterruptpath}}
    Plain \TeX\ version of the environment.
\end{plainenvironment}

\begin{contextenvironment}{{pgfinterruptpath}}
    Con\TeX t version of the environment.
\end{contextenvironment}

\begin{environment}{{pgfinterruptpicture}}
    This environment can be used to temporarily interrupt a |{pgfpicture}|.
    However, the environment is intended only to be used at the beginning and
    end of a box that is (later) inserted into a |{pgfpicture}| using
    |\pgfqbox|. You cannot use this environment directly inside a
    |{pgfpicture}|.
    %
\begin{codeexample}[]
\begin{pgfpicture}
  \pgfpathmoveto{\pgfpoint{0cm}{0cm}} % In the middle of path, now
  \newbox\mybox
  \setbox\mybox=\hbox{
    \begin{pgfinterruptpicture}
      Sub-\begin{pgfpicture} % a subpicture
        \pgfpathmoveto{\pgfpoint{1cm}{0cm}}
        \pgfpathlineto{\pgfpoint{1cm}{1cm}}
        \pgfusepath{stroke}
      \end{pgfpicture}-picture.
    \end{pgfinterruptpicture}
  }
  \pgfqbox{\mybox}%
  \pgfpathlineto{\pgfpoint{0cm}{1cm}}
  \pgfusepath{stroke}
\end{pgfpicture}\hskip3.9cm
\end{codeexample}
    %
\end{environment}

\begin{plainenvironment}{{pgfinterruptpicture}}
    Plain \TeX\ version of the environment.
\end{plainenvironment}

\begin{contextenvironment}{{pgfinterruptpicture}}
    Con\TeX t version of the environment.
\end{contextenvironment}

\begin{environment}{{pgfinterruptboundingbox}}
    This environment temporarily interrupts the computation of the bounding box
    and sets up a new bounding box. At the beginning of the environment the old
    bounding box is saved and an empty bounding box is installed. After the
    environment the original bounding box is reinstalled as if nothing has
    happened.
\end{environment}

\begin{plainenvironment}{{pgfinterruptboundingbox}}
    Plain \TeX\ version of the environment.
\end{plainenvironment}

\begin{contextenvironment}{{pgfinterruptboundingbox}}
    Con\TeX t version of the environment.
\end{contextenvironment}


\subsubsection{Inserting Text and Images}
\label{section-text-command}

Often, you may wish to add normal \TeX\ text at a certain point inside a
|{pgfpicture}|. You cannot do so ``directly'', that is, you cannot simply write
this text inside the |{pgfpicture}| environment. Rather, you must pass the text
as an argument to the |\pgftext| command.

You must \emph{also} use the |\pgftext| command to insert an image or a shading
into a |{pgfpicture}|.

\begin{command}{\pgftext\opt{\oarg{options}}\marg{text}}
    This command will typeset \meta{text} in normal \TeX\ mode and insert the
    resulting box into the |{pgfpicture}|. The bounding box of the graphic will
    be updated so that all of the text box is inside. By default, the text box
    is centered at the origin, but this can be changed either by giving
    appropriate \meta{options} or by applying an appropriate coordinate
    transformation beforehand.

    The \meta{text} may contain verbatim text. (In other words, the \meta{text}
    ``argument'' is not a normal argument, but is put in a box and some
    |\aftergroup| hackery is used to find the end of the box.)

    \pgfname's current (high-level) coordinate transformation is synchronized
    with the canvas transformation matrix temporarily when the text box is
    inserted. The effect is that if there is currently a high-level rotation
    of, say, 30 degrees, the \meta{text} will also be rotated by thirty
    degrees. If you do not want this effect, you have to (possibly temporarily)
    reset the high-level transformation matrix.

    The \meta{options} keys are used with the path |/pgf/text/|. The following
    keys are defined for this path:
    %
    \begin{key}{/pgf/text/left}
        The key causes the text box to be placed such that its left border is
        on the origin.
        %
\begin{codeexample}[]
\tikz{\draw[help lines] (-1,-.5) grid (1,.5);
     \pgftext[left] {lovely}}
\end{codeexample}
    \end{key}
    %
    \begin{key}{/pgf/text/right}
        The key causes the text box to be placed such that its right border is
        on the origin.
        %
\begin{codeexample}[]
\tikz{\draw[help lines] (-1,-.5) grid (1,.5);
     \pgftext[right] {lovely}}
\end{codeexample}
    \end{key}
    %
    \begin{key}{/pgf/text/top}
        This key causes the text box to be placed such that its top is on the
        origin. This option can be used together with the |left| or |right|
        option.
        %
\begin{codeexample}[]
\tikz{\draw[help lines] (-1,-.5) grid (1,.5);
     \pgftext[top] {lovely}}
\end{codeexample}
        %
\begin{codeexample}[]
\tikz{\draw[help lines] (-1,-.5) grid (1,.5);
     \pgftext[top,right] {lovely}}
\end{codeexample}
    \end{key}
    %
    \begin{key}{/pgf/text/bottom}
        This key causes the text box to be placed such that its bottom is on
        the origin.
        %
\begin{codeexample}[]
\tikz{\draw[help lines] (-1,-.5) grid (1,.5);
     \pgftext[bottom] {lovely}}
\end{codeexample}
        %
\begin{codeexample}[]
\tikz{\draw[help lines] (-1,-.5) grid (1,.5);
     \pgftext[bottom,right] {lovely}}
\end{codeexample}
    \end{key}
    %
    \begin{key}{/pgf/text/base}
        This key causes the text box to be placed such that its baseline is on
        the origin.
        %
\begin{codeexample}[]
\tikz{\draw[help lines] (-1,-.5) grid (1,.5);
     \pgftext[base] {lovely}}
\end{codeexample}
        %
\begin{codeexample}[]
\tikz{\draw[help lines] (-1,-.5) grid (1,.5);
     \pgftext[base,right] {lovely}}
\end{codeexample}
    \end{key}
    %
    \begin{key}{/pgf/text/at=\meta{point}}
        Translates the origin (that is, the point where the text is shown) to
        \meta{point}.
        %
\begin{codeexample}[]
\tikz{\draw[help lines] (-1,-.5) grid (1,.5);
     \pgftext[base,at={\pgfpoint{1cm}{0cm}}] {lovely}}
\end{codeexample}
    \end{key}
    %
    \begin{key}{/pgf/text/x=\meta{dimension}}
        Translates the origin by \meta{dimension} along the $x$-axis.
        %
\begin{codeexample}[]
\tikz{\draw[help lines] (-1,-.5) grid (1,.5);
     \pgftext[base,x=1cm,y=-0.5cm] {lovely}}
\end{codeexample}
    \end{key}
    %
    \begin{key}{/pgf/text/y=\meta{dimension}}
        This key works like the |x| option.
    \end{key}
    %
    \begin{key}{/pgf/text/rotate=\meta{degree}}
        Rotates the coordinate system by \meta{degree}. This will also rotate
        the text box.
    %
\begin{codeexample}[]
\tikz{\draw[help lines] (-1,-.5) grid (1,.5);
     \pgftext[base,x=1cm,y=-0.5cm,rotate=30] {lovely}}
\end{codeexample}
    \end{key}
\end{command}


\subsection{Object Identifiers}

Graphical objects can have an \emph{identifier,} which allows you to reference
the object later on. For instance, you could reference the object as the target
of a hyperlink (although this capability is not necessarily implemented by
drivers) or as the target of an animation; indeed, animations always need an
object identifier to identify the to-be-animated object.

Attaching an identifier to an object is a two-step process:
%
\begin{enumerate}
    \item You call |\pgfuseid{|\meta{id}|}| to choose an id, which is a normal
        string.
    \item Next, you call one of several commands like |\pgfidscope| or
        |\pgftext|, which create an object. This object will have then have the
        id.
\end{enumerate}


\subsubsection{Commands for Creating Graphic Objects}

The following system level commands create an object with an id:
%
\begin{enumerate}
    \item |\pgfsys@begin@idscope|, which creates a graphic scope.
    \item |\pgfsys@viewboxmeet| or |\pgfsys@viewboxslice|, which create view
        boxes,
    \item |\pgfsys@fill|, |\pgfsys@stroke|, and all other path usage command,
    \item |\pgfsys@hbox| or |\pgfsys@hboxsynced|, which create text boxes, and
    \item |\pgfsys@animate...|, which create animations.
\end{enumerate}

These system layer commands are, in turn, called by the following basic layer
commands (and, also, by the commands that call them, in turn):
%
\begin{itemize}
    \item |\pgfidscope|, which creates an id scope (see below).
    \item |\pgfviewboxscope|, which creates a view box.
    \item |\pgfusepath|, which creates a path.
    \item |\pgftext| and |\pgfnode| and |\pgfmultipartnode|, which create text
        boxes and nodes, and
    \item |\pgfanimateattribute|, which creates an animation.
\end{itemize}

\begin{environment}{{pgfidscope}}
    Creates a graphic scope that will have the id last used with |\pgfuseid|
    attached to, provided such an id was set and was not already used with
    another object. In the latter cases, no graphic scope is created. Thus, if
    you wish to ensure that a graphic scope is created, you must (additionally)
    call |\pgfscope| inside or outside the id scope.
\end{environment}

The Plain\TeX\ and Con\TeX t versions of the environment are:
%
\begin{plainenvironment}{{pgfidscope}}
\end{plainenvironment}

\begin{contextenvironment}{{pgfidscope}}
\end{contextenvironment}


\subsubsection{Settings and Querying Identifiers}

In order to attach an identifier to an object, you first use the following
command:

\begin{command}{\pgfuseid\marg{name}}
    The \meta{name} is a string by which the object will be referenced (see
    |\pgfidrefnextuse|). The next time a graphic object is created in the
    current \TeX\ scope, the name will be attached to it (actually, it will get
    a system layer identifier attached to it that is automatically created
    using |\pgfsys@new@id|, the \meta{name} is bound to that identifier and it
    can be retrieved using |\pgfidrefnextuse|). This holds true only for the
    next object: If a second object is created, it will not get the name
    attached to it. This does not mean, however, that you cannot attach the
    same name to different objects; you just need to call |\pgfuseid| again
    before each object.

    Besides the \meta{name} (or, more precisely, besides the system layer
    identifier is refers to), the current \emph{identifier type} is also
    important: Actually, a graphic object is not referenced by a system layer
    identifier, but by the combination of the identifier and a type. You can
    use the following commands for modifying the type used for the creation of
    objects:

    \begin{command}{\pgfusetype\marg{type}}
        Sets the type used for the referencing of graphic objects for the
        current scope to \meta{type} or, if \meta{type} starts with a dot,
        appends \meta{type} to the current type.

        You use this command with compound graphic objects: Before each part of
        a graphic object, set the type to an appropriate value. Now, if the
        object is named using |\pgfuseid|, you can later on access all parts of
        the compound object using the combination of the \meta{name} used with
        |\pgfuseid| and the type of the part.

        As an example, this system is used to give you access to the different
        parts of a node: When use say |\pgfuseid{mynode}| and then create a
        node, you can use |mynode| with the empty type to reference the
        graphics scope that encompasses the whole node, but also |mynode|
        together with the type |background| to access the background path of
        the node.

        In detail, \pgfname\ uses this command to set the following types:
        %
        \begin{itemize}
            \item Inside the command |\pgfviewboxscope|, the type |.view| is
                used for the view object.
            \item Inside the command |\pgfmultipartnode|, the type
                |.behind background| is used for the scope of drawings behind
                the background. Similarly, |.before background| and
                |.behind foreground| and finally |.before foreground| are used
                with the respective parts of a node.
            \item Also inside a node, |.background| and |.foreground| are used
                as types of the background and foreground paths, respectively.
            \item Finally, inside a node, for each text part, the text part's
                name is used as a type (so |.text| is used for the main part).
        \end{itemize}

        In addition, \tikzname\ uses this command in the following
        situations:
        %
        \begin{itemize}
            \item The type |.path| is used with a named path (named using the
                |name| key). This is the graphic object you need to reference
                when you wish to morph a path.
            \item The type |.path picture| is used with the scope of the
                optional path picture.
            \item The type |.path fill| is used with the path used for filling.
                This is not the same as the normal path in case the path is
                filled and patterned, for instance.
            \item The type |.path shade| is used with the path used for shading
                a path.
        \end{itemize}
    \end{command}

    \begin{command}{\pgfpushtype}
        Pushes the current type on an internal global stack. The idea is to
        allow you to temporarily change the current type without having to open
        a \TeX\ scope.
    \end{command}

    \begin{command}{\pgfpoptype}
        Restores the most recent type from the internal global stack of types.
    \end{command}
\end{command}

\begin{command}{\pgfclearid}
    Clears the current id (and type) for the local scope.
\end{command}

\begin{command}{\pgfidrefnextuse\marg{macro}\marg{name}}
    This command assigns a system layer identifier (the identifier returned by
    |\pgfsys@new@id|) to the \meta{macro}, namely the one that will be used the
    \emph{next} time |\pgfuseid| is used. You use this command for ``forward
    referencing''.

    A typical use case is the following: A key like |whom| for animations uses
    this command to get the system identifier that will be used for a future
    object. Then, this identifier can be passed to system layer commands like
    |\pgfsys@animation@whom|.

    Note that the ``next'' use need not be on the same page (or there may not
    even be any use at all), in which case the reference will not refer to any
    object.
\end{command}

\begin{command}{\pgfidrefprevuse\marg{macro}\marg{name}}
    Works like |\pgfidrefnextuse|, only it references the most recent
    \emph{previous} use of the \meta{name}. As for |\pgfidrefnextuse|, the most
    recent use need not be on the same page.
\end{command}

\begin{command}{\pgfaliasid\marg{alias}\marg{name}}
    Creates an alias of a name inside the current \TeX\ scope. After calling
    this command, you can use \meta{alias} anywhere where you would normally
    use \meta{name}. Note that the binding between \meta{alias} and \meta{name}
    is not kept when |\pgfuseid| is used on the \meta{name} (or the
    \meta{alias}).
\end{command}

\begin{command}{\pgfgaliasid\marg{1}\marg{2}}
    Like |\pgfaliasid|, only the alias is set globally.
\end{command}

\begin{command}{\pgfifidreferenced\marg{name}\marg{then code}\marg{else code}}
    If \meta{name} has been referenced, \meta{then code} is executed, otherwise
    \meta{else code}.
\end{command}


\subsection{Resource Description Framework Annotations (RDFa)}
\label{section-base-rdf}

With certain output formats (in particular, with \textsc{svg}) you can insert
annotations into the output file following the standard set by the
\emph{resource description framework} (known as ``\textsc{rdf}'', please
consult the literature on \textsc{rdf} and \textsc{rdf}a for an introduction to
resource descriptions and ontologies and their purpose in general). To do so,
you call one (or several) of the following commands before you call
|\pgfidscope|. The attributes and values you specify using the commands will
then be added to the resulting scope (if the driver supports this, which is
only the case for \textsc{svg} at the moment). As an example, when you write
%
\begin{codeexample}[code only]
\pgfrdfresource{/fruits/apple}
\pgfidscope
...
\pgfendidscope
\end{codeexample}

in the resulting \textsc{svg} file you get
%
\begin{codeexample}[code only]
<g resource="/fruits/apple">
  ...
</g>
\end{codeexample}

Most of the following commands just set a single attribute for the next id
scope. In some cases, however, repeated calling of these commands makes sense
and causes the passed values to accumulate as in the following example:
%
\begin{codeexample}[code only]
\pgfrdfresource{/fruits/apple}
\pgfrdfproperty{http://foo.com/props/juicy}
\pgfrdfproperty{http://foo.com/props/green}
\pgfidscope
...
\pgfendidscope
\end{codeexample}

Now you get:
%
\begin{codeexample}[code only]
<g resource="/fruits/apple"
   property="http://foo.com/props/juicy http://foo.com/props/green">
  ...
</g>
\end{codeexample}

The following commands ``accumulate'': |\pgfrdfproperty|, |\pgfrdfrel|,
|\pgfrdfrev| and also the command |\pgfrdftypeof|.

\begin{command}{\pgfrdfabout\marg{text}}
    Adds the \textsc{rdf} attribute |about="|\meta{text}|"| to the next id
    scope (please see the \textsc{rdf}a specification for details on the
    semantics of |about| in the context of the resource description framework).
\end{command}

The following commands work the same way.

\begin{command}{\pgfrdfcontent\marg{text}}
\end{command}

\begin{command}{\pgfrdfdatatype\marg{text}}
\end{command}

\begin{command}{\pgfrdfhref\marg{text}}
\end{command}

\begin{command}{\pgfrdfinlist}
\end{command}

\begin{command}{\pgfrdfprefix\marg{text}}
\end{command}

\begin{command}{\pgfrdfproperty\marg{text}}
\end{command}

\begin{command}{\pgfrdfrel\marg{text}}
\end{command}

\begin{command}{\pgfrdfresource\marg{text}}
\end{command}

\begin{command}{\pgfrdfrev\marg{text}}
\end{command}

\begin{command}{\pgfrdfsrc\marg{text}}
\end{command}

\begin{command}{\pgfrdftypeof\marg{text}}
\end{command}

\begin{command}{\pgfrdfvocab\marg{text}}
\end{command}


\subsection{Error Messages and Warnings}

Sometimes, a command inside \pgfname\ may fail. In this case, two commands are
useful to communicate with the author:

\begin{command}{\pgferror\marg{message}}
    Stops the processing of the current document and prints out the
    \meta{message}. In \LaTeX, this will be done using |\PackageError|,
    otherwise |\errmessage| is used directly.
\end{command}

\begin{command}{\pgfwarning\marg{message}}
    Prints the \meta{message} on the output, but does not interrupt the
    processing. In \LaTeX, this will be done using |\PackageWarning|, otherwise
    a write to stream $17$ is used.
\end{command}