% Copyright 2006 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}{\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}

The following modules are available for use with |pgfcore|:

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



\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{-to}
      \pgfpathmoveto{\pgfpointorigin}\pgfpathlineto{\pgfpoint{2ex}{2ex}}
      \pgfusepath{stroke}
    }
    \pgfpathmoveto{\pgfpoint{3ex}{0ex}}\pgfpathlineto{\pgfpoint{5ex}{2ex}}
    \pgfusepath{stroke}
  \end{pgfscope}
  \pgfpathmoveto{\pgfpoint{6ex}{0ex}}\pgfpathlineto{\pgfpoint{8ex}{2ex}}
  \pgfusepath{stroke}
\end{pgfpicture}
\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/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.
\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{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}
