% Copyright 2019 by Till Tantau
%
% This file may be distributed and/or modified
%
% 1. under the LaTeX Project Public License and/or
% 2. under the GNU Free Documentation License.
%
% See the file doc/generic/pgf/licenses/LICENSE for more details.


\section[Hierarchical Structures: Package, Environments, Scopes, and Text]
        {Hierarchical Structures:\\
         Package, Environments, Scopes, and Text}

\subsection{Overview}

\pgfname\ uses two kinds of hierarchical structuring: First, the package itself
is structured hierarchically, consisting of different packages that are built
on top of each other. Second, \pgfname\ allows you to structure your graphics
hierarchically using environments and scopes.


\subsubsection{The Hierarchical Structure of the Package}

The \pgfname\ system consists of several layers:
%
\begin{description}
    \item[System layer.]
        The lowest layer is called the \emph{system layer}, though it might
        also be called ``driver layer'' or perhaps ``backend layer''. Its job
        is to provide an abstraction of the details of which driver is used to
        transform the |.dvi| file. The system layer is implemented by the
        package |pgfsys|, which will load appropriate driver files as needed.

        The system layer is documented in Part~\ref{part-system}.
    \item[Basic layer.]
        The basic layer is loaded by the package |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.

In addition to the packages of these layers, there are also some library
packages. These packages provide additional definitions of things like new
arrow tips or new plot handlers.

The library packages are documented in Part~\ref{part-libraries}.


\subsubsection{The Hierarchical Structure of Graphics}

Graphics in \pgfname\ are typically structured hierarchically. Hierarchical
structuring can be used to identify groups of graphical elements that are to be
treated ``in the same way''. For example, you might group together a number of
paths, all of which are to be drawn in red. Then, when you decide later on that
you like them to be drawn in, say, blue, all you have to do is to change the
color once.

The general mechanism underlying hierarchical structuring is known as
\emph{scoping} in computer science. The idea is that all changes to the general
``state'' of the graphic that are done inside a scope are local to that scope.
So, if you change the color inside a scope, this does not affect the color used
outside the scope. Likewise, when you change the line width in a scope, the
line width outside is not changed, and so on.

There are different ways of starting and ending scopes of graphic parameters.
Unfortunately, these scopes are sometimes ``in conflict'' with each other and
it is sometimes not immediately clear which scopes apply. In essence, the
following scoping mechanisms are available:
%
\begin{enumerate}
    \item The ``outermost'' scope supported by \pgfname\ is the |{pgfpicture}|
        environment. All changes to the graphic state done inside a
        |{pgfpicture}| are local to that picture.

        In general, it is \emph{not} possible to set graphic parameters
        globally outside any |{pgfpicture}| environments. Thus, you can
        \emph{not} say |\pgfsetlinewidth{1pt}| at the beginning of your
        document to have a default line width of one point. Rather, you have to
        (re)set all graphic parameters inside each |{pgfpicture}|. (If this is
        too bothersome, try defining some macro that does the job for you.)
    \item Inside a |{pgfpicture}| you can use a |{pgfscope}| environment to
        keep changes of the graphic state local to that environment.

        The effect of commands that change the graphic state are local to the
        current |{pgfscope}|, but not always to the current \TeX\ group. Thus,
        if you open a \TeX\ group (some text in curly braces) inside a
        |{pgfscope}|, and if you change, for example, the dash pattern, the
        effect of this changed dash pattern will persist till the end of the
        |{pgfscope}|.

        Unfortunately, this is not always the case. \emph{Some} graphic
        parameters only persist till the end of the current \TeX\ group. For
        example, when you use |\pgfsetarrows| to set the arrow tip inside a
        \TeX\ group, the effect lasts only till the end of the current \TeX\
        group.
    \item Some graphic parameters are not scoped by |{pgfscope}| but
        ``already'' by \TeX\ groups. For example, the effect of coordinate
        transformation commands is always local to the current \TeX\ group.

        Since every |{pgfscope}| automatically creates a \TeX\ group, all
        graphic parameters that are local to the current \TeX\ group are also
        local to the current |{pgfscope}|.
    \item Some graphic parameters can only be scoped using \TeX\ groups, since
        in some situations it is not possible to introduce a |{pgfscope}|. For
        example, a path always has to be completely constructed and used in the
        same |{pgfscope}|. However, we might wish to have different coordinate
        transformations apply to different points on the path. In this case, we
        can use \TeX\ groups to keep the effect local, but we could not use
        |{pgfscope}|.
    \item The |\pgftext| command can be used to create a scope in which \TeX\
        ``escapes back'' to normal \TeX\ mode. The text passed to the
        |\pgftext| is ``heavily guarded'' against having any effect on the
        scope in which it is used. For example, it is 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.
\end{itemize}


\subsection{The Hierarchical Structure of the Package}

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


\subsubsection{The 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.
\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}
\end{package}


\subsubsection{The Modules}

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

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


\subsection{The Hierarchical Structure of the Graphics}

\subsubsection{The Main Environment}

Most, but not all, commands of the \pgfname\ package must be given within a
|{pgfpicture}| environment. The only commands that (must) be given outside are
commands having to do with including images (like |\pgfuseimage|) and with
inserting complete shadings (like |\pgfuseshading|). However, just to keep life
entertaining, the |\pgfshadepath| command must be given \emph{inside} a
|{pgfpicture}| environment.

\begin{environment}{{pgfpicture}}
    This environment will insert a \TeX\ box containing the graphic drawn by
    the \meta{environment contents} at the current position.


    \medskip
    \textbf{The size of the bounding box.}
    The size of the box is determined in the following manner: While \pgfname\
    parses the \meta{environment contents}, it keeps track of a bounding box
    for the graphic. Essentially, this bounding box is the smallest box that
    contains all coordinates mentioned in the graphics. Some coordinates may be
    ``mentioned'' by \pgfname\ itself; for example, when you add circle to the
    current path, the support points of the curve making up the circle are also
    ``mentioned'' despite the fact that you will not ``see'' them in your code.

    Once the \meta{environment contents} 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}}
  \pgfusepath{stroke}
\end{pgfpicture} World!
\end{codeexample}

    Sometimes, you may need more fine-grained control over the size of the
    bounding box. For example, the computed bounding box may be too large or
    you intensionally wish the box to be ``too small''. In these cases, you can
    use the command |\pgfusepath{use as bounding box}|, as described in
    Section~\ref{section-using-bb}.


    \medskip
    \textbf{The baseline of the bounding box.}
    When the box containing the graphic is inserted into the normal text, the
    baseline of the graphic is normally at the bottom of the graphic. For this
    reason, the following two sets of code lines have the same effect, despite
    the fact that the second graphic uses ``higher'' coordinates than the
    first:
    %
\begin{codeexample}[]
Rectangles \begin{pgfpicture}
  \pgfpathrectangle{\pgfpointorigin}{\pgfpoint{2ex}{1ex}}
  \pgfusepath{stroke}
\end{pgfpicture} and \begin{pgfpicture}
  \pgfpathrectangle{\pgfpoint{0ex}{1ex}}{\pgfpoint{2ex}{1ex}}
  \pgfusepath{stroke}
\end{pgfpicture}.
\end{codeexample}

    You can change the baseline using the |\pgfsetbaseline| command, see below.
    %
\begin{codeexample}[]
Rectangles \begin{pgfpicture}
  \pgfpathrectangle{\pgfpointorigin}{\pgfpoint{2ex}{1ex}}
  \pgfusepath{stroke}
  \pgfsetbaseline{0pt}
\end{pgfpicture} and \begin{pgfpicture}
  \pgfpathrectangle{\pgfpoint{0ex}{1ex}}{\pgfpoint{2ex}{1ex}}
  \pgfusepath{stroke}
  \pgfsetbaseline{0pt}
\end{pgfpicture}.
\end{codeexample}


    \medskip
    \textbf{Including text and images in a picture.}
    You cannot directly include text and images in a picture. Thus, you should
    \emph{not} simply write some text in a |{pgfpicture}| or use a command like
    |\includegraphics| or even |\pgfimage|. In all these cases, you need to
    place the text inside a |\pgftext| command. This will ``escape back'' to
    normal \TeX\ mode, see Section~\ref{section-text-command} for details.


    \medskip
    \textbf{Remembering a picture position for later reference.}
    After a picture has been 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.
\end{plainenvironment}

\begin{contextenvironment}{{pgfpicture}}
    This is the Con\TeX t version of the environment.
\end{contextenvironment}

{\let\ifpgfrememberpicturepositiononpage=\relax
\begin{command}{\ifpgfrememberpicturepositiononpage}
    Determines whether the position of pictures on the page should be recorded.
    The value of this \TeX-if at the end of a |{pgfpicture}| environment is
    important, not the value at the beginning.

    If this option is set to true of a picture, \pgfname\ will attempt to
    record the position of the picture on the page. (This attempt will fail
    with most drivers and when it works, it typically requires two runs of
    \TeX.) The position is not directly accessible. Rather, the nodes mechanism
    will use this position if you access a node from another picture. See
    Sections~\ref{section-cross-pictures-pgf}
    and~\ref{section-cross-picture-tikz} for more details.
\end{command}
}

\makeatletter
\begin{command}{\pgfsetbaseline\marg{dimension}}
    This command specifies a $y$-coordinate of the picture that should be used
    as the baseline of the whole picture. When a \pgfname\ picture has been
    typeset completely, \pgfname\ must decide at which height the baseline of
    the picture should lie. Normally, the baseline is set to the $y$-coordinate
    of the bottom of the picture, but it is often desirable to use a different
    height.
    %
\begin{codeexample}[]
Text
\begin{pgfpicture}
  \pgfpathcircle{\pgfpointorigin}{1ex}\pgfusepath{stroke}
\end{pgfpicture},
\begin{pgfpicture}
  \pgfsetbaseline{0pt}
  \pgfpathcircle{\pgfpointorigin}{1ex}\pgfusepath{stroke}
\end{pgfpicture},
\begin{pgfpicture}
  \pgfsetbaseline{.5ex}
  \pgfpathcircle{\pgfpointorigin}{1ex}\pgfusepath{stroke}
\end{pgfpicture},
\begin{pgfpicture}
  \pgfsetbaseline{-1ex}
  \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.
\end{command}

\begin{command}{\pgfsetbaselinepointlater\marg{point}}
    This command also specifies the baseline indirectly, but the $y$-coordinate
    of the given \meta{point} is only computed at the end of the picture.
    %
\begin{codeexample}[]
Hello
\begin{pgfpicture}
  \pgfsetbaselinepointlater{\pgfpointanchor{X}{base}}
  % Note: no shape X, yet
  \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:

\begin{environment}{{pgfscope}}
    All changes to the graphic state done inside this environment are
    local to the environment. The graphic state includes the following:
    %
    \begin{itemize}
        \item The line width.
        \item The stroke and fill colors.
        \item The dash pattern.
        \item The line join and cap.
        \item The miter limit.
        \item The canvas transformation matrix.
        \item The clipping path.
    \end{itemize}
    %
    Other parameters may also influence how graphics are rendered, but they are
    \emph{not} part of the graphic state. For example, the arrow tip kind is
    not part of the graphic state and the effect of commands setting the arrow
    tip kind are local to the current \TeX\ group, not to the current
    |{pgfscope}|. However, since |{pgfscope}| starts and ends a \TeX\ group
    automatically, a |{pgfscope}| can be used to limit the effect of, say,
    commands that set the arrow tip kind.
    %
\begin{codeexample}[]
\begin{pgfpicture}
  \begin{pgfscope}
    {
      \pgfsetlinewidth{2pt}
      \pgfpathrectangle{\pgfpointorigin}{\pgfpoint{2ex}{2ex}}
      \pgfusepath{stroke}
    }
    \pgfpathrectangle{\pgfpoint{3ex}{0ex}}{\pgfpoint{2ex}{2ex}}
    \pgfusepath{stroke}
  \end{pgfscope}
  \pgfpathrectangle{\pgfpoint{6ex}{0ex}}{\pgfpoint{2ex}{2ex}}
  \pgfusepath{stroke}
\end{pgfpicture}
\end{codeexample}

\begin{codeexample}[]
\begin{pgfpicture}
  \begin{pgfscope}
    {
      \pgfsetarrows{->}
      \pgfpathmoveto{\pgfpointorigin}\pgfpathlineto{\pgfpoint{2ex}{2ex}}
      \pgfusepath{stroke}
    }
    \pgfpathmoveto{\pgfpoint{3ex}{0ex}}\pgfpathlineto{\pgfpoint{5ex}{2ex}}
    \pgfusepath{stroke}
  \end{pgfscope}
  \pgfpathmoveto{\pgfpoint{6ex}{0ex}}\pgfpathlineto{\pgfpoint{8ex}{2ex}}
  \pgfusepath{stroke}
\end{pgfpicture}
\end{codeexample}

    At the start of the scope, the current path must be empty, that is, you
    cannot open a scope while constructing a path.

    It is usually a good idea \emph{not} to introduce \TeX\ groups inside a
    |{pgfscope}| environment.
\end{environment}

\begin{plainenvironment}{{pgfscope}}
    Plain \TeX\ version of the |{pgfscope}| environment.
\end{plainenvironment}

\begin{contextenvironment}{{pgfscope}}
    This is the Con\TeX t version of the environment.
\end{contextenvironment}

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

\begin{environment}{{pgfinterruptpath}}
    This environment can be used to temporarily interrupt the construction of
    the current path. The effect will be that the path currently under
    construction will be ``stored away'' and restored at the end of the
    environment. Inside the environment you can construct a new path and do
    something with it.

    An example application of this environment is the arrow tip caching.
    Suppose you ask \pgfname\ to use a specific arrow tip kind. When the arrow
    tip needs to be rendered for the first time, \pgfname\ will ``cache'' the
    path that makes up the arrow tip. To do so, it interrupts the current path
    construction and then protocols the path of the arrow tip. The
    |{pgfinterruptpath}| environment is used to ensure that this does not
    interfere with the path to which the arrow tips should be attached.

    This command does \emph{not} install a |{pgfscope}|. In particular, it does
    not call any |\pgfsys@| commands at all, which would, indeed, be dangerous
    in the middle of a path construction.
\end{environment}

\begin{plainenvironment}{{pgfinterruptpath}}
    Plain \TeX\ version of the environment.
\end{plainenvironment}

\begin{contextenvironment}{{pgfinterruptpath}}
    Con\TeX t version of the environment.
\end{contextenvironment}

\begin{environment}{{pgfinterruptpicture}}
    This environment can be used to temporarily interrupt a |{pgfpicture}|.
    However, the environment is intended only to be used at the beginning and
    end of a box that is (later) inserted into a |{pgfpicture}| using
    |\pgfqbox|. You cannot use this environment directly inside a
    |{pgfpicture}|.
    %
\begin{codeexample}[]
\begin{pgfpicture}
  \pgfpathmoveto{\pgfpoint{0cm}{0cm}} % In the middle of path, now
  \newbox\mybox
  \setbox\mybox=\hbox{
    \begin{pgfinterruptpicture}
      Sub-\begin{pgfpicture} % a subpicture
        \pgfpathmoveto{\pgfpoint{1cm}{0cm}}
        \pgfpathlineto{\pgfpoint{1cm}{1cm}}
        \pgfusepath{stroke}
      \end{pgfpicture}-picture.
    \end{pgfinterruptpicture}
  }
  \pgfqbox{\mybox}%
  \pgfpathlineto{\pgfpoint{0cm}{1cm}}
  \pgfusepath{stroke}
\end{pgfpicture}\hskip3.9cm
\end{codeexample}
    %
\end{environment}

\begin{plainenvironment}{{pgfinterruptpicture}}
    Plain \TeX\ version of the environment.
\end{plainenvironment}

\begin{contextenvironment}{{pgfinterruptpicture}}
    Con\TeX t version of the environment.
\end{contextenvironment}

\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.
\end{environment}

\begin{plainenvironment}{{pgfinterruptboundingbox}}
    Plain \TeX\ version of the environment.
\end{plainenvironment}

\begin{contextenvironment}{{pgfinterruptboundingbox}}
    Con\TeX t version of the environment.
\end{contextenvironment}


\subsubsection{Inserting Text and Images}
\label{section-text-command}

Often, you may wish to add normal \TeX\ text at a certain point inside a
|{pgfpicture}|. You cannot do so ``directly'', that is, you cannot simply write
this text inside the |{pgfpicture}| environment. Rather, you must pass the text
as an argument to the |\pgftext| command.

You must \emph{also} use the |\pgftext| command to insert an image or a shading
into a |{pgfpicture}|.

\begin{command}{\pgftext\opt{\oarg{options}}\marg{text}}
    This command will typeset \meta{text} in normal \TeX\ mode and insert the
    resulting box into the |{pgfpicture}|. The bounding box of the graphic will
    be updated so that all of the text box is inside. 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.
        %
\begin{codeexample}[]
\tikz{\draw[help lines] (-1,-.5) grid (1,.5);
     \pgftext[right] {lovely}}
\end{codeexample}
    \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.
        %
\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.
        %
\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}.
        %
\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.
        %
\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.
    %
\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{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 it 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 you 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:

\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.
\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.
\end{command}