summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-scopes.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-scopes.tex')
-rw-r--r--Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-scopes.tex1178
1 files changed, 719 insertions, 459 deletions
diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-scopes.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-scopes.tex
index 9d8e999a863..618ff86c66a 100644
--- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-scopes.tex
+++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-scopes.tex
@@ -9,296 +9,266 @@
\section[Hierarchical Structures: Package, Environments, Scopes, and Text]
-{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.
+\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:
+\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 |pgfcore| and subsequent
- use of the command |\usepgfmodule| to load additional modules of the
- basic layer.
-
- The basic layer is documented in the present part.
-\item[Frontend layer.]
- The frontend layer is not loaded by a single package. 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}.
+ \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 |pgfcore| and subsequent use
+ of the command |\usepgfmodule| to load additional modules of the basic
+ layer.
+
+ The basic layer is documented in the present part.
+ \item[Frontend layer.]
+ The frontend layer is not loaded by a single package. 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.
+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.
+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.
+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:
-
+\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 possible to use
- another |{pgfpicture}| environment inside the argument of
- |\pgftext|.
+ \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 possible 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.
+ \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.
+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 Core Package}
To use \pgfname, include the following package:
\begin{package}{pgfcore}
- This package loads the complete core of the ``basic layer'' of
- \pgfname, but not any modules. 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. It will also load the system
- layer. To load additional modules, use the |\usepgfmodule| command
- explained below.
+ This package loads the complete core of the ``basic layer'' of \pgfname,
+ but not any modules. 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. It will also load the system layer. To load additional modules,
+ use the |\usepgfmodule| command explained below.
\end{package}
The following package is just a convenience.
\begin{package}{pgf}
- This package loads the |pgfcore| and the two modules |shapes| and
- |plot|.
-
- 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}
+ This package loads the |pgfcore| and the two modules |shapes| and |plot|.
+
+ 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}
\end{package}
-
\subsubsection{The Modules}
-\begin{command}{\usepgflibrary\marg{module names}}
- Once the core has been loaded, you can use this command to load
- further modules. The modules in the \meta{module names} list should
- be separated by commas. Instead of curly braces, you can also
- use square brackets, which is something Con\TeX t users will
- like. If you try to load a module a second time, nothing will
- happen.
-
- \example |\usepgfmodule{matrix,shapes}|
-
- What this command does is to load the file
- |pgfmodule|\meta{module}|.code.tex| for each \meta{module} in
- the list of \meta{module names}. Thus, to write your own module,
- all you need to do is to place a file of the appropriate name
- somewhere \TeX\ can find it. \LaTeX, plain \TeX, and Con\TeX t
- users can then use your library.
-\end{command}
+\begin{command}{\usepgfmodule\marg{module names}}
+ Once the core has been loaded, you can use this command to load further
+ modules. The modules in the \meta{module names} list should be separated by
+ commas. Instead of curly braces, you can also use square brackets, which is
+ something Con\TeX t users will like. If you try to load a module a second
+ time, nothing will happen.
-The following modules are available for use with |pgfcore|:
+ \example |\usepgfmodule{matrix,shapes}|
+ What this command does is to load the file
+ |pgfmodule|\meta{module}|.code.tex| for each \meta{module} in the list of
+ \meta{module names}. Thus, to write your own module, all you need to do is
+ to place a file of the appropriate name somewhere \TeX\ can find it.
+ \LaTeX, plain \TeX, and Con\TeX t users can then use your library.
+\end{command}
+
+The following modules are available for use with |pgfcore|: \todosp{In the
+meantime there are some more modules. Also mention them here?}
+%
\begin{itemize}
-\item The |plot| module provides commands for plotting functions. The
- commands are explained in Section~\ref{section-plots}.
-\item The |shapes| module provides commands for drawing shapes and
- nodes. These commands are explained in
- Section~\ref{section-shapes}.
-\item The |decorations| module provides commands for adding
- decorations to paths. These commands are explained in
- Section~\ref{section-base-decorations}.
-\item The |matrix| module provides the |\pgfmatrix| command. The
- commands are documented in Section~\ref{section-base-matrices}.
+ \item The |plot| module provides commands for plotting functions. The
+ commands are explained in Section~\ref{section-plots}.
+ \item The |shapes| module provides commands for drawing shapes and nodes.
+ These commands are explained in Section~\ref{section-shapes}.
+ \item The |decorations| module provides commands for adding decorations to
+ paths. These commands are explained in
+ Section~\ref{section-base-decorations}.
+ \item The |matrix| module provides the |\pgfmatrix| command. The commands
+ are documented in Section~\ref{section-base-matrices}.
\end{itemize}
-
\subsubsection{The Library Packages}
-There is a special command for loading library packages. The
-difference between a library and module is the following: A library
-just defines additional objects using the basic layer, whereas a
-module adds completely new functionality. For instance, a decoration
-library defines additional decorations, while a decoration module
-defines the whole code for handling decorations.
+There is a special command for loading library packages. The difference between
+a library and module is the following: A library just defines additional
+objects using the basic layer, whereas a module adds completely new
+functionality. For instance, a decoration library defines additional
+decorations, while a decoration module defines the whole code for handling
+decorations.
\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 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}
+ 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 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.
+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} have 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.
-
+ 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} have 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}}
@@ -306,22 +276,21 @@ Hello \begin{pgfpicture}
\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:
-
+ 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}}
@@ -332,9 +301,8 @@ Rectangles \begin{pgfpicture}
\end{pgfpicture}.
\end{codeexample}
- You can change the baseline using the |\pgfsetbaseline| command, see
- below.
-
+ You can change the baseline using the |\pgfsetbaseline| command, see below.
+ %
\begin{codeexample}[]
Rectangles \begin{pgfpicture}
\pgfpathrectangle{\pgfpointorigin}{\pgfpoint{2ex}{1ex}}
@@ -347,79 +315,77 @@ Rectangles \begin{pgfpicture}
\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 typeset, 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}|-en\-vi\-ron\-ment, 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.
+
+ \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 typeset, 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}|-en\-vi\-ron\-ment, 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.
+ 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.
+ 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.
+ 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 a different height.
-
+ 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 a different
+ height.
+ %
\begin{codeexample}[]
Text
\begin{pgfpicture}
@@ -438,19 +404,18 @@ Text
\pgfpathcircle{\pgfpointorigin}{1ex}\pgfusepath{stroke}
\end{pgfpicture}.
\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.
+ 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.
-
+ 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
\begin{pgfpicture}
@@ -459,42 +424,37 @@ Hello
\pgfnode{cross out}{center}{world.}{X}{\pgfusepath{stroke}}
\end{pgfpicture}
\end{codeexample}
+ %
\end{command}
-
\subsubsection{Graphic Scope Environments}
-Inside a |{pgfpicture}| environment you can substructure your picture
-using the following environment:
+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.
-
+ 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}
@@ -527,63 +487,59 @@ using the following environment:
\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.
+ 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.
+ 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.
+ Plain \TeX\ version of the |{pgfscope}| environment.
\end{plainenvironment}
\begin{contextenvironment}{{pgfscope}}
- This is the Con\TeX t version of the environment.
+ 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.
+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.
+ 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.
+ Plain \TeX\ version of the environment.
\end{plainenvironment}
\begin{contextenvironment}{{pgfinterruptpath}}
- Con\TeX t version of the environment.
+ 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}|.
-
+ 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
@@ -602,166 +558,470 @@ user.
\pgfusepath{stroke}
\end{pgfpicture}\hskip3.9cm
\end{codeexample}
+ %
\end{environment}
\begin{plainenvironment}{{pgfinterruptpicture}}
- Plain \TeX\ version of the environment.
+ Plain \TeX\ version of the environment.
\end{plainenvironment}
\begin{contextenvironment}{{pgfinterruptpicture}}
- Con\TeX t version of the environment.
+ Con\TeX t version of the environment.
\end{contextenvironment}
-
-
\begin{environment}{{pgfinterruptboundingbox}}
- This environment temporarily interrupts the computation of the
- bounding box and sets up a new bounding box. At the beginning of the
- environment the old bounding box is saved and an empty bounding box
- is installed. After the environment the original bounding box is
- reinstalled as if nothing has happened.
+ This environment temporarily interrupts the computation of the bounding box
+ and sets up a new bounding box. At the beginning of the environment the old
+ bounding box is saved and an empty bounding box is installed. After the
+ environment the original bounding box is reinstalled as if nothing has
+ happened.
\end{environment}
\begin{plainenvironment}{{pgfinterruptboundingbox}}
- Plain \TeX\ version of the environment.
+ Plain \TeX\ version of the environment.
\end{plainenvironment}
\begin{contextenvironment}{{pgfinterruptboundingbox}}
- Con\TeX t version of the environment.
+ 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.
+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}|.
+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. By 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 \meta{options} keys are used with the path |/pgf/text/|. The
- following keys are defined for this path:
- \begin{key}{/pgf/text/left}
- The key causes the text box to be placed such that its left
- border is on the origin.
+ 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. By 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 \meta{options} keys are used with the path |/pgf/text/|. The following
+ keys are defined for this path:
+ %
+ \begin{key}{/pgf/text/left}
+ The key 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}
- \end{key}
- \begin{key}{/pgf/text/right}
- The key causes the text box to be placed such that its right
- border is on the origin.
+ \end{key}
+ %
+ \begin{key}{/pgf/text/right}
+ The key 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}
- \end{key}
- \begin{key}{/pgf/text/right}
- This key 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.
+ \end{key}
+ %
+ \begin{key}{/pgf/text/top}
+ This key 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}
- \end{key}
- \begin{key}{/pgf/text/bottom}
- This key causes the text box to be placed such that its bottom is
- on the origin.
+ \end{key}
+ %
+ \begin{key}{/pgf/text/bottom}
+ This key 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}
- \end{key}
- \begin{key}{/pgf/text/base}
- This key causes the text box to be placed such that its baseline
- is on the origin.
+ \end{key}
+ %
+ \begin{key}{/pgf/text/base}
+ This key 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}
- \end{key}
- \begin{key}{/pgf/text/at=\meta{point}}
- Translates the origin (that is, the point where the text is
- shown) to \meta{point}.
+ \end{key}
+ %
+ \begin{key}{/pgf/text/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}
- \end{key}
- \begin{key}{/pgf/text/x=\meta{dimension}}
- Translates the origin by \meta{dimension} along the $x$-axis.
+ \end{key}
+ %
+ \begin{key}{/pgf/text/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}
- \end{key}
- \begin{key}{/pgf/text/y=\meta{dimension}}
- This key works like the |x| option.
- \end{key}
- \begin{key}{/pgf/text/rotate=\meta{degree}}
- Rotates the coordinate system by \meta{degree}. This will also
- rotate the text box.
+ \end{key}
+ %
+ \begin{key}{/pgf/text/y=\meta{dimension}}
+ This key works like the |x| option.
+ \end{key}
+ %
+ \begin{key}{/pgf/text/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{key}
+ \end{key}
+\end{command}
+
+
+\subsection{Object Identifiers}
+
+Graphical objects can have an \emph{identifier,} which allows you to reference
+the object later on. For instance, you could reference the object as the target
+of a hyperlink (although this capability is not necessarily implemented by
+drivers) or as the target of an animation; indeed, animations always need an
+object identifier to identify the to-be-animated object.
+
+Attaching an identifier to an object is a two-step process:
+%
+\begin{enumerate}
+ \item You call |\pgfuseid{|\meta{id}|}| to choose an id, which is a normal
+ string.
+ \item Next, you call one of several commands like |\pgfidscope| or
+ |\pgftext|, which create an object. This object will have then have the
+ id.
+\end{enumerate}
+
+
+\subsubsection{Commands for Creating Graphic Objects}
+
+The following system level commands create an object with an id:
+%
+\begin{enumerate}
+ \item |\pgfsys@begin@idscope|, which creates a graphic scope.
+ \item |\pgfsys@viewboxmeet| or |\pgfsys@viewboxslice|, which create view
+ boxes,
+ \item |\pgfsys@fill|, |\pgfsys@stroke|, and all other path usage command,
+ \item |\pgfsys@hbox| or |\pgfsys@hboxsynced|, which create text boxes, and
+ \item |\pgfsys@animate...|, which create animations.
+\end{enumerate}
+
+These system layer commands are, in turn, called by the following basic layer
+commands (and, also, by the commands that call them, in turn):
+%
+\begin{itemize}
+ \item |\pgfidscope|, which creates an id scope (see below).
+ \item |\pgfviewboxscope|, which creates a view box.
+ \item |\pgfusepath|, which creates a path.
+ \item |\pgftext| and |\pgfnode| and |\pgfmultipartnode|, which create text
+ boxes and nodes, and
+ \item |\pgfanimateattribute|, which creates an animation.
+\end{itemize}
+
+\begin{environment}{{pgfidscope}}
+ Creates a graphic scope that will have the id last used with |\pgfuseid|
+ attached to, provided such an id was set and was not already used with
+ another object. In the latter cases, no graphic scope is created. Thus, if
+ you wish to ensure that a graphic scope is created, you must (additionally)
+ call |\pgfscope| inside or outside the id scope.
+\end{environment}
+
+The Plain\TeX\ and Con\TeX t versions of the environment are:
+%
+\begin{plainenvironment}{{pgfidscope}}
+\end{plainenvironment}
+
+\begin{contextenvironment}{{pgfidscope}}
+\end{contextenvironment}
+
+
+\subsubsection{Settings and Querying Identifiers}
+
+In order to attach an identifier to an object, you first use the following
+command:
+
+\begin{command}{\pgfuseid\marg{name}}
+ The \meta{name} is a string by which the object will be referenced (see
+ |\pgfidrefnextuse|). The next time a graphic object is created in the
+ current \TeX\ scope, the name will be attached to it (actually, it will get
+ a system layer identifier attached to it that is automatically created
+ using |\pgfsys@new@id|, the \meta{name} is bound to that identifier and it
+ can be retrieved using |\pgfidrefnextuse|). This holds true only for the
+ next object: If a second object is created, it will not get the name
+ attached to it. This does not mean, however, that you cannot attach the
+ same name to different objects; you just need to call |\pgfuseid| again
+ before each object.
+
+ Besides the \meta{name} (or, more precisely, besides the system layer
+ identifier is refers to), the current \emph{identifier type} is also
+ important: Actually, a graphic object is not referenced by a system layer
+ identifier, but by the combination of the identifier and a type. You can
+ use the following commands for modifying the type used for the creation of
+ objects:
+
+ \begin{command}{\pgfusetype\marg{type}}
+ Sets the type used for the referencing of graphic objects for the
+ current scope to \meta{type} or, if \meta{type} starts with a dot,
+ appends \meta{type} to the current type.
+
+ You use this command with compound graphic objects: Before each part of
+ a graphic object, set the type to an appropriate value. Now, if the
+ object is named using |\pgfuseid|, you can later on access all parts of
+ the compound object using the combination of the \meta{name} used with
+ |\pgfuseid| and the type of the part.
+
+ As an example, this system is used to give you access to the different
+ parts of a node: When use say |\pgfuseid{mynode}| and then create a
+ node, you can use |mynode| with the empty type to reference the
+ graphics scope that encompasses the whole node, but also |mynode|
+ together with the type |background| to access the background path of
+ the node.
+
+ In detail, \pgfname\ uses this command to set the following types:
+ %
+ \begin{itemize}
+ \item Inside the command |\pgfviewboxscope|, the type |.view| is
+ used for the view object.
+ \item Inside the command |\pgfmultipartnode|, the type
+ |.behind background| is used for the scope of drawings behind
+ the background. Similarly, |.before background| and
+ |.behind foreground| and finally |.before foreground| are used
+ with the respective parts of a node.
+ \item Also inside a node, |.background| and |.foreground| are used
+ as types of the background and foreground paths, respectively.
+ \item Finally, inside a node, for each text part, the text part's
+ name is used as a type (so |.text| is used for the main part).
+ \end{itemize}
+
+ In addition, \tikzname\ uses this command in the following
+ situations:
+ %
+ \begin{itemize}
+ \item The type |.path| is used with a named path (named using the
+ |name| key). This is the graphic object you need to reference
+ when you wish to morph a path.
+ \item The type |.path picture| is used with the scope of the
+ optional path picture.
+ \item The type |.path fill| is used with the path used for filling.
+ This is not the same as the normal path in case the path is
+ filled and patterned, for instance.
+ \item The type |.path shade| is used with the path used for shading
+ a path.
+ \end{itemize}
+ \end{command}
+
+ \begin{command}{\pgfpushtype}
+ Pushes the current type on an internal global stack. The idea is to
+ allow you to temporarily change the current type without having to open
+ a \TeX\ scope.
+ \end{command}
+
+ \begin{command}{\pgfpoptype}
+ Restores the most recent type from the internal global stack of types.
+ \end{command}
+\end{command}
+
+\begin{command}{\pgfclearid}
+ Clears the current id (and type) for the local scope.
+\end{command}
+
+\begin{command}{\pgfidrefnextuse\marg{macro}\marg{name}}
+ This command assigns a system layer identifier (the identifier returned by
+ |\pgfsys@new@id|) to the \meta{macro}, namely the one that will be used the
+ \emph{next} time |\pgfuseid| is used. You use this command for ``forward
+ referencing''.
+
+ A typical use case is the following: A key like |whom| for animations uses
+ this command to get the system identifier that will be used for a future
+ object. Then, this identifier can be passed to system layer commands like
+ |\pgfsys@animation@whom|.
+
+ Note that the ``next'' use need not be on the same page (or there may not
+ even be any use at all), in which case the reference will not refer to any
+ object.
+\end{command}
+
+\begin{command}{\pgfidrefprevuse\marg{macro}\marg{name}}
+ Works like |\pgfidrefnextuse|, only it references the most recent
+ \emph{previous} use of the \meta{name}. As for |\pgfidrefnextuse|, the most
+ recent use need not be on the same page.
+\end{command}
+
+\begin{command}{\pgfaliasid\marg{alias}\marg{name}}
+ Creates an alias of a name inside the current \TeX\ scope. After calling
+ this command, you can use \meta{alias} anywhere where you would normally
+ use \meta{name}. Note that the binding between \meta{alias} and \meta{name}
+ is not kept when |\pgfuseid| is used on the \meta{name} (or the
+ \meta{alias}).
+\end{command}
+
+\begin{command}{\pgfgaliasid\marg{1}\marg{2}}
+ Like |\pgfaliasid|, only the alias is set globally.
+\end{command}
+
+\begin{command}{\pgfifidreferenced\marg{name}\marg{then code}\marg{else code}}
+ If \meta{name} has been referenced, \meta{then code} is executed, otherwise
+ \meta{else code}.
+\end{command}
+
+
+\subsection{Resource Description Framework Annotations (RDFa)}
+\label{section-base-rdf}
+
+With certain output formats (in particular, with \textsc{svg}) you can insert
+annotations into the output file following the standard set by the
+\emph{resource description framework} (known as ``\textsc{rdf}'', please
+consult the literature on \textsc{rdf} and \textsc{rdf}a for an introduction to
+resource descriptions and ontologies and their purpose in general). To do so,
+you call one (or several) of the following commands before you call
+|\pgfidscope|. The attributes and values you specify using the commands will
+then be added to the resulting scope (if the driver supports this, which is
+only the case for \textsc{svg} at the moment). As an example, when you write
+%
+\begin{codeexample}[code only]
+\pgfrdfresource{/fruits/apple}
+\pgfidscope
+...
+\pgfendidscope
+\end{codeexample}
+
+in the resulting \textsc{svg} file you get
+%
+\begin{codeexample}[code only]
+<g resource="/fruits/apple">
+ ...
+</g>
+\end{codeexample}
+
+Most of the following commands just set a single attribute for the next id
+scope. In some cases, however, repeated calling of these commands makes sense
+and causes the passed values to accumulate as in the following example:
+%
+\begin{codeexample}[code only]
+\pgfrdfresource{/fruits/apple}
+\pgfrdfproperty{http://foo.com/props/juicy}
+\pgfrdfproperty{http://foo.com/props/green}
+\pgfidscope
+...
+\pgfendidscope
+\end{codeexample}
+
+Now you get:
+%
+\begin{codeexample}[code only]
+<g resource="/fruits/apple"
+ property="http://foo.com/props/juicy http://foo.com/props/green">
+ ...
+</g>
+\end{codeexample}
+
+The following commands ``accumulate'': |\pgfrdfproperty|, |\pgfrdfrel|,
+|\pgfrdfrev| and also the command |\pgfrdftypeof|.
+
+\begin{command}{\pgfrdfabout\marg{text}}
+ Adds the \textsc{rdf} attribute |about="|\meta{text}|"| to the next id
+ scope (please see the \textsc{rdf}a specification for details on the
+ semantics of |about| in the context of the resource description framework).
+\end{command}
+
+The following commands work the same way.
+
+\begin{command}{\pgfrdfcontent\marg{text}}
+\end{command}
+
+\begin{command}{\pgfrdfdatatype\marg{text}}
+\end{command}
+
+\begin{command}{\pgfrdfhref\marg{text}}
+\end{command}
+
+\begin{command}{\pgfrdfinlist}
+\end{command}
+
+\begin{command}{\pgfrdfprefix\marg{text}}
+\end{command}
+
+\begin{command}{\pgfrdfproperty\marg{text}}
+\end{command}
+
+\begin{command}{\pgfrdfrel\marg{text}}
+\end{command}
+
+\begin{command}{\pgfrdfresource\marg{text}}
+\end{command}
+
+\begin{command}{\pgfrdfrev\marg{text}}
+\end{command}
+
+\begin{command}{\pgfrdfsrc\marg{text}}
+\end{command}
+
+\begin{command}{\pgfrdftypeof\marg{text}}
+\end{command}
+\begin{command}{\pgfrdfvocab\marg{text}}
\end{command}
\subsection{Error Messages and Warnings}
-Sometimes, a command inside \pgfname\ may fail. In this case, two
-commands are useful to communicate with the author:
+Sometimes, a command inside \pgfname\ may fail. In this case, two commands are
+useful to communicate with the author:
\begin{command}{\pgferror\marg{message}}
- Stops the processing of the current document and prints out the
- \meta{message}. In \LaTeX, this will be done using |\PackageError|,
- otherwise |\errmessage| is used directly.
+ Stops the processing of the current document and prints out the
+ \meta{message}. In \LaTeX, this will be done using |\PackageError|,
+ otherwise |\errmessage| is used directly.
\end{command}
\begin{command}{\pgfwarning\marg{message}}
- Prints the \meta{message} on the output, but does not interrupt the
- processing. In \LaTeX, this will be done using |\PackageWarning|,
- otherwise a write to stream $17$ is used.
+ Prints the \meta{message} on the output, but does not interrupt the
+ processing. In \LaTeX, this will be done using |\PackageWarning|, otherwise
+ a write to stream $17$ is used.
\end{command}