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.tex525
1 files changed, 434 insertions, 91 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
index 121e8b6b768..4ce292d380d 100644
--- 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
@@ -18,7 +18,7 @@ automatically by both \pgfname\ and \tikzname.
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.
+ abbreviation is |pgfkey| if |pgfmod| is not loaded. % pgfkey --> pgfkeys?
\end{package}
@@ -40,10 +40,6 @@ following:
\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.
@@ -89,7 +85,7 @@ 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:
+appropriately called |/.code| and it is used as follows:
\begin{codeexample}[]
\pgfkeys{/my key/.code=The value is '#1'.}
\pgfkeys{/my key=hi!}
@@ -100,7 +96,7 @@ 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.
+parameter.
\begin{codeexample}[]
\pgfkeys{/my key/.code 2 args=The values are '#1' and '#2'.}
\pgfkeys{/my key={a1}{a2}}
@@ -108,7 +104,7 @@ parameter.
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|.
+also done using a handler, this time called |/.default|.
\begin{codeexample}[]
\pgfkeys{/my key/.code=(#1)}
\pgfkeys{/my key/.default=hello}
@@ -117,15 +113,15 @@ also done using a handler, this time called |.default|.
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|.
+|/.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
+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.
@@ -180,12 +176,12 @@ different parts separated by slashes. A typical key might be
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).
+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
+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
@@ -219,7 +215,7 @@ continue with the next subsection.
like |#| or unbalanced \TeX-ifs.
\begin{codeexample}[]
\pgfkeyssetvalue{/my family/my key}{Hello, world!}
-\pgfkeysvalueof{/my family/my key}
+\pgfkeysvalueof{/my family/my key}
\end{codeexample}
The setting of a key is always local to the current \TeX\ group.
@@ -231,7 +227,7 @@ continue with the next subsection.
\begin{codeexample}[]
\def\helloworld{Hello, world!}
\pgfkeyslet{/my family/my key}{\helloworld}
-\pgfkeysvalueof{/my family/my key}
+\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.
@@ -240,7 +236,7 @@ continue with the next subsection.
\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|.
+ 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}
@@ -267,7 +263,7 @@ continue with the next subsection.
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.
+ you should not do so.
\begin{codeexample}[]
\pgfkeyssetvalue{/my family/my key}{Hello, world!}
\pgfkeysifdefined{/my family/my key}{yes}{no}
@@ -290,7 +286,7 @@ taken. This action can be one of the following:
\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.
+ \emph{unknown key handlers} is called.
\end{enumerate}
Addtionally, if the \meta{value} is missing, a default value may or
@@ -316,8 +312,8 @@ let us have a quick look at the command itself.
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.
-
+ 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
@@ -329,7 +325,7 @@ let us have a quick look at the command itself.
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.
+ commands like |\tikzset| or |\pgfset| that get called very often.
\end{command}
\begin{command}{\pgfkeysalso\marg{key list}}
@@ -358,8 +354,8 @@ 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
+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.
@@ -370,7 +366,7 @@ following happens:
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.
+ |\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
@@ -451,10 +447,27 @@ handlers described in Section~\ref{section-code-handlers}.
command.
\end{command}
-\begin{command}{\pgfkeysdeargs\marg{key}\marg{argument pattern}\marg{code}}
+\begin{command}{\pgfkeysdefnargs\marg{key}\marg{argument count}\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|.
+ an arbitrary \meta{argument count} between $0$ and $9$ (inclusive).
+
+\begin{codeexample}[]
+\pgfkeysdefnargs{/my key}{2}{\def\a{#1}\def\b{#2}}
+\pgfkeys{/my key=
+ {hello}
+ {world}}
+
+|\a| is `\a', |\b| is `\b'.
+\end{codeexample}
+ The resulting key will expect exactly \marg{argument count} arguments.
+\end{command}
+\begin{command}{\pgfkeysedefnargs\marg{key}\marg{argument count}\marg{code}}
+ The |\edef| version of |\pgfkeysdefnargs|.
+\end{command}
+
+\begin{command}{\pgfkeysdefargs\marg{key}\marg{argument pattern}\marg{code}}
+ This command works like |\pgfkeysdefnargs|, but it allows you to provide
+ an arbitrary \meta{argument pattern} rather than just a number of arguments.
\begin{codeexample}[]
\pgfkeysdefargs{/my key}{#1+#2}{\def\a{#1}\def\b{#2}}
@@ -462,6 +475,7 @@ handlers described in Section~\ref{section-code-handlers}.
|\a| is \a, |\b| is \b.
\end{codeexample}
+ Note that |\pgfkeysdefnargs| is \emph{better} when it comes to simple argument \emph{counts}\footnote{When the resulting keys are used, the \texttt{defnargs} variant allows spaces between arguments whereas the \texttt{defargs} variant does not; it considers the spaces as part of the argument.}.
\end{command}
\begin{command}{\pgfkeysedefargs\marg{key}\marg{argument pattern}\marg{code}}
@@ -477,7 +491,7 @@ 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}.
+the \meta{key list}.
\subsubsection{Keys That Are Handled}
@@ -500,7 +514,7 @@ key). It decomposed into two parts:
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.
+ detect for the reader.
\end{enumerate}
(For efficiency reasons, these two macros are only setup at this point;
@@ -518,7 +532,7 @@ It is the job of the handlers to so something useful with the
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
+|/.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
@@ -549,8 +563,100 @@ name) and assign the parameter value to it.
\pgfkeys{/my key=hallo}
\end{codeexample}
+There are some parameters for handled keys which prove to be useful in some (possibly rare) special cases:
+\begin{key}{/handler config=\mchoice{all,only existing,full or existing} (initially all)}
+ Changes the initial configuration how key handlers will be used.
+
+ This configuration is for advanced users and rarely necessary.
+
+ \begin{description}
+ \item[\texttt{all}]
+ The preconfigured setting |all| works as described above and
+ imposes no restriction on the key setting process.
+
+ \item[\texttt{only existing}]
+ The value |only existing| modifies the algorithm for handled keys
+ as follows: a handler \meta{key name}|/.|\meta{handler} will be
+ executed only if \meta{key name} is either a key which stores its
+ value directly or a command key for which |/.@cmd| exists. If
+ \meta{key name} does \emph{not} exist already, the complete string
+ \meta{key name}|/.|\meta{handler} is considered to be an unknown
+ key and the procedure described in the next section applies (for
+ the path of \meta{key name}).
+\begin{codeexample}[]
+% Define a test key and error handlers:
+\pgfkeys{/the/key/.code={Initial definition. }}
+\pgfkeys{/handlers/.unknown/.code={Unknown key `\pgfkeyscurrentkey'. }}
+
+% calling the test key yields 'Initial definition. ':
+\pgfkeys{/the/key}
+
+% Change configuration:
+\pgfkeys{/handler config=only existing}
+
+% allowed: key *re*-definition:
+\pgfkeys{/the/key/.code={Re-Definition. }}
+% calling the key yields 'Re-Definition. ':
+\pgfkeys{/the/key}
+
+% not allowed: definition of new keys:
+% this checks for '/the/other key/.unknown'
+% and '/handlers/.unknown'
+% and yields finally
+% 'Unknown key `/the/other key/.code`'
+\pgfkeys{/the/other key/.code={New definition. }}
+\end{codeexample}
+ It is necessary to exclude some key handlers from this
+ procedure. Altogether, the detailed procedure is as follows:
+ \begin{enumerate}
+ \item If a handled key like |/a path/a key/.a handler=value| is
+ encountered, it is checked whether the handler should be
+ invoked. This is the case if
+ \begin{itemize}
+ \item An exception from |only existing| for this key exists (see below),
+ \item The key |/a path/a key| exists already -- either directly as
+ storage key or with the |.@cmd| suffix.
+ \end{itemize}
+ \item If the check passes, everything works as before.
+ \item If the check fails, the complete key will be considered to be
+ unknown. In that case, the handling of unknown keys as described
+ in the next section applies. There, the current key path will be
+ set to |/a path| and the current key's name to |key/.a handler|.
+ \end{enumerate}
+
+ A consequence of this configuration is to provide more meaningful
+ processing of handled keys if a search path for keys is in effect,
+ see section~\ref{sec:pgf:unknown:keys} for an example.
+
+ \item[\texttt{full or existing}] Finally, the choice
+ |full or existing| is a variant of |only existing|: it works in
+ the same way
+ for keys which do not have a full key path. For example, the style
+
+ |\pgfkeys{/my path/.cd,key/.style={|$\dotsc$|}}|
+
+ can only be redefined: it doesn't have a full path, so the
+ |only existing| mechanism applies. But the style
+
+ |\pgfkeys{/my path/key/.style={|$\dotsc$|}}|
+
+ will still work. This allows users to override the |only existing|
+ feature if they know what they're doing (and provide full key
+ paths).
+ \end{description}
+\end{key}
+
+\begin{key}{/handler config/only existing/add exception=\marg{key
+ handler name}}
+ Allows to add exceptions to the |/handler config=only existing|
+ feature. Initially exceptions for the key handlers
+ |/.cd|, |/.try|, |/.retry|, |/.lastretry| and |/.unknown| are
+ defined. The value \marg{key handler name} should be the name of a
+ key handler.
+\end{key}
\subsubsection{Keys That Are Unknown}
+\label{sec:pgf:unknown:keys}
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
@@ -567,7 +673,7 @@ 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
+searched
for in |/a|, |/b|, and |/b/c|. We setup a key |/my search path| for
this:
\begin{codeexample}[code only]
@@ -584,12 +690,67 @@ this:
\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|.
+directories |/a|, |/b|, and |/b/c|. Before you start implementing
+search paths using this pattern, consider the |/.search also| handler
+discussed below.
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.
+\subsubsection{Search Paths And Handled Keys}
+
+There is one special case which occurs in the search path example
+above. What happens if we want to change a style? For example,
+\begin{codeexample}[code only]
+\pgfkeys{/my search path/.cd,custom/.style={variables}}
+\end{codeexample}
+\noindent could mean a style in |/my search path/|, |/a/|, |/b/| or
+even |/b/c/|!
+
+Due to the rules for handled keys, the answer is
+|/my search path/custom/.style={variables}|.
+It may be useful to modify this default behavior. One useful thing
+would be to search for \emph{existing} styles named |custom| and
+redefine them. For example, if a style |/b/custom| exists, the
+assignment |custom/.style={variables}| should probably redefine
+|/b/custom| instead of |/my search path/custom|. This can be done
+using |handler config|:
+\begin{codeexample}[]
+\pgfkeys{/my search path/.unknown/.code=
+ {%
+ \let\searchname=\pgfkeyscurrentname%
+ \pgfkeysalso{%
+ /a/\searchname/.try=#1,
+ /b/\searchname/.retry=#1,
+ /b/c/\searchname/.retry=#1%
+ }%
+ }%
+}
+
+% Let's define /b/custom here:
+\pgfkeys{/b/custom/.code={This is `\pgfkeyscurrentkey'. }}
+
+% Reconfigure treatment of key handlers:
+\pgfkeys{/handler config=only existing}
+
+% The search path procedure will find /b/custom
+% -> leads to This is `/b/custom'
+\pgfkeys{/my search path/.cd,custom}
+
+% Due to the reconfiguration, this will find /b/custom instead of
+% defining /my search path/custom:
+\pgfkeys{/my search path/.cd,custom/.append code={Modified. }}
+
+% So using the search path, we again find /b/custom which
+% leads to This is `/b/custom' Modified
+\pgfkeys{/my search path/.cd,custom}
+\end{codeexample}
+
+A slightly different approach to search paths can be realized using
+the |/.search also| key handler, see below.
+
+
\subsection{Key Handlers}
We now describe which key handlers are defined by default. You can
@@ -607,17 +768,138 @@ also define new ones as described in Section~\ref{section-key-handlers}.
\end{handler}
\begin{handler}{{.is family}}
+\label{section-is family-handler}
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}
+\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.
+ |/.is family| handler is quicker.
\end{handler}
+\begin{handler}{{.search also}=\marg{path list}}
+ A style which installs a |/.unknown| handler into \meta{key}. This
+ |/.unknown| handler will then search for unknown keys in every path
+ provided in \marg{path list}.
+
+\begin{codeexample}[]
+% define a key:
+\pgfkeys{/secondary path/option/.code={Invoking /secondary path/option with `#1'}}
+
+% set up a search path:
+\pgfkeys{/main path/.search also={/secondary path}}
+
+% try searching for `option=value' in '/main path':
+% -> this finds `/secondary path/option'!
+\pgfkeys{/main path/.cd,option=value}
+\end{codeexample}
+
+ The |/.search also| handler follows the strategy
+ \begin{enumerate}
+ \item If a user provides a fully qualified key which could not be
+ found, for example the full string |/main path/option|, it assume
+ that the user new what he is doing -- and does \emph{not} continue
+ searching for |an option| in \marg{path list}.
+ \item If a user provides only the key's name, for example |option|
+ and |option| can't be found in the current default path (which is
+ |/main path| in our example above), the current default path is
+ set to the next element in \marg{path list} (which is
+ |/secondary path| here) and |\pgfkeys| will be restarted.
+
+ This will be iterated until either a match has been found or all
+ elements in \marg{path list} have been tested.
+
+ \item If all elements in \marg{path list} have been checked and the
+ key is still unknown, the fall-back handler |/handlers/.unknown|
+ will be invoked.
+ \end{enumerate}
+\begin{codeexample}[]
+% define a key:
+\pgfkeys{/secondary path/option/.code={Invoking /secondary path/option with `#1'}}
+
+% set up a search path:
+\pgfkeys{/main path/.search also={/secondary path}}
+
+% try searching for `option=value' in '/main path':
+% -> this finds `/secondary path/option'!
+\pgfkeys{/main path/.cd,option=value}
+
+% negative example:
+% try searching for fully qualified key /main path/option.
+% This won't be handled by .search also.
+\pgfkeys{/handlers/.unknown/.code={Found unknown option \pgfkeyscurrentkeyRAW={#1}!}}%
+\pgfkeys{/main path/.cd,/main path/option=value}
+\end{codeexample}
+
+ Please note that the strategy of |/.search also| is different from
+ the first example provided in section~\ref{sec:pgf:unknown:keys}
+ ``Unknown Keys'' because |/.search also| only applies only for keys
+ which are not fully qualified.
+
+
+ For those who are familiar with |\pgfkeys|, the actual
+ implementation of |/.search also| might be interesting:
+ \begin{enumerate}
+ \item |\pgfkeys{/path/.search also={/tikz}}| is equivalent to
+\begin{codeexample}[code only]
+\pgfkeys{/path/.unknown/.code={%
+ \ifpgfkeysaddeddefaultpath
+ % only process keys for which no full path has been
+ % provided:
+ \pgfkeyssuccessfalse
+ \let\pgfkeys@searchalso@name =\pgfkeyscurrentkeyRAW
+ \ifpgfkeyssuccess
+ \else
+ % search with /tikz as default path:
+ \pgfqkeys{/tikz}{\pgfkeys@searchalso@name={#1}}%
+ \fi
+ \else
+ \def\pgfutilnext{\pgfkeysvalueof {/handlers/.unknown/.@cmd}#1\pgfeov}%
+ \pgfutilnext
+ \fi
+ }
+}
+\end{codeexample}
+ \item |\pgfkeys{/path/.search also={/tikz,/pgf}}| is equivalent to
+\begin{codeexample}[code only]
+\pgfkeys{/path/.unknown/.code={%
+ \ifpgfkeysaddeddefaultpath
+ \pgfkeyssuccessfalse
+ \let\pgfkeys@searchalso@name=\pgfkeyscurrentkeyRAW
+ \ifpgfkeyssuccess
+ \else
+ % step 1: search in /tikz with .try:
+ \pgfqkeys{/tikz}{\pgfkeys@searchalso@name/.try={#1}}%
+ \fi
+ \ifpgfkeyssuccess
+ \else
+ % step 2: search in /pgf (without .try!):
+ \pgfqkeys{/pgf}{\pgfkeys@searchalso@name={#1}}%
+ \fi
+ \else
+ \def\pgfutilnext{\pgfkeysvalueof {/handlers/.unknown/.@cmd}#1\pgfeov}%
+ \pgfutilnext
+ \fi
+ }
+}
+\end{codeexample}
+ \end{enumerate}
+
+ To also enable searching for styles (or other handled keys),
+ consider changing the configuration for handled keys to
+ |/hander config=full or existing| when you use |/.search also|,
+ that is, use
+\begin{codeexample}[code only]
+\pgfkeys{
+ /main path/.search also={/secondary path},
+ /handler config=full or existing}
+\end{codeexample}
+\end{handler}
+
+
\subsubsection{Setting Defaults}
\label{section-default-handlers}
@@ -643,7 +925,7 @@ also define new ones as described in Section~\ref{section-key-handlers}.
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.
+ handler.
\begin{codeexample}[code only]
\pgfkeys{/my key/.code=I do not want an argument!}
\pgfkeys{/my key/.value forbidden}
@@ -681,13 +963,13 @@ A number of handlers exist for defining the code of keys.
\end{handler}
\begin{handler}{{.ecode}|=|\meta{code}}
- This handler works like |.code|, only the command |\pgfkeysedef| is
- used.
+ 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
+ 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,
@@ -695,42 +977,64 @@ A number of handlers exist for defining the code of keys.
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}
+ The second argument is optional: if it is not provided, it will be the empty string.
+
+ 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|.
\end{handler}
\begin{handler}{{.ecode 2 args}|=|\meta{code}}
- This handler works like |.code 2 args|, only an |\edef| is used
+ 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 n args}|=|\marg{argument count}\marg{code}}
+ This handler also works like |/.code|, but you can now specify a
+ number of arguments between $0$ and $9$ (inclusive).
+\begin{codeexample}[]
+\pgfkeys{/a key/.code n args={2}{First=`#1', Second=`#2'}}
+\pgfkeys{/a key={A}{B}}
+\end{codeexample}
+ In contrast to |/.code 2 args|, there must be exactly \meta{argument
+ count} arguments, not more and not less and these arguments should
+ be properly delimited.
+\end{handler}
+
+\begin{handler}{{.ecode n args}|=|\marg{argument count}\marg{code}}
+ This handler works like |/.code n 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.
+ This handler is the most flexible way to define a |/.code| key: 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}
+
+ Note that |/.code n args| should be preferred in case you need just a number
+ of arguments (when the resulting keys are used, |/.code n args|
+ gobbles spaces between the arguments whereas |/.code args| considers
+ spaces to be part of the argument).
\end{handler}
\begin{handler}{{.ecode args}|=|\marg{argument pattern}\marg{code}}
- This handler works like |.code args|, only an |\edef| is used
+ This handler works like |/.code args|, only an |\edef| is used
rather than a |\def| to define the macro.
\end{handler}
@@ -743,11 +1047,11 @@ There are also handlers for modifying existing keys.
\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|.
-
+ may contain parameters like |#2|.
+
\begin{codeexample}[code only]
\pgfkeys{/par indent/.code={\parindent=#1}}
-\newdimen\myparindent
+\newdimen\myparindent
\pgfkeys{/par indent/.add code={}{\myparindent=#1}}
...
\pgfkeys{/par indent=1cm} % This will set both \parindent and
@@ -772,7 +1076,7 @@ There are also handlers for modifying existing keys.
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.
+list. Styles can be parameterized just like normal code.
\begin{handler}{{.style}|=|\meta{key list}}
This handler set things up so that whenever \meta{key}|=|\meta{value} is
@@ -784,7 +1088,7 @@ list. Styles can be parametrized just like normal code.
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.
+ normal code and only then process some further keys.
\begin{codeexample}[code only]
\pgfkeys{/par indent/.code={\parindent=#1}}
@@ -794,7 +1098,7 @@ list. Styles can be parametrized just like normal code.
...
\pgfkeys{/normal indent}
\end{codeexample}
- The following example shows a parametrized style ``in action''.
+ The following example shows a parameterized style ``in action''.
\begin{codeexample}[]
\begin{tikzpicture}[outline/.style={draw=#1,fill=#1!20}]
\node [outline=red] {red box};
@@ -804,7 +1108,7 @@ list. Styles can be parametrized just like normal code.
\end{handler}
\begin{handler}{{.estyle}|=|\meta{key list}}
- This handler works like |.style|, only the \meta{code} is set using
+ 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}
@@ -812,10 +1116,10 @@ list. Styles can be parametrized just like normal code.
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
+ 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}.
+ \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}}
@@ -824,24 +1128,28 @@ For styles the corresponding handlers as for normal code exist:
\end{handler}
\begin{handler}{{.estyle 2 args}|=|\meta{key list}}
- This handler works like |.style 2 args|, only an |\edef| is used
+ 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.
+ 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.
+ This handler works like |/.ecode args|, only for styles.
+\end{handler}
+
+\begin{handler}{{.style n args}|=|\marg{argument count}\meta{key list}}
+ This handler works like |/.code n args|, only for styles. Here, \meta{key list} may depend on all \meta{argument count} parameters.
\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
+ 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
+ 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
@@ -856,11 +1164,11 @@ For styles the corresponding handlers as for normal code exist:
\end{handler}
\begin{handler}{{.prefix style}|=|\meta{prefix key list}}
- Works like |.add style|, but only for the 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.
+ Works like |/.add style|, but only for the append key list.
\end{handler}
@@ -894,12 +1202,12 @@ that is directly stored in a key.
|/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.
+ 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}.
+ stored in \meta{key}.
\begin{codeexample}[]
\pgfkeys{/my key/.initial=red}
@@ -914,6 +1222,21 @@ that is directly stored in a key.
value} at the end of the value stored in \meta{key}.
\end{handler}
+\begin{handler}{{.prefix}|=|\marg{prefix value}}
+ Adds the \meta{prefix value} and the beginning of the value stored in \meta{key}.
+\end{handler}
+
+\begin{handler}{{.append}|=|\marg{append value}}
+ Adds the \meta{append value} at the end of the value stored in \meta{key}.
+\end{handler}
+
+\begin{handler}{{.link}|=|\meta{another key}}
+ Stores the value |\pgfkeysvalueof{|\meta{another key}|}| in the
+ \meta{key}. The idea is that when you expand the \meta{key}, the
+ value of \meta{another key} is expanded instead. This corresponds
+ loosely to the notion of soft links in Unix, hence the name.
+\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
@@ -923,10 +1246,10 @@ value in the key itself.
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}.
+ value is ``stored'' in the \meta{macro}.
\begin{codeexample}[]
\pgfkeys{/text/.store in=\mytext}
-\def\a{world}
+\def\a{world}
\pgfkeys{/text=Hello \a!}
\def\a{Gruffalo}
\mytext
@@ -934,13 +1257,13 @@ value in the key itself.
\end{handler}
\begin{handler}{{.estore in}|=|\meta{macro}}
- This handler is similar to |.store in|, only the code
+ 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}.
+ \meta{macro}.
\begin{codeexample}[]
\pgfkeys{/text/.estore in=\mytext}
-\def\a{world}
+\def\a{world}
\pgfkeys{/text=Hello \a!}
\def\a{Gruffalo}
\mytext
@@ -948,18 +1271,18 @@ value in the key itself.
\end{handler}
In another common situation a key is used to set a \TeX-if to true or
-false.
+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,
+ |/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
+\newif\iftheworldisflat
\pgfkeys{/flat world/.is if=theworldisflat}
\pgfkeys{/flat world=false}
\iftheworldisflat
@@ -995,7 +1318,7 @@ handler is useful.
\end{handler}
-\subsubsection{Expanding Values}
+\subsubsection{Expanded and Multiple 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
@@ -1046,6 +1369,20 @@ Key 4:& \pgfkeys{/key4}
before processing \meta{key}|=|\meta{result}.
\end{handler}
+\begin{handler}{{.list}|=|\meta{comma-separated list of values}}
+ This handler causes the key to be used repeatedly, namely once for
+ every element of the list of values. Note that the list of values
+ should typically be surrounded by braces since, otherwise, \TeX\
+ will not be able to tell whether a comma starts a new key or a new
+ value.
+
+ The \meta{list of values} is processed using the |\foreach|
+ statement, so you can use the |...| notation.
+\begin{codeexample}[]
+\pgfkeys{/foo/.code=(#1)}
+\pgfkeys{/foo/.list={a,b,0,1,...,5}}
+\end{codeexample}
+\end{handler}
\subsubsection{Handlers for Testing Keys}
@@ -1053,13 +1390,13 @@ Key 4:& \pgfkeys{/key4}
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,
+ 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.
+ the \meta{key} was successfully executed or not.
\begin{codeexample}[]
\pgfkeys{/a/.code=(a:#1)}
\pgfkeys{/b/.code=(b:#1)}
@@ -1068,9 +1405,9 @@ Key 4:& \pgfkeys{/key4}
\end{handler}
\begin{handler}{{.retry}|=|\meta{value}}
- This handler works just like |.try|, only it will not do anything if
+ 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''.
+ to set a key if ``the last attempt failed''.
\begin{codeexample}[]
\pgfkeys{/a/.code=(a:#1)}
\pgfkeys{/b/.code=(b:#1)}
@@ -1078,6 +1415,10 @@ Key 4:& \pgfkeys{/key4}
\end{codeexample}
\end{handler}
+\begin{handler}{{.lastretry}|=|\meta{value}}
+ This handler works like |/.retry|, only it will invoke the usual handlers for unknowns keys if |\||ifpgfkeyssuccess| is false. Thus, this handlers will only try to set a key if ``the last attempt failed''. Furthermore, this here is the last such attempt.
+\end{handler}
+
\subsubsection{Handlers for Key Inspection}
@@ -1098,7 +1439,7 @@ Key 4:& \pgfkeys{/key4}
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}.
+ This key will simply execute the given \meta{code}.
\example |\pgfkeys{some key=some value,/utils/exec=\show\hallo,obscure key=obscure}|
\end{key}
@@ -1118,7 +1459,7 @@ 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.
+ without a value when a value is actually required.
\end{key}
\begin{key}{/errors/value forbidden=\marg{offending key}\marg{value}}
@@ -1127,16 +1468,18 @@ language currently set so that users get a localized error message.
\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
+ 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.
+ 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.
+ |/.unknown| handler is found.
\end{key}
+
+\input pgfmanual-en-pgfkeysfiltered.tex