[next] [prev] [prev-tail] [tail] [up]

### 19 Hierarchical Structures:
Package, Environments, Scopes, and Text

#### 19.1 Overview

PGF 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, PGF allows you to structure your graphics hierarchically using environments and scopes.

##### 19.1.1 The Hierarchical Structure of the Package

The PGF system consists of several layers:

System layer.
  The lowest layer is called the 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 V.

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.

Frontend layer.
  The frontend layer is not loaded by a single packages. Rather, different packages, like TikZ or PGFPICT2E, are different frontends to the basic layer.

  The TikZ frontend is documented in Part II.

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 III.

##### 19.1.2 The Hierarchical Structure of Graphics

Graphics in PGF 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 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:

1. The “outermost” scope supported by PGF is the {pgfpicture} environment. All changes to the graphic state done inside a {pgfpicture} are local to that picture.

   In general, it is not possible to set graphic parameters globally outside any {pgfpicture} environments. Thus, you can 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.)

2. 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. 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.

3. 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}.

4. 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}.
5. 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.

Most of the complications can be avoided if you stick to the following rules:

- Give graphic commands only inside {pgfpicture} environments.
- Use {pgfscope} to structure graphics.
- Do not use TEX groups inside graphics, except for keeping the effect of coordinate transformations local.

#### 19.2 The Hierarchical Structure of the Package

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

##### 19.2.1 The Main Package

To use PGF, include the following package:

\usepackage{pgf} % LATEX
\input pgf.tex % plain TEX
\input pgf.tex % ConTEXt

  This package loads the complete “basic layer” of PGF. That is, it will load all of the commands described in the current part of this manual, but it will not load frontends like TikZ.

  In detail, this package will load the following packages, each of which can also be loaded individually:

  - pgfsys, which is the lowest layer of PGF and which is always needed. This file will read pgf.cfg to discern which driver is to be used. See Section 32.1 for details.
  - pgfcore, which is the central core of PGF and which is always needed unless you intend to write a new basic layer from scratch.
  - pgfbaseimage, which provides commands for declaring and using images. An example is \pgfuseimage.
  - pgfbaseshapes, which provides commands for declaring and using shapes. An example is \pgfdeclareshape.
  - pgfbaseplot, which provides commands for plotting functions.

  Including any of the last three packages will automatically load the first two.

In LATEX, the package takes two options:

\usepackage[draft]{pgf}

  When this option is set, all images will be replaced by empty rectangles. This can speedup compilation.

\usepackage[version=<version>]{pgf}

  Indicates that the commands of version <version> need to be defined. If you set <version> to 0.65, then a large bunch of “compatibility commands” are loaded. If you set <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.

##### 19.2.2 The Core Package

\usepackage{pgfcore} % LATEX
\input pgfcore.tex % plain TEX
\input pgfcore.tex % ConTEXt

  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.”

##### 19.2.3 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):

- pgfbaseshapes This package provides commands for drawing nodes and shapes. These commands are explained in Section 25.
- pgfbaseplot This package provides commands for plotting function. The commands are explained in Section 29.
- pgfbaseimage This package provides commands for including (external) images. The commands are explained in Section 27.

#### 19.3 The Hierarchical Structure of the Graphics

##### 19.3.1 The Main Environment

Most, but not all, commands of the PGF 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 inside a {pgfpicture} environment.

\begin{pgfpicture}
<environment contents>
\end{pgfpicture}

  This environment will insert a TEX box containing the graphic drawn by the <environment contents> at the current position.

  The size of the bounding box. The size of the box is determined in the following manner: While PGF parses the <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 PGF 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 <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.

  Hello
  World!

  Hello \begin{pgfpicture} \pgfpathrectangle{\pgfpointorigin}{\pgfpoint{2ex}{1ex}} \pgfusepath{stroke} \end{pgfpicture} World!

  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 23.5.

  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:

  Rectangles
  and
  .

  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}.

  You can change the baseline using the \pgfsetbaseline command, see below.

  Rectangles
  and
  .

  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}.

  Including text and images in a picture. You cannot directly include text and images in a picture. Thus, you should 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 19.3.3 for details.

\pgfpicture
<environment contents>
\endpgfpicture

  The plain TEX version of the environment. Note that in this version, also, a TEX group is created around the environment.

\pgfsetbaseline{<dimension>}

  This command specifies a y-coordinate of the picture that should be used as the baseline of the whole picture. When a PGF picture has been typeset completely, PGF 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.

  Text
  ,
  ,
  ,
  .

  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}}.

##### 19.3.2 Graphic Scope Environments

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

\begin{pgfscope}
<environment contents>
\end{pgfscope}

  All changes to the graphic state done inside this environment are local to the environment. The graphic state includes the following:

  - The line width.
  - The stroke and fill colors.
  - The dash pattern.
  - The line join and cap.
  - The miter limit.
  - The canvas transformation matrix.
  - The clipping path.

  Other parameters may also influence how graphics are rendered, but they are 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{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}

  \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}

  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 not to introduce TEX groups inside a {pgfscope} environment.

\pgfscope
<environment contents>
\endpgfscope

  Plain TEX version of the {pgfscope} environment.

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

\begin{pgfinterruptpath}
<environment contents>
\end{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 PGF to use a specific arrow tip kind. When the arrow tip needs to be rendered for the first time, PGF 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 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.

\begin{pgfinterruptpicture}
<environment contents>
\end{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{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

##### 19.3.3 Inserting Text and Images

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 also use the \pgftext command to insert an image or a shading into a {pgfpicture}.

\pgftext[<options>]{<text>}

  This command will typeset <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 <options> or by applying an appropriate coordinate transformation beforehand.

  The <text> may contain verbatim text. (In other words, the <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.)

  PGF’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 <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 <options> may be given as conveniences:

  - left causes the text box to be placed such that its left border is on the origin.

    \tikz{\draw[help lines] (-1,-.5) grid (1,.5); \pgftext[left] {lovely}}

  - right causes the text box to be placed such that its right border is on the origin.

    \tikz{\draw[help lines] (-1,-.5) grid (1,.5); \pgftext[right] {lovely}}

  - 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.

    \tikz{\draw[help lines] (-1,-.5) grid (1,.5); \pgftext[top] {lovely}}

    \tikz{\draw[help lines] (-1,-.5) grid (1,.5); \pgftext[top,right] {lovely}}

  - bottom causes the text box to be placed such that its bottom is on the origin.

    \tikz{\draw[help lines] (-1,-.5) grid (1,.5); \pgftext[bottom] {lovely}}

    \tikz{\draw[help lines] (-1,-.5) grid (1,.5); \pgftext[bottom,right] {lovely}}

  - base causes the text box to be placed such that its baseline is on the origin.

    \tikz{\draw[help lines] (-1,-.5) grid (1,.5); \pgftext[base] {lovely}}

    \tikz{\draw[help lines] (-1,-.5) grid (1,.5); \pgftext[base,right] {lovely}}

  - at=<point> Translates the origin (that is, the point where the text is shown) to <point>.

    \tikz{\draw[help lines] (-1,-.5) grid (1,.5); \pgftext[base,at={\pgfpoint{1cm}{0cm}}] {lovely}}

  - x=<dimension> Translates the origin by <dimension> along the x-axis.

    \tikz{\draw[help lines] (-1,-.5) grid (1,.5); \pgftext[base,x=1cm,y=-0.5cm] {lovely}}

  - y=<dimension> works like the x option.
  - rotate=<degree> Rotates the coordinate system by <degree>. This will also rotate the text box.

    \tikz{\draw[help lines] (-1,-.5) grid (1,.5); \pgftext[base,x=1cm,y=-0.5cm,rotate=30] {lovely}}

[next] [prev] [prev-tail] [front] [up]