summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-scopes.tex
blob: d6841908568035366d3b00a63c9d7c857ba933e5 (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
% Copyright 2006 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 |pgf|. Some
  applications do not need all of the functionality of the basic
  layer, so it is possible to load only the |pgfcore| and some other
  packages starting with |pgfbase|.

  The basic layer is documented in the present part.
\item[Frontend layer.]
  The frontend layer is not loaded by a single packages. 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 possibly 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 Main Package}

To use \pgfname, include the following package:

\begin{package}{pgf}
  This package loads the complete ``basic layer'' of \pgfname. 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.

  In detail, this package will load the following packages, each of
  which can also be loaded individually:
  \begin{itemize}
  \item
    |pgfsys|, which is the lowest layer of \pgfname\ and which is
    always needed. This file will read |pgf.cfg| to discern which
    driver is to be used. See Section~\ref{section-pgfsys} for
    details. 
  \item
    |pgfcore|, which is the central core of \pgfname\ and which is
    always needed unless you intend to write a new basic layer from
    scratch.
  \item
    |pgfbaseimage|, which provides commands for declaring and
    using images. An example is |\pgfuseimage|.
  \item
    |pgfbaseshapes|, which provides commands for declaring and using
    shapes. An example is |\pgfdeclareshape|.
  \item
    |pgfbaseplot|, which provides commands for plotting functions.    
  \end{itemize}

  Including any of the last three packages will automatically load the
  first two.
\end{package}

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}


\subsubsection{The Core Package}

\begin{package}{pgfcore}
  This package defines all of the basic layer's commands, except for
  the commands defined in the additional packages like
  |pgfbaseplot|. Typically commands defined by the core include
  |\pgfusepath| or   |\pgfpoint|. The core is internally structured
  into several subpackages, but the subpackages cannot be loaded
  individually since they are all ``interrelated.''
\end{package}


\subsubsection{The Optional Basic Layer Packages}

The |pgf| package automatically loads the following packages, but you
can also load them individually (all of them automatically include the
core):

\begin{itemize}
  \item |pgfbaseshapes|
  This package provides commands for drawing nodes and shapes. These
  commands are explained in Section~\ref{section-shapes}.

  \item |pgfbaseplot|
  This package provides commands for plotting function. The
  commands are explained in Section~\ref{section-plots}.

  \item |pgfbaseimage|
  This package provides commands for including (external) images. The 
  commands are explained in Section~\ref{section-images}.
\end{itemize}



\subsubsection{The Library Packages}

There is a special command for loading library packages.

\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 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} has 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 typset, 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}|-environment, 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 another height.

\begin{codeexample}[]
Text \tikz{\pgfpathcircle{\pgfpointorigin}{1ex}\pgfusepath{stroke}},
     \tikz{\pgfsetbaseline{0pt}
          \pgfpathcircle{\pgfpointorigin}{1ex}\pgfusepath{stroke}},
     \tikz{\pgfsetbaseline{.5ex}
          \pgfpathcircle{\pgfpointorigin}{1ex}\pgfusepath{stroke}},
     \tikz{\pgfsetbaseline{-1ex}
          \pgfpathcircle{\pgfpointorigin}{1ex}\pgfusepath{stroke}}.
\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
\tikz{
  \pgfsetbaselinepointlater{\pgfpointanchor{X}{base}}
  % Note: no shape X, yet
  \node [cross out,draw] (X) {world.};
}
\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{-to}
      \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}


\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. Be 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 following \meta{options} may be given as conveniences:
  \begin{itemize}
    \itemoption{left}
    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}
    \itemoption{right}
    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}
    \itemoption{top}
    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}
    \itemoption{bottom}
    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}
    \itemoption{base}
    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}
    \itemoption{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}
    \itemoption{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}
  \itemoption{y}|=|\meta{dimension}
    works like the |x| option.
  \itemoption{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{itemize}
  
\end{command}