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.
The PGF system consists of several layers:
The system layer is documented in Part V.
The basic layer is documented in the present part.
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.
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:
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.)
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.
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}.
Most of the complications can be avoided if you stick to the following rules:
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.
To use PGF, include the following package:
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:
Including any of the last three packages will automatically load the first two.
In LATEX, the package takes two options:
When this option is set, all images will be replaced by empty rectangles. This can speedup compilation.
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.
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.”
The pgf package automatically loads the following packages, but you can also load them individually (all of them automatically include the core):
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.
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! |
|
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 . |
|
You can change the baseline using the \pgfsetbaseline command, see below.
| Rectangles and . |
|
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.
The plain TEX version of the environment. Note that in this version, also, a TEX group is created around the environment.
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 , , , . |
|
Inside a {pgfpicture} environment you can substructure your picture using the following environment:
All changes to the graphic state done inside this environment are local to the environment. The graphic state includes the following:
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.
|
|
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.
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.
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.
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}.
|
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}.
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:
|
|
|
|
|
|
|
|
|
|
|