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