Debian Codegraph @

texmf-dist/doc/generic/pgf/pgfmanual-en-base-scopes.tex

raw
1 % Copyright 2019 by Till Tantau
2 %
3 % This file may be distributed and/or modified
4 %
5 % 1. under the LaTeX Project Public License and/or
6 % 2. under the GNU Free Documentation License.
7 %
8 % See the file doc/generic/pgf/licenses/LICENSE for more details.
9
10
11 \section[Hierarchical Structures: Package, Environments, Scopes, and Text]
12 {Hierarchical Structures:\\
13 Package, Environments, Scopes, and Text}
14
15 \subsection{Overview}
16
17 \pgfname\ uses two kinds of hierarchical structuring: First, the package itself
18 is structured hierarchically, consisting of different packages that are built
19 on top of each other. Second, \pgfname\ allows you to structure your graphics
20 hierarchically using environments and scopes.
21
22
23 \subsubsection{The Hierarchical Structure of the Package}
24
25 The \pgfname\ system consists of several layers:
26 %
27 \begin{description}
28 \item[System layer.]
29 The lowest layer is called the \emph{system layer}, though it might
30 also be called ``driver layer'' or perhaps ``backend layer''. Its job
31 is to provide an abstraction of the details of which driver is used to
32 transform the |.dvi| file. The system layer is implemented by the
33 package |pgfsys|, which will load appropriate driver files as needed.
34
35 The system layer is documented in Part~\ref{part-system}.
36 \item[Basic layer.]
37 The basic layer is loaded by the package |pgfcore| and subsequent use
38 of the command |\usepgfmodule| to load additional modules of the basic
39 layer.
40
41 The basic layer is documented in the present part.
42 \item[Frontend layer.]
43 The frontend layer is not loaded by a single package. Rather, different
44 packages, like \tikzname\ or \textsc{pgfpict2e}, are different
45 frontends to the basic layer.
46
47 The \tikzname\ frontend is documented in Part~\ref{part-tikz}.
48 \end{description}
49
50 Each layer will automatically load the necessary files of the layers below it.
51
52 In addition to the packages of these layers, there are also some library
53 packages. These packages provide additional definitions of things like new
54 arrow tips or new plot handlers.
55
56 The library packages are documented in Part~\ref{part-libraries}.
57
58
59 \subsubsection{The Hierarchical Structure of Graphics}
60
61 Graphics in \pgfname\ are typically structured hierarchically. Hierarchical
62 structuring can be used to identify groups of graphical elements that are to be
63 treated ``in the same way''. For example, you might group together a number of
64 paths, all of which are to be drawn in red. Then, when you decide later on that
65 you like them to be drawn in, say, blue, all you have to do is to change the
66 color once.
67
68 The general mechanism underlying hierarchical structuring is known as
69 \emph{scoping} in computer science. The idea is that all changes to the general
70 ``state'' of the graphic that are done inside a scope are local to that scope.
71 So, if you change the color inside a scope, this does not affect the color used
72 outside the scope. Likewise, when you change the line width in a scope, the
73 line width outside is not changed, and so on.
74
75 There are different ways of starting and ending scopes of graphic parameters.
76 Unfortunately, these scopes are sometimes ``in conflict'' with each other and
77 it is sometimes not immediately clear which scopes apply. In essence, the
78 following scoping mechanisms are available:
79 %
80 \begin{enumerate}
81 \item The ``outermost'' scope supported by \pgfname\ is the |{pgfpicture}|
82 environment. All changes to the graphic state done inside a
83 |{pgfpicture}| are local to that picture.
84
85 In general, it is \emph{not} possible to set graphic parameters
86 globally outside any |{pgfpicture}| environments. Thus, you can
87 \emph{not} say |\pgfsetlinewidth{1pt}| at the beginning of your
88 document to have a default line width of one point. Rather, you have to
89 (re)set all graphic parameters inside each |{pgfpicture}|. (If this is
90 too bothersome, try defining some macro that does the job for you.)
91 \item Inside a |{pgfpicture}| you can use a |{pgfscope}| environment to
92 keep changes of the graphic state local to that environment.
93
94 The effect of commands that change the graphic state are local to the
95 current |{pgfscope}|, but not always to the current \TeX\ group. Thus,
96 if you open a \TeX\ group (some text in curly braces) inside a
97 |{pgfscope}|, and if you change, for example, the dash pattern, the
98 effect of this changed dash pattern will persist till the end of the
99 |{pgfscope}|.
100
101 Unfortunately, this is not always the case. \emph{Some} graphic
102 parameters only persist till the end of the current \TeX\ group. For
103 example, when you use |\pgfsetarrows| to set the arrow tip inside a
104 \TeX\ group, the effect lasts only till the end of the current \TeX\
105 group.
106 \item Some graphic parameters are not scoped by |{pgfscope}| but
107 ``already'' by \TeX\ groups. For example, the effect of coordinate
108 transformation commands is always local to the current \TeX\ group.
109
110 Since every |{pgfscope}| automatically creates a \TeX\ group, all
111 graphic parameters that are local to the current \TeX\ group are also
112 local to the current |{pgfscope}|.
113 \item Some graphic parameters can only be scoped using \TeX\ groups, since
114 in some situations it is not possible to introduce a |{pgfscope}|. For
115 example, a path always has to be completely constructed and used in the
116 same |{pgfscope}|. However, we might wish to have different coordinate
117 transformations apply to different points on the path. In this case, we
118 can use \TeX\ groups to keep the effect local, but we could not use
119 |{pgfscope}|.
120 \item The |\pgftext| command can be used to create a scope in which \TeX\
121 ``escapes back'' to normal \TeX\ mode. The text passed to the
122 |\pgftext| is ``heavily guarded'' against having any effect on the
123 scope in which it is used. For example, it is possible to use another
124 |{pgfpicture}| environment inside the argument of |\pgftext|.
125 \end{enumerate}
126
127 Most of the complications can be avoided if you stick to the following
128 rules:
129 %
130 \begin{itemize}
131 \item Give graphic commands only inside |{pgfpicture}| environments.
132 \item Use |{pgfscope}| to structure graphics.
133 \item Do not use \TeX\ groups inside graphics, \emph{except} for keeping
134 the effect of coordinate transformations local.
135 \end{itemize}
136
137
138 \subsection{The Hierarchical Structure of the Package}
139
140 Before we come to the structuring commands provided by \pgfname\ to structure
141 your graphics, let us first have a look at the structure of the package itself.
142
143
144 \subsubsection{The Core Package}
145
146 To use \pgfname, include the following package:
147
148 \begin{package}{pgfcore}
149 This package loads the complete core of the ``basic layer'' of \pgfname,
150 but not any modules. That is, it will load all of the commands described in
151 the current part of this manual, but it will not load frontends like
152 \tikzname. It will also load the system layer. To load additional modules,
153 use the |\usepgfmodule| command explained below.
154 \end{package}
155
156 The following package is just a convenience.
157
158 \begin{package}{pgf}
159 This package loads the |pgfcore| and the two modules |shapes| and |plot|.
160
161 In \LaTeX, the package takes two options:
162 %
163 \begin{packageoption}{draft}
164 When this option is set, all images will be replaced by empty
165 rectangles. This can speedup compilation.
166 \end{packageoption}
167
168 \begin{packageoption}{version=\meta{version}}
169 Indicates that the commands of version \meta{version} need to be
170 defined. If you set \meta{version} to |0.65|, then a large bunch of
171 ``compatibility commands'' are loaded. If you set \meta{version} to
172 |0.96|, then these compatibility commands will not be loaded.
173
174 If this option is not given at all, then the commands of all versions
175 are defined.
176 \end{packageoption}
177 \end{package}
178
179
180 \subsubsection{The Modules}
181
182 \begin{command}{\usepgfmodule\marg{module names}}
183 Once the core has been loaded, you can use this command to load further
184 modules. The modules in the \meta{module names} list should be separated by
185 commas. Instead of curly braces, you can also use square brackets, which is
186 something Con\TeX t users will like. If you try to load a module a second
187 time, nothing will happen.
188
189 \example |\usepgfmodule{matrix,shapes}|
190
191 What this command does is to load the file
192 |pgfmodule|\meta{module}|.code.tex| for each \meta{module} in the list of
193 \meta{module names}. Thus, to write your own module, all you need to do is
194 to place a file of the appropriate name somewhere \TeX\ can find it.
195 \LaTeX, plain \TeX, and Con\TeX t users can then use your library.
196 \end{command}
197
198 The following modules are available for use with |pgfcore|: \todosp{In the
199 meantime there are some more modules. Also mention them here?}
200 %
201 \begin{itemize}
202 \item The |plot| module provides commands for plotting functions. The
203 commands are explained in Section~\ref{section-plots}.
204 \item The |shapes| module provides commands for drawing shapes and nodes.
205 These commands are explained in Section~\ref{section-shapes}.
206 \item The |decorations| module provides commands for adding decorations to
207 paths. These commands are explained in
208 Section~\ref{section-base-decorations}.
209 \item The |matrix| module provides the |\pgfmatrix| command. The commands
210 are documented in Section~\ref{section-base-matrices}.
211 \end{itemize}
212
213
214 \subsubsection{The Library Packages}
215
216 There is a special command for loading library packages. The difference between
217 a library and module is the following: A library just defines additional
218 objects using the basic layer, whereas a module adds completely new
219 functionality. For instance, a |decorations| library defines additional
220 decorations, while a decoration module defines the whole code for handling
221 decorations.
222
223 \begin{command}{\usepgflibrary\marg{list of libraries}}
224 Use this command to load further libraries. The list of libraries should
225 contain the names of libraries separated by commas. Instead of curly
226 braces, you can also use square brackets. If you try to load a library a
227 second time, nothing will happen.
228
229 \example |\usepgflibrary{arrows}|
230
231 This command causes the file |pgflibrary|\meta{library}|.code.tex| to be
232 loaded for each \meta{library} in the \meta{list of libraries}. This means
233 that in order to write your own library file, place a file of the
234 appropriate name somewhere where \TeX\ can find it. \LaTeX, plain \TeX, and
235 Con\TeX t users can then use your library.
236
237 You should also consider adding a \tikzname\ library that simply includes
238 your \pgfname\ library.
239 \end{command}
240
241
242 \subsection{The Hierarchical Structure of the Graphics}
243
244 \subsubsection{The Main Environment}
245
246 Most, but not all, commands of the \pgfname\ package must be given within a
247 |{pgfpicture}| environment. The only commands that (must) be given outside are
248 commands having to do with including images (like |\pgfuseimage|) and with
249 inserting complete shadings (like |\pgfuseshading|). However, just to keep life
250 entertaining, the |\pgfshadepath| command must be given \emph{inside} a
251 |{pgfpicture}| environment.
252
253 \begin{environment}{{pgfpicture}}
254 This environment will insert a \TeX\ box containing the graphic drawn by
255 the \meta{environment contents} at the current position.
256
257
258 \medskip
259 \textbf{The size of the bounding box.}
260 The size of the box is determined in the following manner: While \pgfname\
261 parses the \meta{environment contents}, it keeps track of a bounding box
262 for the graphic. Essentially, this bounding box is the smallest box that
263 contains all coordinates mentioned in the graphics. Some coordinates may be
264 ``mentioned'' by \pgfname\ itself; for example, when you add circle to the
265 current path, the support points of the curve making up the circle are also
266 ``mentioned'' despite the fact that you will not ``see'' them in your code.
267
268 Once the \meta{environment contents} have been parsed completely, a \TeX\
269 box is created whose size is the size of the computed bounding box and this
270 box is inserted at the current position.
271 %
272 \begin{codeexample}[]
273 Hello \begin{pgfpicture}
274 \pgfpathrectangle{\pgfpointorigin}{\pgfpoint{2ex}{1ex}}
275 \pgfusepath{stroke}
276 \end{pgfpicture} World!
277 \end{codeexample}
278
279 Sometimes, you may need more fine-grained control over the size of the
280 bounding box. For example, the computed bounding box may be too large or
281 you intentionally wish the box to be ``too small''. In these cases, you can
282 use the command |\pgfusepath{use as bounding box}|, as described in
283 Section~\ref{section-using-bb}.
284
285
286 \medskip
287 \textbf{The baseline of the bounding box.}
288 When the box containing the graphic is inserted into the normal text, the
289 baseline of the graphic is normally at the bottom of the graphic. For this
290 reason, the following two sets of code lines have the same effect, despite
291 the fact that the second graphic uses ``higher'' coordinates than the
292 first:
293 %
294 \begin{codeexample}[]
295 Rectangles \begin{pgfpicture}
296 \pgfpathrectangle{\pgfpointorigin}{\pgfpoint{2ex}{1ex}}
297 \pgfusepath{stroke}
298 \end{pgfpicture} and \begin{pgfpicture}
299 \pgfpathrectangle{\pgfpoint{0ex}{1ex}}{\pgfpoint{2ex}{1ex}}
300 \pgfusepath{stroke}
301 \end{pgfpicture}.
302 \end{codeexample}
303
304 You can change the baseline using the |\pgfsetbaseline| command, see below.
305 %
306 \begin{codeexample}[]
307 Rectangles \begin{pgfpicture}
308 \pgfpathrectangle{\pgfpointorigin}{\pgfpoint{2ex}{1ex}}
309 \pgfusepath{stroke}
310 \pgfsetbaseline{0pt}
311 \end{pgfpicture} and \begin{pgfpicture}
312 \pgfpathrectangle{\pgfpoint{0ex}{1ex}}{\pgfpoint{2ex}{1ex}}
313 \pgfusepath{stroke}
314 \pgfsetbaseline{0pt}
315 \end{pgfpicture}.
316 \end{codeexample}
317
318
319 \medskip
320 \textbf{Including text and images in a picture.}
321 You cannot directly include text and images in a picture. Thus, you should
322 \emph{not} simply write some text in a |{pgfpicture}| or use a command like
323 |\includegraphics| or even |\pgfimage|. In all these cases, you need to
324 place the text inside a |\pgftext| command. This will ``escape back'' to
325 normal \TeX\ mode, see Section~\ref{section-text-command} for details.
326
327
328 \medskip
329 \textbf{Remembering a picture position for later reference.}
330 After a picture has been typeset, its position on the page is normally
331 forgotten by \pgfname\ and also by \TeX. This means that is not possible to
332 reference a node in this picture later on. In particular, it is normally
333 impossible to draw lines between nodes in different pictures automatically.
334
335 In order to make \pgfname\ ``remember'' a picture, the \TeX-if
336 |\ifpgfrememberpicturepositiononpage| should be set to |true|. It is only
337 important that this \TeX-if is |true| at the end of the
338 |{pgfpicture}|-en\-vi\-ron\-ment, so you can switch it on inside the
339 environment. However, you can also just switch it on globally, then the
340 positions of all pictures are remembered.
341
342 There are several reasons why the remembering is not switched on by
343 default. First, it does not work for all backend drivers (currently, it
344 works only for pdf\TeX). Second, it requires two passes of \TeX\ over the
345 file; on the first pass all positions will be wrong. Third, for every
346 remembered picture a line is added to the |.aux|-file, which may result in
347 a large number of extra lines.
348
349 Despite all these ``problems'', for documents that are processed with
350 pdf\TeX\ and in which there is only a small number of pictures (less than a
351 hundred or so), you can switch on this option globally, it will not cause
352 any significant slowing of \TeX.
353 \end{environment}
354
355 \begin{plainenvironment}{{pgfpicture}}
356 The plain \TeX\ version of the environment. Note that in this version,
357 also, a \TeX\ group is created around the environment.
358 \end{plainenvironment}
359
360 \begin{contextenvironment}{{pgfpicture}}
361 This is the Con\TeX t version of the environment.
362 \end{contextenvironment}
363
364 {\let\ifpgfrememberpicturepositiononpage=\relax
365 \begin{command}{\ifpgfrememberpicturepositiononpage}
366 Determines whether the position of pictures on the page should be recorded.
367 The value of this \TeX-if at the end of a |{pgfpicture}| environment is
368 important, not the value at the beginning.
369
370 If this option is set to true of a picture, \pgfname\ will attempt to
371 record the position of the picture on the page. (This attempt will fail
372 with most drivers and when it works, it typically requires two runs of
373 \TeX.) The position is not directly accessible. Rather, the nodes mechanism
374 will use this position if you access a node from another picture. See
375 Sections~\ref{section-cross-pictures-pgf}
376 and~\ref{section-cross-picture-tikz} for more details.
377 \end{command}
378 }
379
380 \makeatletter
381 \begin{command}{\pgfsetbaseline\marg{dimension}}
382 This command specifies a $y$-coordinate of the picture that should be used
383 as the baseline of the whole picture. When a \pgfname\ picture has been
384 typeset completely, \pgfname\ must decide at which height the baseline of
385 the picture should lie. Normally, the baseline is set to the $y$-coordinate
386 of the bottom of the picture, but it is often desirable to use a different
387 height.
388 %
389 \begin{codeexample}[]
390 Text
391 \begin{pgfpicture}
392 \pgfpathcircle{\pgfpointorigin}{1ex}\pgfusepath{stroke}
393 \end{pgfpicture},
394 \begin{pgfpicture}
395 \pgfsetbaseline{0pt}
396 \pgfpathcircle{\pgfpointorigin}{1ex}\pgfusepath{stroke}
397 \end{pgfpicture},
398 \begin{pgfpicture}
399 \pgfsetbaseline{.5ex}
400 \pgfpathcircle{\pgfpointorigin}{1ex}\pgfusepath{stroke}
401 \end{pgfpicture},
402 \begin{pgfpicture}
403 \pgfsetbaseline{-1ex}
404 \pgfpathcircle{\pgfpointorigin}{1ex}\pgfusepath{stroke}
405 \end{pgfpicture}.
406 \end{codeexample}
407 %
408 \end{command}
409
410 \begin{command}{\pgfsetbaselinepointnow\marg{point}}
411 This command specifies the baseline indirectly, namely as the
412 $y$-coordinate that the given \meta{point} has when the command is called.
413 \end{command}
414
415 \begin{command}{\pgfsetbaselinepointlater\marg{point}}
416 This command also specifies the baseline indirectly, but the $y$-coordinate
417 of the given \meta{point} is only computed at the end of the picture.
418 %
419 \begin{codeexample}[]
420 Hello
421 \begin{pgfpicture}
422 \pgfsetbaselinepointlater{\pgfpointanchor{X}{base}}
423 % Note: no shape X, yet
424 \pgfnode{cross out}{center}{world.}{X}{\pgfusepath{stroke}}
425 \end{pgfpicture}
426 \end{codeexample}
427 %
428 \end{command}
429
430
431 \subsubsection{Graphic Scope Environments}
432
433 Inside a |{pgfpicture}| environment you can substructure your picture using the
434 following environment:
435
436 \begin{environment}{{pgfscope}}
437 All changes to the graphic state done inside this environment are
438 local to the environment. The graphic state includes the following:
439 %
440 \begin{itemize}
441 \item The line width.
442 \item The stroke and fill colors.
443 \item The dash pattern.
444 \item The line join and cap.
445 \item The miter limit.
446 \item The canvas transformation matrix.
447 \item The clipping path.
448 \end{itemize}
449 %
450 Other parameters may also influence how graphics are rendered, but they are
451 \emph{not} part of the graphic state. For example, the arrow tip kind is
452 not part of the graphic state and the effect of commands setting the arrow
453 tip kind are local to the current \TeX\ group, not to the current
454 |{pgfscope}|. However, since |{pgfscope}| starts and ends a \TeX\ group
455 automatically, a |{pgfscope}| can be used to limit the effect of, say,
456 commands that set the arrow tip kind.
457 %
458 \begin{codeexample}[]
459 \begin{pgfpicture}
460 \begin{pgfscope}
461 {
462 \pgfsetlinewidth{2pt}
463 \pgfpathrectangle{\pgfpointorigin}{\pgfpoint{2ex}{2ex}}
464 \pgfusepath{stroke}
465 }
466 \pgfpathrectangle{\pgfpoint{3ex}{0ex}}{\pgfpoint{2ex}{2ex}}
467 \pgfusepath{stroke}
468 \end{pgfscope}
469 \pgfpathrectangle{\pgfpoint{6ex}{0ex}}{\pgfpoint{2ex}{2ex}}
470 \pgfusepath{stroke}
471 \end{pgfpicture}
472 \end{codeexample}
473
474 \begin{codeexample}[]
475 \begin{pgfpicture}
476 \begin{pgfscope}
477 {
478 \pgfsetarrows{->}
479 \pgfpathmoveto{\pgfpointorigin}\pgfpathlineto{\pgfpoint{2ex}{2ex}}
480 \pgfusepath{stroke}
481 }
482 \pgfpathmoveto{\pgfpoint{3ex}{0ex}}\pgfpathlineto{\pgfpoint{5ex}{2ex}}
483 \pgfusepath{stroke}
484 \end{pgfscope}
485 \pgfpathmoveto{\pgfpoint{6ex}{0ex}}\pgfpathlineto{\pgfpoint{8ex}{2ex}}
486 \pgfusepath{stroke}
487 \end{pgfpicture}
488 \end{codeexample}
489
490 At the start of the scope, the current path must be empty, that is, you
491 cannot open a scope while constructing a path.
492
493 It is usually a good idea \emph{not} to introduce \TeX\ groups inside a
494 |{pgfscope}| environment.
495 \end{environment}
496
497 \begin{plainenvironment}{{pgfscope}}
498 Plain \TeX\ version of the |{pgfscope}| environment.
499 \end{plainenvironment}
500
501 \begin{contextenvironment}{{pgfscope}}
502 This is the Con\TeX t version of the environment.
503 \end{contextenvironment}
504
505 The following scopes also encapsulate certain properties of the graphic state.
506 However, they are typically not used directly by the user.
507
508 \begin{environment}{{pgfinterruptpath}}
509 This environment can be used to temporarily interrupt the construction of
510 the current path. The effect will be that the path currently under
511 construction will be ``stored away'' and restored at the end of the
512 environment. Inside the environment you can construct a new path and do
513 something with it.
514
515 An example application of this environment is the arrow tip caching.
516 Suppose you ask \pgfname\ to use a specific arrow tip kind. When the arrow
517 tip needs to be rendered for the first time, \pgfname\ will ``cache'' the
518 path that makes up the arrow tip. To do so, it interrupts the current path
519 construction and then protocols the path of the arrow tip. The
520 |{pgfinterruptpath}| environment is used to ensure that this does not
521 interfere with the path to which the arrow tips should be attached.
522
523 This command does \emph{not} install a |{pgfscope}|. In particular, it does
524 not call any |\pgfsys@| commands at all, which would, indeed, be dangerous
525 in the middle of a path construction.
526 \end{environment}
527
528 \begin{plainenvironment}{{pgfinterruptpath}}
529 Plain \TeX\ version of the environment.
530 \end{plainenvironment}
531
532 \begin{contextenvironment}{{pgfinterruptpath}}
533 Con\TeX t version of the environment.
534 \end{contextenvironment}
535
536 \begin{environment}{{pgfinterruptpicture}}
537 This environment can be used to temporarily interrupt a |{pgfpicture}|.
538 However, the environment is intended only to be used at the beginning and
539 end of a box that is (later) inserted into a |{pgfpicture}| using
540 |\pgfqbox|. You cannot use this environment directly inside a
541 |{pgfpicture}|.
542 %
543 \begin{codeexample}[]
544 \begin{pgfpicture}
545 \pgfpathmoveto{\pgfpoint{0cm}{0cm}} % In the middle of path, now
546 \newbox\mybox
547 \setbox\mybox=\hbox{
548 \begin{pgfinterruptpicture}
549 Sub-\begin{pgfpicture} % a subpicture
550 \pgfpathmoveto{\pgfpoint{1cm}{0cm}}
551 \pgfpathlineto{\pgfpoint{1cm}{1cm}}
552 \pgfusepath{stroke}
553 \end{pgfpicture}-picture.
554 \end{pgfinterruptpicture}
555 }
556 \pgfqbox{\mybox}%
557 \pgfpathlineto{\pgfpoint{0cm}{1cm}}
558 \pgfusepath{stroke}
559 \end{pgfpicture}\hskip3.9cm
560 \end{codeexample}
561 %
562 \end{environment}
563
564 \begin{plainenvironment}{{pgfinterruptpicture}}
565 Plain \TeX\ version of the environment.
566 \end{plainenvironment}
567
568 \begin{contextenvironment}{{pgfinterruptpicture}}
569 Con\TeX t version of the environment.
570 \end{contextenvironment}
571
572 \begin{environment}{{pgfinterruptboundingbox}}
573 This environment temporarily interrupts the computation of the bounding box
574 and sets up a new bounding box. At the beginning of the environment the old
575 bounding box is saved and an empty bounding box is installed. After the
576 environment the original bounding box is reinstalled as if nothing has
577 happened.
578 \end{environment}
579
580 \begin{plainenvironment}{{pgfinterruptboundingbox}}
581 Plain \TeX\ version of the environment.
582 \end{plainenvironment}
583
584 \begin{contextenvironment}{{pgfinterruptboundingbox}}
585 Con\TeX t version of the environment.
586 \end{contextenvironment}
587
588
589 \subsubsection{Inserting Text and Images}
590 \label{section-text-command}
591
592 Often, you may wish to add normal \TeX\ text at a certain point inside a
593 |{pgfpicture}|. You cannot do so ``directly'', that is, you cannot simply write
594 this text inside the |{pgfpicture}| environment. Rather, you must pass the text
595 as an argument to the |\pgftext| command.
596
597 You must \emph{also} use the |\pgftext| command to insert an image or a shading
598 into a |{pgfpicture}|.
599
600 \begin{command}{\pgftext\opt{\oarg{options}}\marg{text}}
601 This command will typeset \meta{text} in normal \TeX\ mode and insert the
602 resulting box into the |{pgfpicture}|. The bounding box of the graphic will
603 be updated so that all of the text box is inside. By default, the text box
604 is centered at the origin, but this can be changed either by giving
605 appropriate \meta{options} or by applying an appropriate coordinate
606 transformation beforehand.
607
608 The \meta{text} may contain verbatim text. (In other words, the \meta{text}
609 ``argument'' is not a normal argument, but is put in a box and some
610 |\aftergroup| hackery is used to find the end of the box.)
611
612 \pgfname's current (high-level) coordinate transformation is synchronized
613 with the canvas transformation matrix temporarily when the text box is
614 inserted. The effect is that if there is currently a high-level rotation
615 of, say, 30 degrees, the \meta{text} will also be rotated by thirty
616 degrees. If you do not want this effect, you have to (possibly temporarily)
617 reset the high-level transformation matrix.
618
619 The \meta{options} keys are used with the path |/pgf/text/|. The following
620 keys are defined for this path:
621 %
622 \begin{key}{/pgf/text/left}
623 The key causes the text box to be placed such that its left border is
624 on the origin.
625 %
626 \begin{codeexample}[]
627 \tikz{\draw[help lines] (-1,-.5) grid (1,.5);
628 \pgftext[left] {lovely}}
629 \end{codeexample}
630 \end{key}
631 %
632 \begin{key}{/pgf/text/right}
633 The key causes the text box to be placed such that its right border is
634 on the origin.
635 %
636 \begin{codeexample}[]
637 \tikz{\draw[help lines] (-1,-.5) grid (1,.5);
638 \pgftext[right] {lovely}}
639 \end{codeexample}
640 \end{key}
641 %
642 \begin{key}{/pgf/text/top}
643 This key causes the text box to be placed such that its top is on the
644 origin. This option can be used together with the |left| or |right|
645 option.
646 %
647 \begin{codeexample}[]
648 \tikz{\draw[help lines] (-1,-.5) grid (1,.5);
649 \pgftext[top] {lovely}}
650 \end{codeexample}
651 %
652 \begin{codeexample}[]
653 \tikz{\draw[help lines] (-1,-.5) grid (1,.5);
654 \pgftext[top,right] {lovely}}
655 \end{codeexample}
656 \end{key}
657 %
658 \begin{key}{/pgf/text/bottom}
659 This key causes the text box to be placed such that its bottom is on
660 the origin.
661 %
662 \begin{codeexample}[]
663 \tikz{\draw[help lines] (-1,-.5) grid (1,.5);
664 \pgftext[bottom] {lovely}}
665 \end{codeexample}
666 %
667 \begin{codeexample}[]
668 \tikz{\draw[help lines] (-1,-.5) grid (1,.5);
669 \pgftext[bottom,right] {lovely}}
670 \end{codeexample}
671 \end{key}
672 %
673 \begin{key}{/pgf/text/base}
674 This key causes the text box to be placed such that its baseline is on
675 the origin.
676 %
677 \begin{codeexample}[]
678 \tikz{\draw[help lines] (-1,-.5) grid (1,.5);
679 \pgftext[base] {lovely}}
680 \end{codeexample}
681 %
682 \begin{codeexample}[]
683 \tikz{\draw[help lines] (-1,-.5) grid (1,.5);
684 \pgftext[base,right] {lovely}}
685 \end{codeexample}
686 \end{key}
687 %
688 \begin{key}{/pgf/text/at=\meta{point}}
689 Translates the origin (that is, the point where the text is shown) to
690 \meta{point}.
691 %
692 \begin{codeexample}[]
693 \tikz{\draw[help lines] (-1,-.5) grid (1,.5);
694 \pgftext[base,at={\pgfpoint{1cm}{0cm}}] {lovely}}
695 \end{codeexample}
696 \end{key}
697 %
698 \begin{key}{/pgf/text/x=\meta{dimension}}
699 Translates the origin by \meta{dimension} along the $x$-axis.
700 %
701 \begin{codeexample}[]
702 \tikz{\draw[help lines] (-1,-.5) grid (1,.5);
703 \pgftext[base,x=1cm,y=-0.5cm] {lovely}}
704 \end{codeexample}
705 \end{key}
706 %
707 \begin{key}{/pgf/text/y=\meta{dimension}}
708 This key works like the |x| option.
709 \end{key}
710 %
711 \begin{key}{/pgf/text/rotate=\meta{degree}}
712 Rotates the coordinate system by \meta{degree}. This will also rotate
713 the text box.
714 %
715 \begin{codeexample}[]
716 \tikz{\draw[help lines] (-1,-.5) grid (1,.5);
717 \pgftext[base,x=1cm,y=-0.5cm,rotate=30] {lovely}}
718 \end{codeexample}
719 \end{key}
720 \end{command}
721
722
723 \subsection{Object Identifiers}
724
725 Graphical objects can have an \emph{identifier,} which allows you to reference
726 the object later on. For instance, you could reference the object as the target
727 of a hyperlink (although this capability is not necessarily implemented by
728 drivers) or as the target of an animation; indeed, animations always need an
729 object identifier to identify the to-be-animated object.
730
731 Attaching an identifier to an object is a two-step process:
732 %
733 \begin{enumerate}
734 \item You call |\pgfuseid{|\meta{id}|}| to choose an id, which is a normal
735 string.
736 \item Next, you call one of several commands like |\pgfidscope| or
737 |\pgftext|, which create an object. This object will have then have the
738 id.
739 \end{enumerate}
740
741
742 \subsubsection{Commands for Creating Graphic Objects}
743
744 The following system level commands create an object with an id:
745 %
746 \begin{enumerate}
747 \item |\pgfsys@begin@idscope|, which creates a graphic scope.
748 \item |\pgfsys@viewboxmeet| or |\pgfsys@viewboxslice|, which create view
749 boxes,
750 \item |\pgfsys@fill|, |\pgfsys@stroke|, and all other path usage command,
751 \item |\pgfsys@hbox| or |\pgfsys@hboxsynced|, which create text boxes, and
752 \item |\pgfsys@animate...|, which create animations.
753 \end{enumerate}
754
755 These system layer commands are, in turn, called by the following basic layer
756 commands (and, also, by the commands that call them, in turn):
757 %
758 \begin{itemize}
759 \item |\pgfidscope|, which creates an id scope (see below).
760 \item |\pgfviewboxscope|, which creates a view box.
761 \item |\pgfusepath|, which creates a path.
762 \item |\pgftext| and |\pgfnode| and |\pgfmultipartnode|, which create text
763 boxes and nodes, and
764 \item |\pgfanimateattribute|, which creates an animation.
765 \end{itemize}
766
767 \begin{environment}{{pgfidscope}}
768 Creates a graphic scope that will have the id last used with |\pgfuseid|
769 attached to, provided such an id was set and was not already used with
770 another object. In the latter cases, no graphic scope is created. Thus, if
771 you wish to ensure that a graphic scope is created, you must (additionally)
772 call |\pgfscope| inside or outside the id scope.
773 \end{environment}
774
775 The Plain\TeX\ and Con\TeX t versions of the environment are:
776 %
777 \begin{plainenvironment}{{pgfidscope}}
778 \end{plainenvironment}
779
780 \begin{contextenvironment}{{pgfidscope}}
781 \end{contextenvironment}
782
783
784 \subsubsection{Settings and Querying Identifiers}
785
786 In order to attach an identifier to an object, you first use the following
787 command:
788
789 \begin{command}{\pgfuseid\marg{name}}
790 The \meta{name} is a string by which the object will be referenced (see
791 |\pgfidrefnextuse|). The next time a graphic object is created in the
792 current \TeX\ scope, the name will be attached to it (actually, it will get
793 a system layer identifier attached to it that is automatically created
794 using |\pgfsys@new@id|, the \meta{name} is bound to that identifier and it
795 can be retrieved using |\pgfidrefnextuse|). This holds true only for the
796 next object: If a second object is created, it will not get the name
797 attached to it. This does not mean, however, that you cannot attach the
798 same name to different objects; you just need to call |\pgfuseid| again
799 before each object.
800
801 Besides the \meta{name} (or, more precisely, besides the system layer
802 identifier it refers to), the current \emph{identifier type} is also
803 important: Actually, a graphic object is not referenced by a system layer
804 identifier, but by the combination of the identifier and a type. You can
805 use the following commands for modifying the type used for the creation of
806 objects:
807
808 \begin{command}{\pgfusetype\marg{type}}
809 Sets the type used for the referencing of graphic objects for the
810 current scope to \meta{type} or, if \meta{type} starts with a dot,
811 appends \meta{type} to the current type.
812
813 You use this command with compound graphic objects: Before each part of
814 a graphic object, set the type to an appropriate value. Now, if the
815 object is named using |\pgfuseid|, you can later on access all parts of
816 the compound object using the combination of the \meta{name} used with
817 |\pgfuseid| and the type of the part.
818
819 As an example, this system is used to give you access to the different
820 parts of a node: When you say |\pgfuseid{mynode}| and then create a
821 node, you can use |mynode| with the empty type to reference the
822 graphics scope that encompasses the whole node, but also |mynode|
823 together with the type |background| to access the background path of
824 the node.
825
826 In detail, \pgfname\ uses this command to set the following types:
827 %
828 \begin{itemize}
829 \item Inside the command |\pgfviewboxscope|, the type |.view| is
830 used for the view object.
831 \item Inside the command |\pgfmultipartnode|, the type
832 |.behind background| is used for the scope of drawings behind
833 the background. Similarly, |.before background| and
834 |.behind foreground| and finally |.before foreground| are used
835 with the respective parts of a node.
836 \item Also inside a node, |.background| and |.foreground| are used
837 as types of the background and foreground paths, respectively.
838 \item Finally, inside a node, for each text part, the text part's
839 name is used as a type (so |.text| is used for the main part).
840 \end{itemize}
841
842 In addition, \tikzname\ uses this command in the following
843 situations:
844 %
845 \begin{itemize}
846 \item The type |.path| is used with a named path (named using the
847 |name| key). This is the graphic object you need to reference
848 when you wish to morph a path.
849 \item The type |.path picture| is used with the scope of the
850 optional path picture.
851 \item The type |.path fill| is used with the path used for filling.
852 This is not the same as the normal path in case the path is
853 filled and patterned, for instance.
854 \item The type |.path shade| is used with the path used for shading
855 a path.
856 \end{itemize}
857 \end{command}
858
859 \begin{command}{\pgfpushtype}
860 Pushes the current type on an internal global stack. The idea is to
861 allow you to temporarily change the current type without having to open
862 a \TeX\ scope.
863 \end{command}
864
865 \begin{command}{\pgfpoptype}
866 Restores the most recent type from the internal global stack of types.
867 \end{command}
868 \end{command}
869
870 \begin{command}{\pgfclearid}
871 Clears the current id (and type) for the local scope.
872 \end{command}
873
874 \begin{command}{\pgfidrefnextuse\marg{macro}\marg{name}}
875 This command assigns a system layer identifier (the identifier returned by
876 |\pgfsys@new@id|) to the \meta{macro}, namely the one that will be used the
877 \emph{next} time |\pgfuseid| is used. You use this command for ``forward
878 referencing''.
879
880 A typical use case is the following: A key like |whom| for animations uses
881 this command to get the system identifier that will be used for a future
882 object. Then, this identifier can be passed to system layer commands like
883 |\pgfsys@animation@whom|.
884
885 Note that the ``next'' use need not be on the same page (or there may not
886 even be any use at all), in which case the reference will not refer to any
887 object.
888 \end{command}
889
890 \begin{command}{\pgfidrefprevuse\marg{macro}\marg{name}}
891 Works like |\pgfidrefnextuse|, only it references the most recent
892 \emph{previous} use of the \meta{name}. As for |\pgfidrefnextuse|, the most
893 recent use need not be on the same page.
894 \end{command}
895
896 \begin{command}{\pgfaliasid\marg{alias}\marg{name}}
897 Creates an alias of a name inside the current \TeX\ scope. After calling
898 this command, you can use \meta{alias} anywhere where you would normally
899 use \meta{name}. Note that the binding between \meta{alias} and \meta{name}
900 is not kept when |\pgfuseid| is used on the \meta{name} (or the
901 \meta{alias}).
902 \end{command}
903
904 \begin{command}{\pgfgaliasid\marg{1}\marg{2}}
905 Like |\pgfaliasid|, only the alias is set globally.
906 \end{command}
907
908 \begin{command}{\pgfifidreferenced\marg{name}\marg{then code}\marg{else code}}
909 If \meta{name} has been referenced, \meta{then code} is executed, otherwise
910 \meta{else code}.
911 \end{command}
912
913
914 \subsection{Resource Description Framework Annotations (RDFa)}
915 \label{section-base-rdf}
916
917 With certain output formats (in particular, with \textsc{svg}) you can insert
918 annotations into the output file following the standard set by the
919 \emph{resource description framework} (known as ``\textsc{rdf}'', please
920 consult the literature on \textsc{rdf} and \textsc{rdf}a for an introduction to
921 resource descriptions and ontologies and their purpose in general). To do so,
922 you call one (or several) of the following commands before you call
923 |\pgfidscope|. The attributes and values you specify using the commands will
924 then be added to the resulting scope (if the driver supports this, which is
925 only the case for \textsc{svg} at the moment). As an example, when you write
926 %
927 \begin{codeexample}[code only]
928 \pgfrdfresource{/fruits/apple}
929 \pgfidscope
930 ...
931 \pgfendidscope
932 \end{codeexample}
933
934 in the resulting \textsc{svg} file you get
935 %
936 \begin{codeexample}[code only]
937 <g resource="/fruits/apple">
938 ...
939 </g>
940 \end{codeexample}
941
942 Most of the following commands just set a single attribute for the next id
943 scope. In some cases, however, repeated calling of these commands makes sense
944 and causes the passed values to accumulate as in the following example:
945 %
946 \begin{codeexample}[code only]
947 \pgfrdfresource{/fruits/apple}
948 \pgfrdfproperty{http://foo.com/props/juicy}
949 \pgfrdfproperty{http://foo.com/props/green}
950 \pgfidscope
951 ...
952 \pgfendidscope
953 \end{codeexample}
954
955 Now you get:
956 %
957 \begin{codeexample}[code only]
958 <g resource="/fruits/apple"
959 property="http://foo.com/props/juicy http://foo.com/props/green">
960 ...
961 </g>
962 \end{codeexample}
963
964 The following commands ``accumulate'': |\pgfrdfproperty|, |\pgfrdfrel|,
965 |\pgfrdfrev| and also the command |\pgfrdftypeof|.
966
967 \begin{command}{\pgfrdfabout\marg{text}}
968 Adds the \textsc{rdf} attribute |about="|\meta{text}|"| to the next id
969 scope (please see the \textsc{rdf}a specification for details on the
970 semantics of |about| in the context of the resource description framework).
971 \end{command}
972
973 The following commands work the same way.
974
975 \begin{command}{\pgfrdfcontent\marg{text}}
976 \end{command}
977
978 \begin{command}{\pgfrdfdatatype\marg{text}}
979 \end{command}
980
981 \begin{command}{\pgfrdfhref\marg{text}}
982 \end{command}
983
984 \begin{command}{\pgfrdfinlist}
985 \end{command}
986
987 \begin{command}{\pgfrdfprefix\marg{text}}
988 \end{command}
989
990 \begin{command}{\pgfrdfproperty\marg{text}}
991 \end{command}
992
993 \begin{command}{\pgfrdfrel\marg{text}}
994 \end{command}
995
996 \begin{command}{\pgfrdfresource\marg{text}}
997 \end{command}
998
999 \begin{command}{\pgfrdfrev\marg{text}}
1000 \end{command}
1001
1002 \begin{command}{\pgfrdfsrc\marg{text}}
1003 \end{command}
1004
1005 \begin{command}{\pgfrdftypeof\marg{text}}
1006 \end{command}
1007
1008 \begin{command}{\pgfrdfvocab\marg{text}}
1009 \end{command}
1010
1011
1012 \subsection{Error Messages and Warnings}
1013
1014 Sometimes, a command inside \pgfname\ may fail. In this case, two commands are
1015 useful to communicate with the author:
1016
1017 \begin{command}{\pgferror\marg{message}}
1018 Stops the processing of the current document and prints out the
1019 \meta{message}. In \LaTeX, this will be done using |\PackageError|,
1020 otherwise |\errmessage| is used directly.
1021 \end{command}
1022
1023 \begin{command}{\pgfwarning\marg{message}}
1024 Prints the \meta{message} on the output, but does not interrupt the
1025 processing. In \LaTeX, this will be done using |\PackageWarning|, otherwise
1026 a write to stream $17$ is used.
1027 \end{command}