summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-pgfkeys.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-pgfkeys.tex')
-rw-r--r--Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-pgfkeys.tex1142
1 files changed, 1142 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-pgfkeys.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-pgfkeys.tex
new file mode 100644
index 00000000000..121e8b6b768
--- /dev/null
+++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-pgfkeys.tex
@@ -0,0 +1,1142 @@
+% 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{Key Management}
+\label{section-keys}
+
+This section describes the package |pgfkeys|. It is loaded
+automatically by both \pgfname\ and \tikzname.
+
+\begin{package}{pgfkeys}
+ This package can be used independently of \pgfname. Note that no
+ other package of \pgfname\ needs to be loaded (so neither the
+ emulation layer nor the system layer is needed). The Con\TeX t
+ abbreviation is |pgfkey| if |pgfmod| is not loaded.
+\end{package}
+
+
+
+\subsection{Introduction}
+
+\subsubsection{Comparison to Other Packages}
+
+The |pgfkeys| package defines a key--value management system that is in
+some sense similar to the more light-weight |keyval| system and the
+improved |xkeyval| system. However, |pgfkeys| uses a slightly
+different philosophy than these systems and it will coexist peacefully
+with both of them.
+
+The main differences between |pgfkeys| and |xkeyval| are the
+following:
+
+\begin{itemize}
+\item |pgfkeys| organizes keys in a tree, while |keyval| and |xkeyval|
+ use families. In |pgfkeys| the families correspond to the root
+ entries of the key tree.
+\item For efficiency reasons, |pgfkeys| does not directly support
+ setting keys drawn from multiple families as |xkeyval| does. This
+ can be emulated if necessary, but it will be slower than |xkeyval|'s
+ native support.
+\item |pgfkeys| has no save-stack impact (you will have to read the
+ \TeX Book very carefully to appreciate this).
+\item |pgfkeys| is slightly slower than |keyval|, but not much.
+\item |pgfkeys| supports styles. This means that keys can just stand
+ for other keys (which can stand for other keys in turn or which can
+ also just execute some code). \tikzname\ uses this mechanism heavily.
+\item |pgfkeys| supports multi-argument key code. This can, however,
+ be emulated in |keyval|.
+\item |pgfkeys| supports handlers. These are call-backs that are
+ called when a key is not known. They are very flexible, in fact even
+ defining keys in different ways is handled by, well, handlers.
+\end{itemize}
+
+
+\subsubsection{Quick Guide to Using the Key Mechanism}
+
+The following quick guide to \pgfname's key mechanism only treats the
+most commonly used features. For an in-depth discussion of what is
+going on, please consult the remainder of this section.
+
+Keys are organized in a large tree that is reminiscent of the Unix
+file tree. A typical key might be, say, |/tikz/coordinate system/x|
+or just |/x|. Again as in Unix, when you specify keys you can provide
+the complete path of the key, but you usually just provide the name of
+the key (corresponding to the file name without any path) and the path
+is added automatically.
+
+Typically (but not necessarily) some code is associated with a key. To
+execute this code, you use the |\pgfkeys| command. This command takes
+a list of so-called key--value pairs. Each pair is of the form
+\meta{key}|=|\meta{value}. For each pair the |\pgfkeys| command will
+execute the code stored for the \meta{key} with its parameter set to
+\meta{value}.
+
+Here is a typical example of how the |\pgfkeys| command is used:
+\begin{codeexample}[code only]
+\pgfkeys{/my key=hallo,/your keys/main key=something\strange,
+ key name without path=something else}
+\end{codeexample}
+
+Now, to set the code that is stored in a key you do not need to learn
+a new command. Rather, the |\pgfkeys| command can also be used to set
+the code of a key. This is done using so-called \emph{handlers}. They
+look like keys whose names look like ``hidden files in Unix'' since
+they start with a dot. The handler for setting the code of a key is
+appropriately called |.code| and it is used as follows:
+\begin{codeexample}[]
+\pgfkeys{/my key/.code=The value is '#1'.}
+\pgfkeys{/my key=hi!}
+\end{codeexample}
+As you can see, in the first line we defined the code for the key
+|/my key|. In the second line we executed this code with the parameter
+set to |hi!|.
+
+There are numerous handlers for defining a key. For instance, we can
+also define a key whose value actually consists of more than one
+parameter.
+\begin{codeexample}[]
+\pgfkeys{/my key/.code 2 args=The values are '#1' and '#2'.}
+\pgfkeys{/my key={a1}{a2}}
+\end{codeexample}
+
+We often want to have keys where the code is called with some default
+value if the user does not provide a value. Not surprisingly, this is
+also done using a handler, this time called |.default|.
+\begin{codeexample}[]
+\pgfkeys{/my key/.code=(#1)}
+\pgfkeys{/my key/.default=hello}
+\pgfkeys{/my key=hallo,/my key}
+\end{codeexample}
+
+The other way round, it is also possible to specify that a value
+\emph{must} be specified, using a handler called
+|.value required|. Finally, you can also require that no value
+\emph{may} be specified using |.value forbidden|.
+
+All keys for a package like, say, \tikzname\ start with the path
+|/tikz|. We obviously do not like to write this path down every
+time we use a key (so we do not have to write things like
+|\draw[/tikz/line width=1cm]|). What we need is to somehow ``change
+the default path to a specific location.'' This is done using the
+handler |.cd| (for ``change directory''). Once this handler has been
+used on a key, all subsequent keys {\itshape in the current call of
+ |\pgfkeys| only} are automatically prefixed with this path, if
+necessary.
+
+Here is an example:
+\begin{codeexample}[code only]
+\pgfkeys{/tikz/.cd,line width=1cm,line cap=round}
+\end{codeexample}
+This makes it easy to define commands like |\tikzset|, which could be
+defined as follows (the actual definition is a bit faster, but the
+effect is the same):
+\begin{codeexample}[code only]
+\def\tikzset#1{\pgfkeys{/tikz/.cd,#1}}
+\end{codeexample}
+
+When a key is handled, instead of executing some code, the key can
+also cause further keys to be executed. Such keys will be called
+\emph{styles}. A style is, in essence, just a key list that should be
+executed whenever the style is executed. Here is an example:
+\begin{codeexample}[]
+\pgfkeys{/a/.code=(a:#1)}
+\pgfkeys{/b/.code=(b:#1)}
+\pgfkeys{/my style/.style={/a=foo,/b=bar,/a=#1}}
+\pgfkeys{/my style=wow}
+\end{codeexample}
+As the above example shows, style can also be parametrized, just like
+the normal code keys.
+
+As a typical use of styles, suppose we wish to setup the key |/tikz|
+so that it will change the default path to |/tikz|. This can be
+achieved as follows:
+\begin{codeexample}[code only]
+\pgfkeys{/tikz/.style=/tikz/.cd}
+\pgfkeys{tikz,line width=1cm,draw=red}
+\end{codeexample}
+
+Note that when |\pgfkeys| is executed, the default path is set
+to~|/|. This means that the first |tikz| will be completed to
+|/tikz|. Then |/tikz| is a style and, thus, replaced by |/tikz/.cd|,
+which changes the default path to |/tikz|. Thus, the |line width| is
+correctly prefixed with |/tikz|.
+
+\subsection{The Key Tree}
+
+The |pgfkeys| package organizes keys in a so-called \emph{key
+ tree}. This tree will be familiar to anyone who has used a Unix
+operating system: A key is addressed by a path, which consists of
+different parts separated by slashes. A typical key might be
+|/tikz/line width| or just |/tikz| or something more complicated like
+|/tikz/cs/x/.store in|.
+
+Let us fix some further terminology: Given a key like |/a/b/c|, we
+call the part leading up the last slash (|/a/b|) the \emph{path} of
+the key. We call everything after the last slash (|c|) the \emph{name}
+of the key (in a file system this would be the file name).
+
+We do not always wish to specify keys completely. Instead, we usually
+specify only part of a key (typically only the name) and the
+\emph{default path} is then added to the key at the front. So, when
+the default path is |/tikz| and you
+refer to the (partial) key |line width|, the actual key that is used
+is |/tikz/line width|. There is a simple rule for deciding whether a
+key is a partial key or a full key: If it starts with a slash, then it
+is a full key and it is not modified; if it does not start with
+a slash, then the default path is automatically prefixed.
+
+Note that the default path is not the same as a search path. In
+particular, the default path is just a single path. When a partial key
+is given, only this single default path is prefixed; |pgfkeys| does
+not try to lookup the key in different parts of a search path. It is,
+however, possible to emulate search paths, but a much more
+complicated mechanism must be used.
+
+When you set keys (to be explained in a moment), you can freely mix
+partial and full keys and you can change the default path. This makes
+it possible to temporarily use keys from another part of the key tree
+(this turns out to be a very useful feature).
+
+Each key (may) store some \emph{tokens} and there exist commands,
+described below, for setting, getting, and changing the tokens stored
+in a key. However, you will only very seldom use these commands
+directly. Rather, the standard way of using keys is the |\pgfkeys|
+command or some command that uses it internally like, say,
+|\tikzset|. So, you may wish to skip the following commands and
+continue with the next subsection.
+
+\begin{command}{\pgfkeyssetvalue\marg{full key}\marg{token text}}
+ Stores the \meta{token text} in the \meta{full key}. The \meta{full key}
+ may not be a partial key, so no default-path-adding is done. The
+ \meta{token text} can be arbitrary tokens and may even contain things
+ like |#| or unbalanced \TeX-ifs.
+\begin{codeexample}[]
+\pgfkeyssetvalue{/my family/my key}{Hello, world!}
+\pgfkeysvalueof{/my family/my key}
+\end{codeexample}
+
+ The setting of a key is always local to the current \TeX\ group.
+\end{command}
+
+\begin{command}{\pgfkeyslet\marg{full key}\marg{macro}}
+ Performs a |\let| statement so the the \meta{full key} pionts to the
+ contents of \meta{macro}.
+\begin{codeexample}[]
+\def\helloworld{Hello, world!}
+\pgfkeyslet{/my family/my key}{\helloworld}
+\pgfkeysvalueof{/my family/my key}
+\end{codeexample}
+ You should never let a key be equal to |\relax|. Such a key may or
+ may not be indistinguishable from an undefined key.
+\end{command}
+
+\begin{command}{\pgfkeysgetvalue\marg{full key}\marg{macro}}
+ Retrieves the tokens stored in the \meta{full key} and lets
+ \meta{macro} be equal to these tokens. If the key has
+ not been set, the \meta{macro} will be equal to |\relax|.
+\begin{codeexample}[]
+\pgfkeyssetvalue{/my family/my key}{Hello, world!}
+\pgfkeysgetvalue{/my family/my key}{\helloworld}
+\helloworld
+\end{codeexample}
+\end{command}
+
+\begin{command}{\pgfkeysvalueof\marg{full key}}
+ Inserts the value stored in \meta{full key} at the current position
+ into the text.
+
+\begin{codeexample}[]
+\pgfkeyssetvalue{/my family/my key}{Hello, world!}
+\pgfkeysvalueof{/my family/my key}
+\end{codeexample}
+\end{command}
+
+
+\begin{command}{\pgfkeysifdefined\marg{full key}\marg{if}\marg{else}}
+ Checks whether this key was previously set using either
+ |\pgfkeyssetvalue| or |\pgfkeyslet|. If so, the code in \meta{if} is
+ executed, otherwise the code in \meta{else}.
+
+ This command will use e\TeX's |\ifcsname| command, if available, for
+ efficiency. This means, however, that it may behave differently for
+ \TeX\ and for e\TeX\ when you set keys to |\relax|. For this reason
+ you should not do so.
+\begin{codeexample}[]
+\pgfkeyssetvalue{/my family/my key}{Hello, world!}
+\pgfkeysifdefined{/my family/my key}{yes}{no}
+\end{codeexample}
+\end{command}
+
+
+\subsection{Setting Keys}
+
+Settings keys is done using a powerful command called |\pgfkeys|. This
+command takes a list of so-called \emph{key--value pairs}. These are
+pairs of the form \meta{key}|=|\meta{value}. The principle idea is the
+following: For each pair in the list, some \emph{action} is
+taken. This action can be one of the following:
+
+\begin{enumerate}
+\item A command is executed whose argument(s) are \meta{value}. This
+ command is stored in a special subkey of \meta{key}.
+\item The \meta{value} is stored in the \meta{key} itself.
+\item If the key's name (the part after the last slahs) is a known
+ \emph{handler}, then this handler will take care of the key.
+\item If the key is totally unknown, one of several possible
+ \emph{unknown key handlers} is called.
+\end{enumerate}
+
+Addtionally, if the \meta{value} is missing, a default value may or
+may not be substituted. Before we plunge into all the details,
+let us have a quick look at the command itself.
+
+\begin{command}{\pgfkeys\marg{key list}}
+ The \meta{key list} should be a list of key--value pairs, separated
+ by commas. A key--value pair can have the following two forms:
+ \meta{key}|=|\meta{value} or just \meta{key}. Any spaces around the
+ \meta{key} or around the \meta{value} are removed. It is permissible
+ to surround both the \meta{key} or the \meta{value} in curly braces,
+ which are also removed. Especially putting the \meta{value} in curly
+ braces needs to be done quite often, namely whenever the \meta{value}
+ contains an equal-sign or a comma.
+
+ The key--value pairs in the list are handled in the order they
+ appear. How this handling is done, exactly, is described in the rest
+ of this section.
+
+ If a \meta{key} is a partial key, the current value of the default
+ path is prefixed to the \meta{key} and this ``upgraded'' key is
+ then used. The default path is just the root path |/| when the first
+ key is handled, but it may change later on. At the end of the
+ command, the default path is reset to the value it had before this
+ command was executed.
+
+ Calls of this command may be nested. Thus, it is permissible to call
+ |\pgfkeys| inside the code that is executed for a key. Since the
+ default path is restored after a call of |\pgfkeys|, the default
+ path will not change when you call |\pgfkeys| while executing code
+ for a key (which is exactly what you want).
+\end{command}
+
+\begin{command}{\pgfqkeys\marg{default path}\marg{key list}}
+ This command has the same effect as |\pgfkeys{|\meta{default
+ path}|/.cd,|\meta{key list}|}|, it is only marginally
+ quicker. This command should not be used in user code, but rather in
+ commands like |\tikzset| or |\pgfset| that get called very often.
+\end{command}
+
+\begin{command}{\pgfkeysalso\marg{key list}}
+ This command has execatly the same effect as |\pgfkeys|, only the
+ default path is not modified before or after the keys are being
+ set. This command is mainly intended to be called by the code that
+ is being processed for a key.
+\end{command}
+
+\begin{command}{\pgfqkeysalso\marg{default path}\marg{key list}}
+ This command has the same effect as |\pgfkeysalso{|\meta{default
+ path}|/.cd,|\meta{key list}|}|, it is only quicker. Changing the
+ default path inside a |\pgfkeyalso| is dangerous, so use with
+ care. A rather safe place to call this command is at the beginning
+ of a \TeX\ group.
+\end{command}
+
+
+\subsubsection{Default Arguments}
+
+The arguments of the |\pgfkeys| command can either be of the form
+\meta{key}|=|\meta{value} or of the form \meta{key} with the
+value-part missing. In the second case, the |\pgfkeys| will try to
+provide a \emph{default value} for the \meta{value}. If such a default
+value is defined, it will be used as if you had written
+\meta{key}|=|\meta{default value}.
+
+In the following, the details of how default values are determined is
+described; however, you should normally use the handlers |.default|
+and |.value required| as described in
+Section~\ref{section-default-handlers} and you can may wish to skip
+the following details.
+
+When |\pgfkeys| encounters a \meta{key} without an equal-sign, the
+following happens:
+\begin{enumerate}
+\item The input is replaced by \meta{key}|=\pgfkeysnovalue|. In
+ particular, the commands |\pgfkeys{my key}| and
+ |\pgfkeys{my key=\pgfkeysnovalue}| have exactly the same effect and
+ you can ``simulate'' a missing value by providing the value
+ |\pgfkeysnovalue|, which is sometimes useful.
+\item If the \meta{value} is |\pgfkeysnovalue|, then it is checked
+ whether the subkey \meta{key}|/.@def| exists. For instance, if you
+ write |\pgfkeys{/my key}|, then it is checked whether the key
+ |/my key/.@def| exists.
+\item If the key \meta{key}|/.@def| exists, then the tokens stored in
+ this key are used as \meta{value}.
+\item If the key does not exist, then |\pgfkeysnovalue| is used as the
+ \meta{value}.
+\item At the end, if the \meta{value} is now equal to
+ |\pgfkeysvaluerequired|, then the code (or something fairly equivalent)
+ |\pgfkeys{/errors/value required=|\meta{key}|{}}|
+ is executed. Thus, by changing this key you can change the error
+ message that is printed or you can handle the missing value in some
+ other way.
+\end{enumerate}
+
+
+
+\subsubsection{Keys That Execute Commands}
+\label{section-key-code}
+
+After the transformation process described in the previous subsection,
+we arrive at a key of the form \meta{key}=\meta{value}, where
+\meta{key} is a full key. Different things can now happen, but always
+the macro |\pgfkeyscurrentkey| will have been setup to expand to the
+text of the \meta{key} that is currently being processed.
+
+The first things that is tested is whether the key \meta{key}|/.@cmd|
+exists. If this is the case, then it is assumed that this key stores
+the code of a macro and this macro is executed. The argument of this
+macro is \meta{value} directly followed by |\pgfeov|, which stands for
+``end of value.'' The \meta{value} is not surrounded by braces. After
+this code has been executed, |\pgfkeys| continues with the next key in
+the \meta{key list}.
+
+It may seem quite peculiar that the macro stored in the key
+\meta{key}|/.@cmd| is not simply executed with the argument
+|{|\meta{value}|}|. However, the approach taken in the |pgfkeys|
+packages allows for more flexibility. For instance, assume that you
+have a key that expects a \meta{value} of the form
+``\meta{text}|+|\meta{more text}'' and wishes to store \meta{text} and
+\meta{more text} in two different macros. This can be achieved as
+follows:
+\begin{codeexample}[]
+\def\mystore#1+#2\pgfeov{\def\a{#1}\def\b{#2}}
+\pgfkeyslet{/my key/.@cmd}{\mystore}
+\pgfkeys{/my key=hello+world}
+
+|\a| is \a, |\b| is \b.
+\end{codeexample}
+
+Naturally, defining the code to be stored in a key in the above manner
+is too awkward. The following commands simplify things a bit, but the
+usual manner of setting up code for a key is to use one of the
+handlers described in Section~\ref{section-code-handlers}.
+
+\begin{command}{\pgfkeysdef\marg{key}\marg{code}}
+ This command temporarily defines a \TeX-macro with the argument list
+ |#1\pgfeov| and then lets \meta{key}|/.@cmd| be equal to this
+ macro. The net effect of all this is that you have then setup code
+ for the key \meta{key} so that when you write
+ |\pgfkeys{|\meta{key}|=|\meta{value}|}|, then the \meta{code} is
+ executed with all occurrences of |#1| in \meta{code} being replaced
+ by \meta{value}. (This behaviour is quite similar to the
+ |\define@key| command of |keyval| and |xkeyval|).
+
+\begin{codeexample}[]
+\pgfkeysdef{/my key}{#1, #1.}
+\pgfkeys{/my key=hello}
+\end{codeexample}
+\end{command}
+
+\begin{command}{\pgfkeysedef\marg{key}\marg{code}}
+ This command works like |\pgfkeysdef|, but it uses |\edef| rather
+ than |\def| when defining the key macro. If you do not know the
+ difference between the two, then you will not need this command;
+ and if you know the difference, then you will know when you need this
+ command.
+\end{command}
+
+\begin{command}{\pgfkeysdeargs\marg{key}\marg{argument pattern}\marg{code}}
+ This command works like |\pgfkeysdef|, but it allows you to provide
+ an arbitrary \meta{argument pattern} rather than just the simple
+ single argument of |\pgfkeysdef|.
+
+\begin{codeexample}[]
+\pgfkeysdefargs{/my key}{#1+#2}{\def\a{#1}\def\b{#2}}
+\pgfkeys{/my key=hello+world}
+
+|\a| is \a, |\b| is \b.
+\end{codeexample}
+\end{command}
+
+\begin{command}{\pgfkeysedefargs\marg{key}\marg{argument pattern}\marg{code}}
+ The |\edef| version of |\pgfkeysdefargs|.
+\end{command}
+
+
+\subsubsection{Keys That Store Values}
+
+Let us continue with what happens when |\pgfkeys| processes the
+current key and the subkey \meta{key}|/.@cmd| is not defined. Then
+it is checked whether the \meta{key} itself exists (has been
+previously assigned a value using, for instance,
+|\pgfkeyssetvalue|). In this case, the tokens stored in \meta{key} are
+replaced by \meta{value} and |\pgfkeys| proceeds with the next key in
+the \meta{key list}.
+
+
+\subsubsection{Keys That Are Handled}
+\label{section-key-handlers}
+
+If neither the \meta{key} itself nor the subkey \meta{key}|/.@cmd| are
+defined, then the \meta{key} cannot be processed ``all by itself.''
+Rather, a \meta{handler} is needed for this key. Most of the power of
+|pgfkeys| comes from the proper use of such handlers.
+
+Recall that the \meta{key} is always a full key (if it was not
+originally, it has already been upgraded at this point to a full
+key). It decomposed into two parts:
+
+\begin{enumerate}
+\item The \meta{path} of \meta{key} (everything
+ before the last slash) is stored in the macro |\pgfkeyscurrentpath|.
+\item The \meta{name} of \meta{key} (everything
+ after the last slash) is stored in the macro |\pgfkeyscurrentname|.
+
+ It is recommended (but not necessary) that the name of a handler
+ starts with a dot (but not with |.@|), so that they are easy to
+ detect for the reader.
+\end{enumerate}
+
+(For efficiency reasons, these two macros are only setup at this point;
+so when code is executed for a key in the ``usual'' manner then these
+macros are not setup.)
+
+The |\pgfkeys| command now checks whether the key
+|/handlers/|\meta{name}|/.@cmd| exists. If so, it should store a command
+and this command is executed exactly in the same manner as described
+in Section~\ref{section-key-code}.
+Thus, this code gets the \meta{value} that was originally intended for
+\meta{key} as its argument, followed by |\pgfeov|.
+It is the job of the handlers to so something useful with the
+\meta{value}.
+
+For an example, let us write a handler that will output the value
+stored in a key to the log file. We call this handler
+|.print to log|. The idea is that when someone tries to use the key
+|/my key/.print to log|, then this key will not be defined and the
+handler gets executed. The handler will then have access to the
+path-part of the key, which is |/my key|, via the macro
+|\pgfkeyscurrentpath|. It can then lookup which value is stored in
+this key and print it.
+
+\begin{codeexample}[code only]
+\pgfkeysdef{/handlers/.print to log}
+{%
+ \pgfkeysgetvalue{\pgfkeyscurrentpath}{\temp}
+ \writetolog{\temp}
+}
+\pgfkeyssetvalue{/my key}{Hi!}
+...
+\pgfkeys{/my key/.print to log}
+\end{codeexample}
+The above code will print |Hi!| in the log, provided the macro
+|\writetolog| is setup appropriately.
+
+For a more interesting handler, let us program a handler that will
+setup a key so that when the key is used some code is executed. This
+code is given as \meta{value}. All the handler must do is to call
+|\pgfkeysdef| for the path of the key (which misses the handler's
+name) and assign the parameter value to it.
+\begin{codeexample}[]
+\pgfkeysdef{/handlers/.my code}{\pgfkeysdef{\pgfkeyscurrentpath}{#1}}
+\pgfkeys{/my key/.my code=(#1)}
+\pgfkeys{/my key=hallo}
+\end{codeexample}
+
+
+\subsubsection{Keys That Are Unknown}
+
+For some keys, neither the key is defined nor its |.@cmd| subkey nor
+is a handler defined for this key. In this case, it is checked whether
+the key \meta{current path}|/.unknown/.@cmd| exists. Thus, when you try to
+use the key |/tikz/strange|, then it is checked whether
+|/tikz/.unknown/.@cmd| exists. If this key exists (which it does), it is
+executed. This code can then try to make sense of the key. For
+instance, the handler for \tikzname\ will try to interpret the key's
+name as a color or as an arrow specification or as a \pgfname\
+option.
+
+You can setup unknown key handlers for your own keys by simply setting
+the code of the key \meta{my path prefix}|/.unknown|. This also allows
+you to setup ``search paths.'' The idea is that you would like keys to
+be searched not only in a single default path, but in
+several. Suppose, for instance, that you would like keys to be
+searched
+for in |/a|, |/b|, and |/b/c|. We setup a key |/my search path| for
+this:
+\begin{codeexample}[code only]
+\pgfkeys{/my search path/.unknown/.code=
+ {%
+ \let\searchname=\pgfkeyscurrentname%
+ \pgfkeysalso{%
+ /a/\searchname/.try=#1,
+ /b/\searchname/.retry=#1,
+ /b/c/\searchname/.retry=#1%
+ }%
+ }%
+}
+\pgfkeys{/my search path/.cd,foo,bar}
+\end{codeexample}
+In the above code, |foo| and |bar| will be searched for in the three
+directories |/a|, |/b|, and |/b/c|.
+
+If the key \meta{current path}|/.unknown/.@cmd| does not exist, the
+handler |/handlers/.unknown| is invoked instead, which is always
+defined and which prints an error message by default.
+
+\subsection{Key Handlers}
+
+We now describe which key handlers are defined by default. You can
+also define new ones as described in Section~\ref{section-key-handlers}.
+
+
+\subsubsection{Handlers for Path Management}
+
+\begin{handler}{{.cd}}
+ This handler causes the default path to be set to \meta{key}. Note that
+ the default path is reset at the beginning of each call to
+ |\pgfkeys| to be equal to~|/|.
+
+ \example |\pgfkeys{/tikz/.cd,...}|
+\end{handler}
+
+\begin{handler}{{.is family}}
+ This handler sets up things such that when \meta{key} is executed, then
+ the current path is set to \meta{key}. A typical use is the following:
+\begin{codeexample}[code only]
+\pgfkeys{/tikz/.is family}
+\pgfkeys{tikz,line width=1cm}
+\end{codeexample}
+ The effect of this handler is the same as if you had written
+ \meta{key}|/.style=|\meta{key}|/.cd|, only the code produced by the
+ |.is family| handler is quicker.
+\end{handler}
+
+
+\subsubsection{Setting Defaults}
+\label{section-default-handlers}
+
+\begin{handler}{{.default}|=|\meta{value}}
+ Sets the default value of \meta{key} to \meta{value}. This means
+ that whenever no value is provided in a call to |\pgfkeys|, then
+ this \meta{value} will be used instead.
+
+ \example |\pgfkeys{/width/.default=1cm}|
+\end{handler}
+
+\begin{handler}{{.value required}}
+ This handler causes the error message key |/erros/value required| to
+ be issued whenever the \meta{key} is used without a value.
+
+ \example |\pgfkeys{/width/.value required}|
+\end{handler}
+
+\begin{handler}{{.value forbidden}}
+ This handler causes the error message key |/erros/value forbidden|
+ to be issued whenever the \meta{key} is used with a value.
+
+ This handler works be adding code to the code of the key. This means
+ that you have to define the key first before you can use this
+ handler.
+\begin{codeexample}[code only]
+\pgfkeys{/my key/.code=I do not want an argument!}
+\pgfkeys{/my key/.value forbidden}
+
+\pgfkeys{/my key} % Ok
+\pgfkeys{/my key=foo} % Error
+\end{codeexample}
+\end{handler}
+
+
+\subsubsection{Defining Key Codes}
+\label{section-code-handlers}
+
+A number of handlers exist for defining the code of keys.
+
+\begin{handler}{{.code}|=|\meta{code}}
+ This handler executes |\pgfkeysdef| with the parameters \meta{key}
+ and \meta{code}. This means that, afterwards, whenever the
+ \meta{key} is used, the \meta{code} gets executed. More precisely,
+ when \meta{key}|=|\meta{value} is encountered in a key list,
+ \meta{code} is executed with any occurrence of |#1| replaced by
+ \meta{value}. As always, if no \meta{value} is given, the default
+ value is used, if defined, or the special value |\pgfkeysnovalue|.
+
+ It is permissible that \meta{code} calls the command |\pgfkeys|. It
+ is also permissible the \meta{code} calls the command
+ |\pgfkeysalso|, which is useful for styles, see below.
+
+\begin{codeexample}[code only]
+\pgfkeys{/par indent/.code={\parindent=#1},/par indent/.default=2em}
+\pgfkeys{/par indent=1cm}
+...
+\pgfkeys{/par indent}
+\end{codeexample}
+\end{handler}
+
+\begin{handler}{{.ecode}|=|\meta{code}}
+ This handler works like |.code|, only the command |\pgfkeysedef| is
+ used.
+\end{handler}
+
+
+\begin{handler}{{.code 2 args}|=|\meta{code}}
+ This handler works like |.code|, only two arguments rather than one
+ are expected when the \meta{code} is executed. This means that when
+ \meta{key}|=|\meta{value} is encountered in a key list, the
+ \meta{value} should consist of two arguments. For instance,
+ \meta{value} could be |{first}{second}|. Then \meta{code} is
+ executed with any occurrence of |#1| replaced |first| and any
+ occurrence of |#2| replaced by |second|.
+
+ Because of the special way the \meta{value} is parsed, if you set
+ \meta{value} to, for instance, |first| (without any braces), then
+ |#1| will be set to |f| and |#2| will be set to |irst|.
+
+\begin{codeexample}[code only]
+\pgfkeys{/page size/.code 2 args={\paperheight=#2\paperwidth=#1}}
+\pgfkeys{/page size={30cm}{20cm}}
+\end{codeexample}
+\end{handler}
+
+\begin{handler}{{.ecode 2 args}|=|\meta{code}}
+ This handler works like |.code 2 args|, only an |\edef| is used
+ rather than a |\def| to define the macro.
+\end{handler}
+
+
+
+\begin{handler}{{.code args}|=|\marg{argument pattern}\marg{code}}
+ This handler also works like |.code|, but you can now specify an
+ arbitrary \meta{argument pattern}. Such a pattern is a usual \TeX\
+ macro pattern. For instance, suppose \meta{argument pattern} is
+ |(#1/#2)| and \meta{key}|=|\meta{value} is encountered in a
+ key list with \meta{value} being |(first/second)|. Then \meta{code}
+ is executed with any occurrence of |#1| replaced |first| and any
+ occurrence of |#2| replaced by |second|. So, the actual \meta{value}
+ is matched against the \meta{argument pattern} in the standard \TeX\
+ way.
+
+\begin{codeexample}[code only]
+\pgfkeys{/page size/.code args={#1 and #2}{\paperheight=#2\paperwidth=#1}}
+\pgfkeys{/page size=30cm and 20cm}
+\end{codeexample}
+\end{handler}
+
+\begin{handler}{{.ecode args}|=|\marg{argument pattern}\marg{code}}
+ This handler works like |.code args|, only an |\edef| is used
+ rather than a |\def| to define the macro.
+\end{handler}
+
+
+There are also handlers for modifying existing keys.
+
+\begin{handler}{{.add code}|=|\marg{prefix code}\marg{append code}}
+ This handler adds code to an existing key. The \meta{prefix code} is
+ added to the code stored in \meta{key}|/.@cmd| at the beginning, the
+ \meta{append code} is added to this code at the end. Either can be
+ empty. The argument list of \meta{code} cannot be changed using this
+ handler. Note that both \meta{prefix code} and \meta{append code}
+ may contain parameters like |#2|.
+
+\begin{codeexample}[code only]
+\pgfkeys{/par indent/.code={\parindent=#1}}
+\newdimen\myparindent
+\pgfkeys{/par indent/.add code={}{\myparindent=#1}}
+...
+\pgfkeys{/par indent=1cm} % This will set both \parindent and
+ % \myparindent to 1cm
+\end{codeexample}
+\end{handler}
+
+\begin{handler}{{.prefix code}|=|\meta{prefix code}}
+ This handler is a shortcut for \meta{key}|/.add code={|\meta{prefix
+ code}|}{}|. That is, this handler adds the \meta{prefix code} at
+ the beginning of the code stored in \meta{key}|/.@cmd|.
+\end{handler}
+
+\begin{handler}{{.append code}|=|\meta{append code}}
+ This handler is a shortcut for \meta{key}|/.add code={}{|\meta{append
+ code}|}{}|.
+\end{handler}
+
+
+\subsubsection{Defining Styles}
+
+The following handlers allow you to define \emph{styles}. A style is a
+key list that is processed whenever the style is given as a key in a
+key list. Thus, a style ``stands for'' a certain key value
+list. Styles can be parametrized just like normal code.
+
+\begin{handler}{{.style}|=|\meta{key list}}
+ This handler set things up so that whenever \meta{key}|=|\meta{value} is
+ encountered in a key list, then the \meta{key list}, with every
+ occurrence of |#1| replaced by \meta{value}, is processed
+ instead. As always, if no \meta{value} is given, the default
+ value is used, if defined, or the special value |\pgfkeysnovalue|.
+
+ You can achieve the same effect by writing
+ \meta{key}|/.code=\pgfkeysalso{|\meta{key list}|}|. This means, in
+ particular, that the code of a key could also first execute some
+ normal code and only then process some further keys.
+
+\begin{codeexample}[code only]
+\pgfkeys{/par indent/.code={\parindent=#1}}
+\pgfkeys{/no indent/.style={/par indent=0pt}}
+\pgfkeys{/normal indent/.style={/par indent=2em}}
+\pgfkeys{/no indent}
+...
+\pgfkeys{/normal indent}
+\end{codeexample}
+ The following example shows a parametrized style ``in action''.
+\begin{codeexample}[]
+\begin{tikzpicture}[outline/.style={draw=#1,fill=#1!20}]
+ \node [outline=red] {red box};
+ \node [outline=blue] at (0,-1) {blue box};
+\end{tikzpicture}
+\end{codeexample}
+\end{handler}
+
+\begin{handler}{{.estyle}|=|\meta{key list}}
+ This handler works like |.style|, only the \meta{code} is set using
+ |\edef| rather than |\def|. Thus, all macros in the \meta{code} are
+ expanded prior to saving the style.
+\end{handler}
+
+For styles the corresponding handlers as for normal code exist:
+
+\begin{handler}{{.style 2 args}|=|\meta{key list}}
+ This handler works like |.code 2 args|, only for styles. Thus, the
+ \meta{key list} may contain occurrences of both |#1| and |#2| and
+ when the style is used, two parameters must be given as
+ \meta{value}.
+\begin{codeexample}[code only]
+\pgfkeys{/paper height/.code={\paperheight=#1},/paper width/.code={\paperwidth=#1}}
+\pgfkeys{/page size/.style 2 args={/paper height=#1,/paper width=#2}}
+\pgfkeys{/page size={30cm}{20cm}}
+\end{codeexample}
+\end{handler}
+
+\begin{handler}{{.estyle 2 args}|=|\meta{key list}}
+ This handler works like |.style 2 args|, only an |\edef| is used
+ rather than a |\def| to define the macro.
+\end{handler}
+
+\begin{handler}{{.style args}|=|\marg{argument pattern}\marg{key list}}
+ This handler works like |.code args|, only for styles.
+\end{handler}
+
+\begin{handler}{{.estyle args}|=|\marg{argument pattern}\marg{code}}
+ This handler works like |.ecode args|, only for styles.
+\end{handler}
+
+\begin{handler}{{.add style}|=|\marg{prefix key list}\marg{append key list}}
+ This handler works like |.add code|, only for styles. However, it is
+ permissible to add styles to keys that have previously been set
+ using |.code|. (It is also permissible to add normal \meta{code} to
+ a key that has previously been set using |.style|). When you add a
+ style to a key that was previously set using |.code|, the following
+ happens: When \meta{key} is processed, the \meta{prefix key list}
+ will be processed first, then the \meta{code} that was previously
+ stored in \meta{key}|/.@cmd|, and then the keys in \meta{append key
+ list} are processed.
+\begin{codeexample}[code only]
+\pgfkeys{/par indent/.code={\parindent=#1}}
+\pgfkeys{/par indent/.add style={}{/my key=#1}}
+...
+\pgfkeys{/par indent=1cm} % This will set \parindent and
+ % then execute /my key=#1
+\end{codeexample}
+\end{handler}
+
+\begin{handler}{{.prefix style}|=|\meta{prefix key list}}
+ Works like |.add style|, but only for the prefix key list.
+\end{handler}
+
+\begin{handler}{{.append style}|=|\meta{append key list}}
+ Works like |.add style|, but only for the append key list.
+\end{handler}
+
+
+\subsubsection{Defining Value-, Macro-, If- and Choice-Keys}
+
+For some keys, the code that should be executed for them is rather
+``specialized.'' For instance, it happens often that the code for a
+key just sets a certain \TeX-if to true or false. For these case
+predefine handlers make it easier to install the necessary code.
+
+However, we start with some handlers that are used to manage the value
+that is directly stored in a key.
+
+\begin{handler}{{.initial}|=|\meta{value}}
+ This handler sets the value of \meta{key} to \meta{value}. Note that
+ no subkeys are involved. After this handler has been used, by the
+ rules governing keys, you can subsequently change the value of the
+ \meta{key} by just writing \meta{key}|=|\meta{value}. Thus, this
+ handler is used to set the initial value of key.
+
+\begin{codeexample}[code only]
+\pgfkeys{/my key/.initial=red}
+% "/my key" now stores the value "red"
+\pgfkeys{/my key=blue}
+% "/my key" now stores the value "blue"
+\end{codeexample}
+
+ Note that in the after the example, writing |\pgfkeys{/my key}| will not
+ have the effect you might expect (namely that |blue| is inserted
+ into the main text). Rather, |/my key| will be promoted to
+ |/my key=\pgfkeysnovalue| and, thus, |\pgfkeysnovalue| will be
+ stored in |/my key|.
+
+ To retrieve the value stored in a key, the handler |.get| is used.
+\end{handler}
+
+\begin{handler}{{.get}|=|\meta{macro}}
+ Executes a |\let| command so that \meta{macro} contains the contents
+ stored in \meta{key}.
+
+\begin{codeexample}[]
+\pgfkeys{/my key/.initial=red}
+\pgfkeys{/my key=blue}
+\pgfkeys{/my key/.get=\mymacro}
+\mymacro
+\end{codeexample}
+\end{handler}
+
+\begin{handler}{{.add}|=|\marg{prefix value}\marg{append value}}
+ Adds the \meta{prefix value} and the beginning and the \meta{append
+ value} at the end of the value stored in \meta{key}.
+\end{handler}
+
+The next handler is useful for the common situation where
+\meta{key}|=|\meta{value} should cause the \meta{value} to be stored
+in some macro. Note that, typically, you could just as well store the
+value in the key itself.
+
+\begin{handler}{{.store in}|=|\meta{macro}}
+ This handler has the following effect: When you write
+ \meta{key}|=|\meta{value}, the code
+ |\def|\meta{macro}|{|\meta{value}|}| is executed. Thus, the given
+ value is ``stored'' in the \meta{macro}.
+\begin{codeexample}[]
+\pgfkeys{/text/.store in=\mytext}
+\def\a{world}
+\pgfkeys{/text=Hello \a!}
+\def\a{Gruffalo}
+\mytext
+\end{codeexample}
+\end{handler}
+
+\begin{handler}{{.estore in}|=|\meta{macro}}
+ This handler is similar to |.store in|, only the code
+ |\edef|\meta{macro}|{|\meta{value}|}| is used. Thus, the
+ macro-expanded version of \meta{value} is stored in the
+ \meta{macro}.
+\begin{codeexample}[]
+\pgfkeys{/text/.estore in=\mytext}
+\def\a{world}
+\pgfkeys{/text=Hello \a!}
+\def\a{Gruffalo}
+\mytext
+\end{codeexample}
+\end{handler}
+
+In another common situation a key is used to set a \TeX-if to true or
+false.
+
+\begin{handler}{{.is if}|=|\meta{\TeX-if name}}
+ This handler has the following effect: When you write
+ \meta{key}|=|\meta{value}, it is first checked that \meta{value} is
+ |true| or |false| (the default is |true| if no \meta{value} is
+ given). If this is not the case, the error key
+ |/errors/boolean expected| is executed. Otherwise,
+ the code |\|\meta{\TeX-if name}\meta{value} is executed, which sets
+ the \TeX-if accordingly.
+\begin{codeexample}[]
+\newif\iftheworldisflat
+\pgfkeys{/flat world/.is if=theworldisflat}
+\pgfkeys{/flat world=false}
+\iftheworldisflat
+ Flat
+\else
+ Round?
+\fi
+\end{codeexample}
+\end{handler}
+
+The next handler deals with the problem when a
+\meta{key}|=|\meta{value} makes sense only for a small set of possible
+\meta{value}s. For instance, the line cap can only be |rounded| or
+|rect| or |butt|, but nothing else. For this situation the following
+handler is useful.
+
+\begin{handler}{{.is choice}}
+ This handler set things up so that writing \meta{key}|=|\meta{value}
+ will cause the subkey \meta{key}|/|\meta{value} to be executed. So,
+ each of the different possible choices should be given by a subkey
+ of \meta{key}.
+\begin{codeexample}[code only]
+\pgfkeys{/line cap/.is choice}
+\pgfkeys{/line cap/round/.style={\pgfsetbuttcap}}
+\pgfkeys{/line cap/butt/.style={\pgfsetroundcap}}
+\pgfkeys{/line cap/rect/.style={\pgfsetrectcap}}
+\pgfkeys{/line cap/rectangle/.style={/line cap=rect}}
+...
+\draw [/line cap=butt] ...
+\end{codeexample}
+ If the subkey \meta{key}|/|\meta{value} does not exist, the error
+ key |/errors/unknown choice value| is executed.
+\end{handler}
+
+
+\subsubsection{Expanding Values}
+
+When you write \meta{key}|=|\meta{value}, you usually wish to use the
+\meta{value} ``as is.'' Indeed, great care is taken to ensure that you
+can even use things like |#1| or unbalanced \TeX-ifs inside
+\meta{value}. However, sometimes you want the \meta{value} to be
+expanded before it is used. For instance, \meta{value} might be a
+macro name like |\mymacro| and you do not want |\mymacro| to be used
+as the macro, but rather the \emph{contents} of |\mymacro|. Thus,
+instead of using \meta{value} you wish to use whatever \meta{value}
+expands to. Instead of using some fancy |\expandafter| hackery, you
+can use the following handlers:
+
+\begin{handler}{{.expand once}|=|\meta{value}}
+ This handler expands \meta{value} once (more precisely, it executes
+ an |\expandafter| command on the first token of \meta{value}) and
+ then process the resulting \meta{result} as if you had written
+ \meta{key}|=|\meta{result}. Note that if \meta{key} contains a
+ handler itself, this handler will be called normally.
+\begin{codeexample}[]
+\def\a{bottom}
+\def\b{\a}
+\def\c{\b}
+
+\pgfkeys{/key1/.initial=\c}
+\pgfkeys{/key2/.initial/.expand once=\c}
+\pgfkeys{/key3/.initial/.expand twice=\c}
+\pgfkeys{/key4/.initial/.expanded=\c}
+
+\def\a{{\ttfamily\string\a}}
+\def\b{{\ttfamily\string\b}}
+\def\c{{\ttfamily\string\c}}
+
+\begin{tabular}{ll}
+Key 1:& \pgfkeys{/key1} \\
+Key 2:& \pgfkeys{/key2} \\
+Key 3:& \pgfkeys{/key3} \\
+Key 4:& \pgfkeys{/key4}
+\end{tabular}
+\end{codeexample}
+\end{handler}
+
+\begin{handler}{{.expand twice}|=|\meta{value}}
+ This handler works like saying \meta{key}|/.expand once/.expand once=|\meta{value}.
+\end{handler}
+
+\begin{handler}{{.expanded}|=|\meta{value}}
+ This handler will completely expand \meta{value} (using |\edef|)
+ before processing \meta{key}|=|\meta{result}.
+\end{handler}
+
+
+\subsubsection{Handlers for Testing Keys}
+
+\begin{handler}{{.try}|=|\meta{value}}
+ This handler causes the same things to be done as if
+ \meta{key}|=|\meta{value} had been written instead. However, if
+ neither \meta{key}|/.@cmd| nor the key itself is defined, no
+ handlers will be called. Instead,
+ the execution of the key just stops. Thus, this handler will ``try''
+ to use the key, but no further action is taken when the key is not
+ defined.
+
+ The \TeX-if |\||ifpgfkeyssuccess| will be set according to whether
+ the \meta{key} was successfully executed or not.
+\begin{codeexample}[]
+\pgfkeys{/a/.code=(a:#1)}
+\pgfkeys{/b/.code=(b:#1)}
+\pgfkeys{/x/.try=hmm,/a/.try=hallo,/b/.try=welt}
+\end{codeexample}
+\end{handler}
+
+\begin{handler}{{.retry}|=|\meta{value}}
+ This handler works just like |.try|, only it will not do anything if
+ |\||ifpgfkeyssuccess| is false. Thus, this handler will only retry
+ to set a key if ``the last attempt failed''.
+\begin{codeexample}[]
+\pgfkeys{/a/.code=(a:#1)}
+\pgfkeys{/b/.code=(b:#1)}
+\pgfkeys{/x/.try=hmm,/a/.retry=hallo,/b/.retry=welt}
+\end{codeexample}
+\end{handler}
+
+
+\subsubsection{Handlers for Key Inspection}
+
+\begin{handler}{{.show value}}
+ This handler executes a |\show| command on the value stored in
+ \meta{key}. This is useful mostly for debugging.
+
+ \example |\pgfkeys{/my/obscure key/.show value}|
+\end{handler}
+
+\begin{handler}{{.show code}}
+ This handler executes a |\show| command on the code stored in
+ \meta{key}|/.@cmd|. This is useful mostly for debugging.
+
+ \example |\pgfkeys{/my/obscure key/.show code}|
+\end{handler}
+
+The following key is not a handler, but it also commonly used for
+inspecting things:
+\begin{key}{/utils/exec=\meta{code}}
+ This key will simply execute the given \meta{code}.
+
+ \example |\pgfkeys{some key=some value,/utils/exec=\show\hallo,obscure key=obscure}|
+\end{key}
+
+
+\subsection{Error Keys}
+
+In certain situations errors can occur, like using an undefined
+key. In these situations error keys are executed. They should store a
+macro that gets two arguments: The first is the offending key
+(possibly only after macro expansion), the second is the value that
+was passed as a parameter (also possibly only after macro expansion).
+
+Currently, error keys are simply executed. In the future it might be a
+good idea to have different subkeys that are executed depending on the
+language currently set so that users get a localized error message.
+
+\begin{key}{/errors/value required=\marg{offending key}\marg{value}}
+ This key is executed whenever an \meta{offending key} is used
+ without a value when a value is actually required.
+\end{key}
+
+\begin{key}{/errors/value forbidden=\marg{offending key}\marg{value}}
+ This key is executed whenever a key is used with a value when a
+ value is actually forbidden.
+\end{key}
+
+\begin{key}{/errors/boolean expected=\marg{offending key}\marg{value}}
+ This key is executed whenever a key setup using |.is if| gets called
+ with a \meta{value} other than |true| or |false|.
+\end{key}
+
+\begin{key}{/errors/unknown choice value=\marg{offending key}\marg{value}}
+ This key is executed whenever a choice is used as a \meta{value} for
+ a key setup using the |.is choice| handler that is not defined.
+\end{key}
+
+\begin{key}{/errors/unknown key=\marg{offending key}\marg{value}}
+ This key is executed whenever a key is unknown and no specific
+ |.unknown| handler is found.
+\end{key}