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.tex464
1 files changed, 316 insertions, 148 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 4ce292d380d..25825dc52c7 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
@@ -147,10 +147,10 @@ executed whenever the style is executed. Here is an example:
\pgfkeys{/my style/.style={/a=foo,/b=bar,/a=#1}}
\pgfkeys{/my style=wow}
\end{codeexample}
-As the above example shows, style can also be parametrized, just like
+As the above example shows, styles can also be paramaterized, just like
the normal code keys.
-As a typical use of styles, suppose we wish to setup the key |/tikz|
+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]
@@ -191,7 +191,7 @@ a slash, then the default path is automatically prefixed.
Note that the default path is not the same as a search path. In
particular, the default path is just a single path. When a partial key
is given, only this single default path is prefixed; |pgfkeys| does
-not try to lookup the key in different parts of a search path. It is,
+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.
@@ -222,7 +222,7 @@ continue with the next subsection.
\end{command}
\begin{command}{\pgfkeyslet\marg{full key}\marg{macro}}
- Performs a |\let| statement so the the \meta{full key} pionts to the
+ Performs a |\let| statement so the \meta{full key} points to the
contents of \meta{macro}.
\begin{codeexample}[]
\def\helloworld{Hello, world!}
@@ -283,13 +283,13 @@ taken. This action can be one of the following:
\item A command is executed whose argument(s) are \meta{value}. This
command is stored in a special subkey of \meta{key}.
\item The \meta{value} is stored in the \meta{key} itself.
-\item If the key's name (the part after the last slahs) is a known
+\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}
-Addtionally, if the \meta{value} is missing, a default value may or
+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.
@@ -329,7 +329,7 @@ let us have a quick look at the command itself.
\end{command}
\begin{command}{\pgfkeysalso\marg{key list}}
- This command has execatly the same effect as |\pgfkeys|, only the
+ 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.
@@ -344,6 +344,149 @@ let us have a quick look at the command itself.
\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
+\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
+\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
+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:
+\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
+\begin{codeexample}[]
+\let\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.
+ \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 |<|.
+
+\begin{codeexample}[]
+\pgfkeys{
+ /handlers/first char syntax=true,
+ /handlers/first char syntax/the character "/.initial=\myquotemacro,
+ /handlers/first char syntax/the character </.initial=\mypointedmacro,
+}
+
+\def\myquotemacro#1{Quoted: #1. }
+\def\mypointedmacro#1{Pointed: #1. }
+
+\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:
+
+\begin{codeexample}[]
+\pgfkeys{
+ /handlers/first char syntax=true,
+ /handlers/first char syntax/the character '/.initial=\mysinglequotemacro
+}
+
+\def\mysinglequotemacro#1{\pgfkeysalso{label={#1}}}
+
+\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.
+
+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:
+
+\begin{codeexample}[]
+\pgfkeys{
+ /handlers/first char syntax=true,
+ /handlers/first char syntax/the character (/.initial=\myparamacro
+}
+
+\def\myparamacro#1{\myparaparser#1\someendtext}
+\def\myparaparser(#1)#2\someendtext{
+ \pgfmathparse{#1}
+ \ifx\pgfmathresult\onetext
+ \pgfkeysalso{#2}
+ \fi
+}
+\def\onetext{1}
+
+\foreach \i in {1,...,4}
+ \tikz \node [draw, thick, rectangle, (pi>\i) circle, (pi>\i*2) draw=red] {x};
+\end{codeexample}
+
+
\subsubsection{Default Arguments}
The arguments of the |\pgfkeys| command can either be of the form
@@ -356,7 +499,7 @@ value is defined, it will be used as if you had written
In the following, the details of how default values are determined is
described; however, you should normally use the handlers |/.default|
and |/.value required| as described in
-Section~\ref{section-default-handlers} and you can may wish to skip
+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
@@ -391,7 +534,7 @@ following happens:
After the transformation process described in the previous subsection,
we arrive at a key of the form \meta{key}=\meta{value}, where
\meta{key} is a full key. Different things can now happen, but always
-the macro |\pgfkeyscurrentkey| will have been setup to expand to the
+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|
@@ -426,7 +569,7 @@ handlers described in Section~\ref{section-code-handlers}.
\begin{command}{\pgfkeysdef\marg{key}\marg{code}}
This command temporarily defines a \TeX-macro with the argument list
|#1\pgfeov| and then lets \meta{key}|/.@cmd| be equal to this
- macro. The net effect of all this is that you have then setup code
+ 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
@@ -517,9 +660,9 @@ key). It decomposed into two parts:
detect for the reader.
\end{enumerate}
-(For efficiency reasons, these two macros are only setup at this point;
+(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 setup.)
+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
@@ -527,7 +670,7 @@ and this command is executed exactly in the same manner as described
in Section~\ref{section-key-code}.
Thus, this code gets the \meta{value} that was originally intended for
\meta{key} as its argument, followed by |\pgfeov|.
-It is the job of the handlers to so something useful with the
+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
@@ -550,10 +693,10 @@ 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 setup appropriately.
+|\writetolog| is set up appropriately.
For a more interesting handler, let us program a handler that will
-setup a key so that when the key is used some code is executed. This
+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.
@@ -655,11 +798,13 @@ There are some parameters for handled keys which prove to be useful in some (pos
key handler.
\end{key}
+
+
\subsubsection{Keys That Are Unknown}
\label{sec:pgf:unknown:keys}
-For some keys, neither the key is defined nor its |.@cmd| subkey nor
-is a handler defined for this key. In this case, it is checked whether
+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
@@ -668,13 +813,13 @@ instance, the handler for \tikzname\ will try to interpret the key's
name as a color or as an arrow specification or as a \pgfname\
option.
-You can setup unknown key handlers for your own keys by simply setting
+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 setup ``search paths.'' The idea is that you would like keys to
+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 setup a key |/my search path| for
+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=
@@ -780,125 +925,6 @@ also define new ones as described in Section~\ref{section-key-handlers}.
|/.is family| handler is quicker.
\end{handler}
-\begin{handler}{{.search also}=\marg{path list}}
- A style which installs a |/.unknown| handler into \meta{key}. This
- |/.unknown| handler will then search for unknown keys in every path
- provided in \marg{path list}.
-
-\begin{codeexample}[]
-% define a key:
-\pgfkeys{/secondary path/option/.code={Invoking /secondary path/option with `#1'}}
-
-% set up a search path:
-\pgfkeys{/main path/.search also={/secondary path}}
-
-% try searching for `option=value' in '/main path':
-% -> this finds `/secondary path/option'!
-\pgfkeys{/main path/.cd,option=value}
-\end{codeexample}
-
- The |/.search also| handler follows the strategy
- \begin{enumerate}
- \item If a user provides a fully qualified key which could not be
- found, for example the full string |/main path/option|, it assume
- that the user new what he is doing -- and does \emph{not} continue
- searching for |an option| in \marg{path list}.
- \item If a user provides only the key's name, for example |option|
- and |option| can't be found in the current default path (which is
- |/main path| in our example above), the current default path is
- set to the next element in \marg{path list} (which is
- |/secondary path| here) and |\pgfkeys| will be restarted.
-
- This will be iterated until either a match has been found or all
- elements in \marg{path list} have been tested.
-
- \item If all elements in \marg{path list} have been checked and the
- key is still unknown, the fall-back handler |/handlers/.unknown|
- will be invoked.
- \end{enumerate}
-\begin{codeexample}[]
-% define a key:
-\pgfkeys{/secondary path/option/.code={Invoking /secondary path/option with `#1'}}
-
-% set up a search path:
-\pgfkeys{/main path/.search also={/secondary path}}
-
-% try searching for `option=value' in '/main path':
-% -> this finds `/secondary path/option'!
-\pgfkeys{/main path/.cd,option=value}
-
-% negative example:
-% try searching for fully qualified key /main path/option.
-% This won't be handled by .search also.
-\pgfkeys{/handlers/.unknown/.code={Found unknown option \pgfkeyscurrentkeyRAW={#1}!}}%
-\pgfkeys{/main path/.cd,/main path/option=value}
-\end{codeexample}
-
- Please note that the strategy of |/.search also| is different from
- the first example provided in section~\ref{sec:pgf:unknown:keys}
- ``Unknown Keys'' because |/.search also| only applies only for keys
- which are not fully qualified.
-
-
- For those who are familiar with |\pgfkeys|, the actual
- implementation of |/.search also| might be interesting:
- \begin{enumerate}
- \item |\pgfkeys{/path/.search also={/tikz}}| is equivalent to
-\begin{codeexample}[code only]
-\pgfkeys{/path/.unknown/.code={%
- \ifpgfkeysaddeddefaultpath
- % only process keys for which no full path has been
- % provided:
- \pgfkeyssuccessfalse
- \let\pgfkeys@searchalso@name =\pgfkeyscurrentkeyRAW
- \ifpgfkeyssuccess
- \else
- % search with /tikz as default path:
- \pgfqkeys{/tikz}{\pgfkeys@searchalso@name={#1}}%
- \fi
- \else
- \def\pgfutilnext{\pgfkeysvalueof {/handlers/.unknown/.@cmd}#1\pgfeov}%
- \pgfutilnext
- \fi
- }
-}
-\end{codeexample}
- \item |\pgfkeys{/path/.search also={/tikz,/pgf}}| is equivalent to
-\begin{codeexample}[code only]
-\pgfkeys{/path/.unknown/.code={%
- \ifpgfkeysaddeddefaultpath
- \pgfkeyssuccessfalse
- \let\pgfkeys@searchalso@name=\pgfkeyscurrentkeyRAW
- \ifpgfkeyssuccess
- \else
- % step 1: search in /tikz with .try:
- \pgfqkeys{/tikz}{\pgfkeys@searchalso@name/.try={#1}}%
- \fi
- \ifpgfkeyssuccess
- \else
- % step 2: search in /pgf (without .try!):
- \pgfqkeys{/pgf}{\pgfkeys@searchalso@name={#1}}%
- \fi
- \else
- \def\pgfutilnext{\pgfkeysvalueof {/handlers/.unknown/.@cmd}#1\pgfeov}%
- \pgfutilnext
- \fi
- }
-}
-\end{codeexample}
- \end{enumerate}
-
- To also enable searching for styles (or other handled keys),
- consider changing the configuration for handled keys to
- |/hander config=full or existing| when you use |/.search also|,
- that is, use
-\begin{codeexample}[code only]
-\pgfkeys{
- /main path/.search also={/secondary path},
- /handler config=full or existing}
-\end{codeexample}
-\end{handler}
-
\subsubsection{Setting Defaults}
@@ -1079,7 +1105,7 @@ 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 set things up so that whenever \meta{key}|=|\meta{value} is
+ 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
@@ -1176,8 +1202,8 @@ For styles the corresponding handlers as for normal code exist:
For some keys, the code that should be executed for them is rather
``specialized.'' For instance, it happens often that the code for a
-key just sets a certain \TeX-if to true or false. For these case
-predefine handlers make it easier to install the necessary code.
+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.
@@ -1196,7 +1222,7 @@ that is directly stored in a key.
% "/my key" now stores the value "blue"
\end{codeexample}
- Note that in the after the example, writing |\pgfkeys{/my key}| will not
+ 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
@@ -1300,7 +1326,7 @@ The next handler deals with the problem when a
handler is useful.
\begin{handler}{{.is choice}}
- This handler set things up so that writing \meta{key}|=|\meta{value}
+ 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}.
@@ -1327,7 +1353,7 @@ can even use things like |#1| or unbalanced \TeX-ifs inside
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}
+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:
@@ -1384,6 +1410,148 @@ Key 4:& \pgfkeys{/key4}
\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.
+\begin{codeexample}[]
+\pgfkeys{
+ /a/.code=(a:#1),
+ /b/.code=(b:#1),
+ /b/.forward to=/a,
+ /c/.forward to=/a
+}
+\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}.
+
+\begin{codeexample}[]
+% define a key:
+\pgfkeys{/secondary path/option/.code={Invoking /secondary path/option with `#1'}}
+
+% set up a search path:
+\pgfkeys{/main path/.search also={/secondary path}}
+
+% try searching for `option=value' in '/main path':
+% -> this finds `/secondary path/option'!
+\pgfkeys{/main path/.cd,option=value}
+\end{codeexample}
+
+ The |/.search also| handler follows the strategy
+ \begin{enumerate}
+ \item If a user provides a fully qualified key which could not be
+ found, for example the full string |/main path/option|, it assume
+ that the user 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'}}
+
+% set up a search path:
+\pgfkeys{/main path/.search also={/secondary path}}
+
+% try searching for `option=value' in '/main path':
+% -> this finds `/secondary path/option'!
+\pgfkeys{/main path/.cd,option=value}
+
+% negative example:
+% try searching for fully qualified key /main path/option.
+% This won't be handled by .search also.
+\pgfkeys{/handlers/.unknown/.code={Found unknown option \pgfkeyscurrentkeyRAW={#1}!}}%
+\pgfkeys{/main path/.cd,/main path/option=value}
+\end{codeexample}
+
+ Please note that the strategy of |/.search also| is different from
+ the first example provided in section~\ref{sec:pgf:unknown:keys}
+ ``Unknown Keys'' because |/.search also| only applies 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
+ % only process keys for which no full path has been
+ % provided:
+ \pgfkeyssuccessfalse
+ \let\pgfkeys@searchalso@name =\pgfkeyscurrentkeyRAW
+ \ifpgfkeyssuccess
+ \else
+ % search with /tikz as default path:
+ \pgfqkeys{/tikz}{\pgfkeys@searchalso@name={#1}}%
+ \fi
+ \else
+ \def\pgfutilnext{\pgfkeysvalueof {/handlers/.unknown/.@cmd}#1\pgfeov}%
+ \pgfutilnext
+ \fi
+ }
+}
+\end{codeexample}
+ \item |\pgfkeys{/path/.search also={/tikz,/pgf}}| is equivalent to
+\begin{codeexample}[code only]
+\pgfkeys{/path/.unknown/.code={%
+ \ifpgfkeysaddeddefaultpath
+ \pgfkeyssuccessfalse
+ \let\pgfkeys@searchalso@name=\pgfkeyscurrentkeyRAW
+ \ifpgfkeyssuccess
+ \else
+ % step 1: search in /tikz with .try:
+ \pgfqkeys{/tikz}{\pgfkeys@searchalso@name/.try={#1}}%
+ \fi
+ \ifpgfkeyssuccess
+ \else
+ % step 2: search in /pgf (without .try!):
+ \pgfqkeys{/pgf}{\pgfkeys@searchalso@name={#1}}%
+ \fi
+ \else
+ \def\pgfutilnext{\pgfkeysvalueof {/handlers/.unknown/.@cmd}#1\pgfeov}%
+ \pgfutilnext
+ \fi
+ }
+}
+\end{codeexample}
+ \end{enumerate}
+
+ To also enable searching for styles (or other handled keys),
+ consider changing the configuration for handled keys to
+ |/hander config=full or existing| when you use |/.search also|,
+ that is, use
+\begin{codeexample}[code only]
+\pgfkeys{
+ /main path/.search also={/secondary path},
+ /handler config=full or existing}
+\end{codeexample}
+\end{handler}
+
+
\subsubsection{Handlers for Testing Keys}
\begin{handler}{{.try}|=|\meta{value}}
@@ -1416,7 +1584,7 @@ Key 4:& \pgfkeys{/key4}
\end{handler}
\begin{handler}{{.lastretry}|=|\meta{value}}
- This handler works like |/.retry|, only it will invoke the usual handlers for unknowns keys if |\||ifpgfkeyssuccess| is false. Thus, this handlers will only try to set a key if ``the last attempt failed''. Furthermore, this here is the last such attempt.
+ 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}
@@ -1468,13 +1636,13 @@ language currently set so that users get a localized error message.
\end{key}
\begin{key}{/errors/boolean expected=\marg{offending key}\marg{value}}
- This key is executed whenever a key setup using |/.is if| gets called
+ This key is executed whenever a key 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 setup using the |/.is choice| handler that is not defined.
+ 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}}