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.tex1667
1 files changed, 852 insertions, 815 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 423fac92e88..392e2298142 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
@@ -11,423 +11,431 @@
\section{Key Management}
\label{section-keys}
-This section describes the package |pgfkeys|. It is loaded
-automatically by both \pgfname\ and \tikzname.
+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. % pgfkey --> 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| \todosp{pgfkey --> pgfkeys?} 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:
+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 |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.
+ \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 |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.
+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.
+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}.
+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:
+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!|.
+%
+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.
+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|.
+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.
+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):
+%
+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:
+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, styles can also be paramaterized, just like
-the normal code keys.
+%
+As the above example shows, styles can also be parameterized, just like the
+normal code keys.
-As a typical use of styles, suppose we wish to set up the key |/tikz|
-so that it will change the default path to |/tikz|. This can be
-achieved as follows:
+As a typical use of styles, suppose we wish to set up 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|.
+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 look up 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
+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 look up 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.
+ 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.
+ 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 \meta{full key} points to the
- contents of \meta{macro}.
+ Performs a |\let| statement so the \meta{full key} points 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.
+ %
+ 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|.
+ 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.
-
+ 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.
+ 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:
-
+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 slash) 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.
+ \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 slash) 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}
-Additionally, 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.
+Additionally, 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).
+ 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.
+ 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 exactly 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.
+ This command has exactly 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.
+ 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{First Char Syntax Detection}
\label{sec:pgf:first:char:syntax}
-Usually, keys are of the form \meta{key}|=|\meta{value} and how such
-keys are handled is discussed in the rest of this section. However, it
-is also possible to setup a different syntax for certain parts of the
-input to |\pgfkeys|. Since this is a rather advanced option, most
-readers may wish to skip the following discussion upon first reading;
-it is discussed here because this special syntax detection is the very
-first thing that is done when a key is processed, before any of the
-following operations are performed.
-
-The |\pgfkeys| command and its variants decompose their input into a
-list of \meta{string}s that are separated by commas. By default, each
-such \meta{string} must either have the form \meta{key}|=|\meta{value}
-or of the form \meta{key} with the value-part missing. However, you
-might wish to interpret some of these strings differently. For
-instance, when a \meta{string} has the form |"|\meta{text}|"|, you
-might wish the \meta{string} to be interpreted as if one had written
-|label text={|\meta{text}|}|. Then, people could write
+Usually, keys are of the form \meta{key}|=|\meta{value} and how such keys are
+handled is discussed in the rest of this section. However, it is also possible
+to setup a different syntax for certain parts of the input to |\pgfkeys|. Since
+this is a rather advanced option, most readers may wish to skip the following
+discussion upon first reading; it is discussed here because this special syntax
+detection is the very first thing that is done when a key is processed, before
+any of the following operations are performed.
+
+The |\pgfkeys| command and its variants decompose their input into a list of
+\meta{string}s that are separated by commas. By default, each such
+\meta{string} must either have the form \meta{key}|=|\meta{value} or of the
+form \meta{key} with the value-part missing. However, you might wish to
+interpret some of these strings differently. For instance, when a \meta{string}
+has the form |"|\meta{text}|"|, you might wish the \meta{string} to be
+interpreted as if one had written |label text={|\meta{text}|}|. Then, people
+could write
+%
\begin{codeexample}[code only]
\myset{red, "main valve", thick}
\end{codeexample}
+%
instead of the more cumbersome
+%
\begin{codeexample}[code only]
\myset{red, label text=main valve, thick}
\end{codeexample}
-An example where such a syntax reinterpretation is done is the
-|quotes| library, which allows you to write things like
+%
+An example where such a syntax reinterpretation is done is the |quotes|
+library, which allows you to write things like
+%
\begin{codeexample}[]
\tikz \graph { a ->["1" red] b ->["0"] c };
\end{codeexample}
+%
\noindent instead of the somewhat longer
+%
\begin{codeexample}[]
\tikz \graph { a ->[edge node={node[red,auto]{1}}] b ->[edge label=0] c };
\end{codeexample}
-In order to detect whether a \meta{string} has a special syntax, you
-can request that the \emph{first character} of \meta{string} is
-analysed by the key parser. If this first character matches a
-character that has been flagged as a special character, the
-\meta{string} is not interpreted as a usual key--value pair. Instead,
-\meta{string} is passed as a parameter to a special macro that should
-take care of the \meta{string}. After this macro has finished, the
+In order to detect whether a \meta{string} has a special syntax, you can
+request that the \emph{first character} of \meta{string} is analysed by the key
+parser. If this first character matches a character that has been flagged as a
+special character, the \meta{string} is not interpreted as a usual key--value
+pair. Instead, \meta{string} is passed as a parameter to a special macro that
+should take care of the \meta{string}. After this macro has finished, the
parsing continues with the \meta{next string} in the list.
-In order to setup a special syntax handling for \meta{strings} that
-begin with a certain character, two things need to be done:
+In order to setup a special syntax handling for \meta{strings} that begin with
+a certain character, two things need to be done:
+%
\begin{enumerate}
-\item First, the whole first char syntax detection must be ``switched
- on,'' since, by default, it is turned off for efficiency reasons
- (the overhead is rather small, however). This is done by setting the
- following key:
- \begin{key}{/handlers/first char syntax=\opt{\meta{true or false}}
- (default true, initially false)}
- \end{key}
-\item Second, in order to handle strings starting with a certain
- \meta{character} in a special way, you need to store a macro in the
- following key:
- \begin{key}{/handlers/first char syntax/\meta{meaning of character}}
- The \meta{meaning of character} should be the text that \TeX's
- command |\meaning| returns for a macro that has been |\let| to the
- \meta{character}. For instance, when strings starting with |"|
- should be treated in a special way, the \meta{meaning of
- character} would be the string |the character "| since this is
- what \TeX\ writes when you say
+ \item First, the whole first char syntax detection must be ``switched on'',
+ since, by default, it is turned off for efficiency reasons (the
+ overhead is rather small, however). This is done by setting the
+ following key:
+ %
+ \begin{key}{/handlers/first char syntax=\opt{\meta{true or false}} (default true, initially false)}
+ \end{key}
+ \item Second, in order to handle strings starting with a certain
+ \meta{character} in a special way, you need to store a macro in the
+ following key:
+ %
+ \begin{key}{/handlers/first char syntax/\meta{meaning of character}}
+ The \meta{meaning of character} should be the text that \TeX's
+ command |\meaning| returns for a macro that has been |\let| to the
+ \meta{character}. For instance, when strings starting with |"|
+ should be treated in a special way, the \meta{meaning of character}
+ would be the string |the character "| since this is what \TeX\
+ writes when you say
+ %
\begin{codeexample}[]
\let\mycharacter="
-\meaning\mycharacter
+\meaning\mycharacter
\end{codeexample}
- Now, the key |/handlers/first char syntax/|\meta{meaning of
- character} should be setup (using |\pgfkeyssetvalue| or using
- the |.initial| handler) to store a \meta{macro name}.
-
- If this is the case and if \meta{string} starts with the
- \meta{character} (blanks at the beginning of \meta{string} are
- deleted prior to this test), then \meta{macro name} is called with
- \meta{string} as its argument.
+ %
+ Now, the key |/handlers/first char syntax/|\meta{meaning of
+ character} should be setup (using |\pgfkeyssetvalue| or using the
+ |.initial| handler) to store a \meta{macro name}.
+
+ If this is the case and if \meta{string} starts with the
+ \meta{character} (blanks at the beginning of \meta{string} are
+ deleted prior to this test), then \meta{macro name} is called with
+ \meta{string} as its argument.
\end{key}
\end{enumerate}
-Let us now have a look at an example. We install two handlers, one for
-strings starting with |"| and one for strings starting with |<|.
-
+Let us now have a look at an example. We install two handlers, one for strings
+starting with |"| and one for strings starting with |<|.
+%
\begin{codeexample}[]
\pgfkeys{
/handlers/first char syntax=true,
@@ -441,11 +449,11 @@ strings starting with |"| and one for strings starting with |<|.
\ttfamily \pgfkeys{"foo", <bar>}
\end{codeexample}
-Naturally, in the above examples, the two handling macros did not do
-something particularly exciting. In the next example, we setup a more
-elaborate macro that mimics a small part the behaviour of the |quotes|
-library, only for single quotes:
-
+Naturally, in the above examples, the two handling macros did not do something
+particularly exciting. In the next example, we setup a more elaborate macro
+that mimics a small part the behaviour of the |quotes| library, only for single
+quotes:
+%
\begin{codeexample}[]
\pgfkeys{
/handlers/first char syntax=true,
@@ -457,16 +465,16 @@ library, only for single quotes:
\tikz \node [circle, 'foo', draw] {bar};
\end{codeexample}
-Note that in the above example, the macro |\mysinglequotemacro| gets
-passed the complete string, including the single quotes. It is the job
-of the macro to get rid of them, if this is necessary.
+Note that in the above example, the macro |\mysinglequotemacro| gets passed the
+complete string, including the single quotes. It is the job of the macro to get
+rid of them, if this is necessary.
The first char syntax detection allows you to perform rather powerful
-transformations on the syntax of keys -- provided you can ``pin down''
-the syntax on the first character. In the following example, you can
-write expressions in parentheses in front of a key--value pair and the
-pair will only be executed when the expression evaluates to true:
-
+transformations on the syntax of keys -- provided you can ``pin down'' the
+syntax on the first character. In the following example, you can write
+expressions in parentheses in front of a key--value pair and the pair will only
+be executed when the expression evaluates to true:
+%
\begin{codeexample}[]
\pgfkeys{
/handlers/first char syntax=true,
@@ -490,70 +498,65 @@ pair will only be executed when the expression evaluates to true:
\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}.
+\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 may wish to skip
-the following details.
+described; however, you should normally use the handlers |/.default| and
+|/.value required| as described in Section~\ref{section-default-handlers} and
+you may wish to skip the following details.
-When |\pgfkeys| encounters a \meta{key} without an equal-sign, the
-following happens:
+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
- % FIXME : there is a bug in the pretty printer ... fix it and get rid of '||' here:
- |\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.
+ \item The input is replaced by \meta{key}|=\pgfkeysnovalue|. In particular,
+ the commands |\pgfkeys{my key}| and
+ % FIXME: there is a bug in the pretty printer ... fix it and get rid of '||' here:
+ |\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 set up 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
+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 set up 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:
+\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}
@@ -562,21 +565,20 @@ follows:
|\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}.
+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 set up 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|).
-
+ 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 set up 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}
@@ -584,17 +586,16 @@ handlers described in Section~\ref{section-code-handlers}.
\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.
+ 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}{\pgfkeysdefnargs\marg{key}\marg{argument count}\marg{code}}
- This command works like |\pgfkeysdef|, but it allows you to provide
- an arbitrary \meta{argument count} between $0$ and $9$ (inclusive).
-
+ This command works like |\pgfkeysdef|, but it allows you to provide 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=
@@ -603,86 +604,89 @@ handlers described in Section~\ref{section-code-handlers}.
|\a| is `\a', |\b| is `\b'.
\end{codeexample}
- The resulting key will expect exactly \marg{argument count} arguments.
+ %
+ 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|.
+ 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.
-
+ 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}}
\pgfkeys{/my key=hello+world}
|\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.}.
+ %
+ 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}}
- The |\edef| version of |\pgfkeysdefargs|.
+ 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}.
+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.
+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:
+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.
+ \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 set up at this point;
-so when code is executed for a key in the ``usual'' manner then these
-macros are not set up.)
+(For efficiency reasons, these two macros are only set up at this point; so
+when code is executed for a key in the ``usual'' manner then these macros are
+not set up.)
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 do 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.
-
+|/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 do 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}
{%
@@ -693,40 +697,41 @@ this key and print it.
...
\pgfkeys{/my key/.print to log}
\end{codeexample}
-The above code will print |Hi!| in the log, provided the macro
-|\writetolog| is set up appropriately.
-
-For a more interesting handler, let us program a handler that will
-set up 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.
+%
+The above code will print |Hi!| in the log, provided the macro |\writetolog| is
+set up appropriately.
+
+For a more interesting handler, let us program a handler that will set up 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}
-There are some parameters for handled keys which prove to be useful in some (possibly rare) special cases:
+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}).
+ 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. }}
@@ -750,78 +755,77 @@ There are some parameters for handled keys which prove to be useful in some (pos
% '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}
+ %
+ 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.
+\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, nor its |.@cmd| subkey nor
-a handler is defined. 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 set up 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 set up ``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 set up a key |/my search path| for
-this:
+For some keys, neither the key, nor its |.@cmd| subkey nor a handler is
+defined. 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 set up 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 set
+up ``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 set up a key
+|/my search path| for this:
+%
\begin{codeexample}[code only]
\pgfkeys{/my search path/.unknown/.code=
{%
@@ -835,33 +839,36 @@ 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|. Before you start implementing
-search paths using this pattern, consider the |/.search also| handler
-discussed below.
+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.
-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,
+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/|!
+%
+\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|:
+|/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=
{%
@@ -893,66 +900,67 @@ using |handler config|:
\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.
+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
-also define new ones as described in Section~\ref{section-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~|/|.
+ 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,...}|
+ \example |\pgfkeys{/tikz/.cd,...}|
\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:
+ 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.
+ %
+ 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.
+ 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}|
+ \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.
+ 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}|
+ \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 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.
+ 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}
@@ -960,6 +968,7 @@ also define new ones as described in Section~\ref{section-key-handlers}.
\pgfkeys{/my key} % Ok
\pgfkeys{/my key=foo} % Error
\end{codeexample}
+ %
\end{handler}
@@ -969,113 +978,111 @@ also define new ones as described in Section~\ref{section-key-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.
-
+ 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.
+ 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|.
-
+ 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|.
+ %
\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.
+ %
+ 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|.
+ 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
- rather than a |\def| to define the macro.
+ 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).
+ 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.
+ %
+ 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.
+ 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 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.
-
+ 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).
+
+ 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
- rather than a |\def| to define the macro.
+ 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|.
-
+ 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
@@ -1084,39 +1091,40 @@ There are also handlers for modifying existing keys.
\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|.
+ 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}|}{}|.
+ 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 parameterized just like normal code.
+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 parameterized just
+like normal code.
\begin{handler}{{.style}|=|\meta{key list}}
- This handler sets 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.
-
+ This handler sets 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}}
@@ -1125,62 +1133,68 @@ list. Styles can be parameterized just like normal code.
...
\pgfkeys{/normal indent}
\end{codeexample}
- The following example shows a parameterized 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};
\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.
+ 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}.
+ 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.
+ 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.
+ 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
- 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.
+ 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}}
@@ -1188,34 +1202,35 @@ For styles the corresponding handlers as for normal code exist:
\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.
+ 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}
\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 cases,
-predefined handlers make it easier to install the necessary code.
+``specialized''. For instance, it happens often that the code for a key just
+sets a certain \TeX-if to true or false. For these cases, predefined 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.
+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.
-
+ 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"
@@ -1223,57 +1238,58 @@ that is directly stored in a key.
% "/my key" now stores the value "blue"
\end{codeexample}
- Note that with this configuration, 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|.
+ Note that with this configuration, 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.
+ 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}.
-
+ 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}.
+ 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}
\begin{handler}{{.prefix}|=|\marg{prefix value}}
- Adds the \meta{prefix value} and the beginning of the value stored in \meta{key}.
+ 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}.
+ 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.
+ 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
-value in the key itself.
+\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}.
+ 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}
@@ -1281,13 +1297,14 @@ value in the key itself.
\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}.
+ 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}
@@ -1295,19 +1312,19 @@ value in the key itself.
\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.
+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.
+ 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}
@@ -1318,19 +1335,19 @@ false.
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.
+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 sets 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}.
+ This handler sets 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}}
@@ -1340,30 +1357,31 @@ handler is useful.
...
\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.
+ %
+ If the subkey \meta{key}|/|\meta{value} does not exist, the error key
+ |/errors/unknown choice value| is executed.
\end{handler}
\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
-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:
+\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.
+ 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}
@@ -1385,44 +1403,47 @@ 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}.
+ 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}.
+ This handler will completely expand \meta{value} (using |\edef|) 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.
+ 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 Forwarding}
\begin{handler}{{.forward to}|=|\meta{another key}}
- This handler causes the \meta{key} to ``forward'' its argument to
- \meta{another key}. When the \meta{key} is used, its normal code
- will be executed first. Then, the value is (additionally) passed to
- \meta{another key}. If the \meta{key} has not yet been defined prior
- to the use of |.forward to|, it will be defined then (and do nothing by
- itself, expect for forwarding it to \meta{key name}). The
- \meta{another key} must be a fully qualified key name.
+ This handler causes the \meta{key} to ``forward'' its argument to
+ \meta{another key}. When the \meta{key} is used, its normal code will be
+ executed first. Then, the value is (additionally) passed to \meta{another
+ key}. If the \meta{key} has not yet been defined prior to the use of
+ |.forward to|, it will be defined then (and do nothing by itself, expect
+ for forwarding it to \meta{key name}). The \meta{another key} must be a
+ fully qualified key name.
+ %
\begin{codeexample}[]
\pgfkeys{
/a/.code=(a:#1),
@@ -1432,14 +1453,14 @@ Key 4:& \pgfkeys{/key4}
}
\pgfkeys{/b=1} \pgfkeys{/c=2}
\end{codeexample}
+ %
\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}.
-
+ 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'}}
@@ -1452,24 +1473,26 @@ Key 4:& \pgfkeys{/key4}
\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 knew what she 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| cannot 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}
+ 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 knew what she 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| cannot 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'}}
@@ -1488,15 +1511,17 @@ Key 4:& \pgfkeys{/key4}
\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 to keys
- that 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
+ 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 to keys that 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
@@ -1516,7 +1541,9 @@ Key 4:& \pgfkeys{/key4}
}
}
\end{codeexample}
- \item |\pgfkeys{/path/.search also={/tikz,/pgf}}| is equivalent to
+ %
+ \item |\pgfkeys{/path/.search also={/tikz,/pgf}}| is equivalent to
+ %
\begin{codeexample}[code only]
\pgfkeys{/path/.unknown/.code={%
\ifpgfkeysaddeddefaultpath
@@ -1539,117 +1566,127 @@ Key 4:& \pgfkeys{/key4}
}
}
\end{codeexample}
- \end{enumerate}
+ \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
+ 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{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.
+ 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''.
+ 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}
\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 handler will only try to set a key if ``the last attempt failed''. Furthermore, this here is the last such attempt.
+ This handler works like |/.retry|, only it will invoke the usual handlers
+ for unknowns keys if |\||ifpgfkeyssuccess| is false. Thus, this handler
+ 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}
\begin{handler}{{.show value}}
- This handler executes a |\show| command on the value stored in
- \meta{key}. This is useful mostly for debugging.
+ 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}|
+ \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.
+ 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}|
+ \example |\pgfkeys{/my/obscure key/.show code}|
\end{handler}
-The following key is not a handler, but it also commonly used for
-inspecting things:
+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}.
- % FIXME : there is a bug in the pretty printer ... fix it!
- \example \verb|\pgfkeys{some key=some value,/utils/exec=\show\hallo,obscure key=obscure}|
+ % FIXME: there is a bug in the pretty printer ... fix it!
+ \example \verb|\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).
+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.
+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.
+ 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.
+ 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 set up using |/.is if| gets called
- with a \meta{value} other than |true| or |false|.
+ This key is executed whenever a key set up 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 set up using the |/.is choice| handler that is not defined.
+ This key is executed whenever a choice is used as a \meta{value} for a key
+ set up 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.
+ This key is executed whenever a key is unknown and no specific |/.unknown|
+ handler is found.
\end{key}
-\input pgfmanual-en-pgfkeysfiltered.tex
+
+\input{pgfmanual-en-pgfkeysfiltered.tex}