| 1 |
% Copyright 2019 by Till Tantau |
| 2 |
% |
| 3 |
% This file may be distributed and/or modified |
| 4 |
% |
| 5 |
% 1. under the LaTeX Project Public License and/or |
| 6 |
% 2. under the GNU Free Documentation License. |
| 7 |
% |
| 8 |
% See the file doc/generic/pgf/licenses/LICENSE for more details. |
| 9 |
|
| 10 |
|
| 11 |
\section{Key Management} |
| 12 |
\label{section-keys} |
| 13 |
|
| 14 |
This section describes the package |pgfkeys|. It is loaded automatically by |
| 15 |
both \pgfname\ and \tikzname. |
| 16 |
|
| 17 |
\begin{package}{pgfkeys} |
| 18 |
This package can be used independently of \pgfname. Note that no |
| 19 |
other package of \pgfname\ needs to be loaded (so neither the |
| 20 |
emulation layer nor the system layer is needed). The Con\TeX t |
| 21 |
abbreviation is |pgfkey| \todosp{pgfkey --> pgfkeys?} if |pgfmod| is not loaded. |
| 22 |
\end{package} |
| 23 |
|
| 24 |
|
| 25 |
\subsection{Introduction} |
| 26 |
|
| 27 |
\subsubsection{Comparison to Other Packages} |
| 28 |
|
| 29 |
The |pgfkeys| package defines a key--value management system that is in some |
| 30 |
sense similar to the more light-weight |keyval| system and the improved |
| 31 |
|xkeyval| system. However, |pgfkeys| uses a slightly different philosophy than |
| 32 |
these systems and it will coexist peacefully with both of them. |
| 33 |
|
| 34 |
The main differences between |pgfkeys| and |xkeyval| are the following: |
| 35 |
% |
| 36 |
\begin{itemize} |
| 37 |
\item |pgfkeys| organizes keys in a tree, while |keyval| and |xkeyval| |
| 38 |
use families. In |pgfkeys| the families correspond to the root |
| 39 |
entries of the key tree. |
| 40 |
\item |pgfkeys| has no save-stack impact (you will have to read the \TeX |
| 41 |
Book very carefully to appreciate this). |
| 42 |
\item |pgfkeys| is slightly slower than |keyval|, but not much. |
| 43 |
\item |pgfkeys| supports styles. This means that keys can just stand for |
| 44 |
other keys (which can stand for other keys in turn or which can also |
| 45 |
just execute some code). \tikzname\ uses this mechanism heavily. |
| 46 |
\item |pgfkeys| supports multi-argument key code. This can, however, be |
| 47 |
emulated in |keyval|. |
| 48 |
\item |pgfkeys| supports handlers. These are call-backs that are called |
| 49 |
when a key is not known. They are very flexible, in fact even |
| 50 |
defining keys in different ways is handled by, well, handlers. |
| 51 |
\end{itemize} |
| 52 |
|
| 53 |
|
| 54 |
\subsubsection{Quick Guide to Using the Key Mechanism} |
| 55 |
|
| 56 |
The following quick guide to \pgfname's key mechanism only treats the most |
| 57 |
commonly used features. For an in-depth discussion of what is going on, please |
| 58 |
consult the remainder of this section. |
| 59 |
|
| 60 |
Keys are organized in a large tree that is reminiscent of the Unix file tree. A |
| 61 |
typical key might be, say, |/tikz/coordinate system/x| or just |/x|. Again as |
| 62 |
in Unix, when you specify keys you can provide the complete path of the key, |
| 63 |
but you usually just provide the name of the key (corresponding to the file |
| 64 |
name without any path) and the path is added automatically. |
| 65 |
|
| 66 |
Typically (but not necessarily) some code is associated with a key. To execute |
| 67 |
this code, you use the |\pgfkeys| command. This command takes a list of |
| 68 |
so-called key--value pairs. Each pair is of the form \meta{key}|=|\meta{value}. |
| 69 |
For each pair the |\pgfkeys| command will execute the code stored for the |
| 70 |
\meta{key} with its parameter set to \meta{value}. |
| 71 |
|
| 72 |
Here is a typical example of how the |\pgfkeys| command is used: |
| 73 |
% |
| 74 |
\begin{codeexample}[code only] |
| 75 |
\pgfkeys{/my key=hallo,/your keys/main key=something\strange, |
| 76 |
key name without path=something else} |
| 77 |
\end{codeexample} |
| 78 |
|
| 79 |
Now, to set the code that is stored in a key you do not need to learn a new |
| 80 |
command. Rather, the |\pgfkeys| command can also be used to set the code of a |
| 81 |
key. This is done using so-called \emph{handlers}. They look like keys whose |
| 82 |
names look like ``hidden files in Unix'' since they start with a dot. The |
| 83 |
handler for setting the code of a key is appropriately called |/.code| and it |
| 84 |
is used as follows: |
| 85 |
% |
| 86 |
\begin{codeexample}[] |
| 87 |
\pgfkeys{/my key/.code=The value is '#1'.} |
| 88 |
\pgfkeys{/my key=hi!} |
| 89 |
\end{codeexample} |
| 90 |
% |
| 91 |
As you can see, in the first line we defined the code for the key |/my key|. In |
| 92 |
the second line we executed this code with the parameter set to |hi!|. |
| 93 |
|
| 94 |
There are numerous handlers for defining a key. For instance, we can also |
| 95 |
define a key whose value actually consists of more than one parameter. |
| 96 |
% |
| 97 |
\begin{codeexample}[] |
| 98 |
\pgfkeys{/my key/.code 2 args=The values are '#1' and '#2'.} |
| 99 |
\pgfkeys{/my key={a1}{a2}} |
| 100 |
\end{codeexample} |
| 101 |
|
| 102 |
We often want to have keys where the code is called with some default value if |
| 103 |
the user does not provide a value. Not surprisingly, this is also done using a |
| 104 |
handler, this time called |/.default|. |
| 105 |
% |
| 106 |
\begin{codeexample}[] |
| 107 |
\pgfkeys{/my key/.code=(#1)} |
| 108 |
\pgfkeys{/my key/.default=hello} |
| 109 |
\pgfkeys{/my key=hallo,/my key} |
| 110 |
\end{codeexample} |
| 111 |
|
| 112 |
The other way round, it is also possible to specify that a value \emph{must} be |
| 113 |
specified, using a handler called |/.value required|. Finally, you can also |
| 114 |
require that no value \emph{may} be specified using |/.value forbidden|. |
| 115 |
|
| 116 |
All keys for a package like, say, \tikzname\ start with the path |/tikz|. We |
| 117 |
obviously do not like to write this path down every time we use a key (so we do |
| 118 |
not have to write things like |\draw[/tikz/line width=1cm]|). What we need is |
| 119 |
to somehow ``change the default path to a specific location''. This is done |
| 120 |
using the handler |/.cd| (for ``change directory''). Once this handler has been |
| 121 |
used on a key, all subsequent keys {\itshape in the current call of |\pgfkeys| |
| 122 |
only} are automatically prefixed with this path, if necessary. |
| 123 |
|
| 124 |
Here is an example: |
| 125 |
% |
| 126 |
\begin{codeexample}[code only] |
| 127 |
\pgfkeys{/tikz/.cd,line width=1cm,line cap=round} |
| 128 |
\end{codeexample} |
| 129 |
% |
| 130 |
This makes it easy to define commands like |\tikzset|, which could be defined |
| 131 |
as follows (the actual definition is a bit faster, but the effect is the same): |
| 132 |
% |
| 133 |
\begin{codeexample}[code only] |
| 134 |
\def\tikzset#1{\pgfkeys{/tikz/.cd,#1}} |
| 135 |
\end{codeexample} |
| 136 |
|
| 137 |
When a key is handled, instead of executing some code, the key can also cause |
| 138 |
further keys to be executed. Such keys will be called \emph{styles}. A style |
| 139 |
is, in essence, just a key list that should be executed whenever the style is |
| 140 |
executed. Here is an example: |
| 141 |
% |
| 142 |
\begin{codeexample}[] |
| 143 |
\pgfkeys{/a/.code=(a:#1)} |
| 144 |
\pgfkeys{/b/.code=(b:#1)} |
| 145 |
\pgfkeys{/my style/.style={/a=foo,/b=bar,/a=#1}} |
| 146 |
\pgfkeys{/my style=wow} |
| 147 |
\end{codeexample} |
| 148 |
% |
| 149 |
As the above example shows, styles can also be parameterized, just like the |
| 150 |
normal code keys. |
| 151 |
|
| 152 |
As a typical use of styles, suppose we wish to set up the key |/tikz| so that |
| 153 |
it will change the default path to |/tikz|. This can be achieved as follows: |
| 154 |
% |
| 155 |
\begin{codeexample}[code only] |
| 156 |
\pgfkeys{/tikz/.style=/tikz/.cd} |
| 157 |
\pgfkeys{tikz,line width=1cm,draw=red} |
| 158 |
\end{codeexample} |
| 159 |
|
| 160 |
Note that when |\pgfkeys| is executed, the default path is set to~|/|. This |
| 161 |
means that the first |tikz| will be completed to |/tikz|. Then |/tikz| is a |
| 162 |
style and, thus, replaced by |/tikz/.cd|, which changes the default path to |
| 163 |
|/tikz|. Thus, the |line width| is correctly prefixed with |/tikz|. |
| 164 |
|
| 165 |
|
| 166 |
\subsection{The Key Tree} |
| 167 |
|
| 168 |
The |pgfkeys| package organizes keys in a so-called \emph{key tree}. This tree |
| 169 |
will be familiar to anyone who has used a Unix operating system: A key is |
| 170 |
addressed by a path, which consists of different parts separated by slashes. A |
| 171 |
typical key might be |/tikz/line width| or just |/tikz| or something more |
| 172 |
complicated like |/tikz/cs/x/.store in|. |
| 173 |
|
| 174 |
Let us fix some further terminology: Given a key like |/a/b/c|, we call the |
| 175 |
part leading up the last slash (|/a/b|) the \emph{path} of the key. We call |
| 176 |
everything after the last slash (|c|) the \emph{name} of the key (in a file |
| 177 |
system this would be the file name). |
| 178 |
|
| 179 |
We do not always wish to specify keys completely. Instead, we usually specify |
| 180 |
only part of a key (typically only the name) and the \emph{default path} is |
| 181 |
then added to the key at the front. So, when the default path is |/tikz| and |
| 182 |
you refer to the (partial) key |line width|, the actual key that is used is |
| 183 |
|/tikz/line width|. There is a simple rule for deciding whether a key is a |
| 184 |
partial key or a full key: If it starts with a slash, then it is a full key and |
| 185 |
it is not modified; if it does not start with a slash, then the default path is |
| 186 |
automatically prefixed. |
| 187 |
|
| 188 |
\emph{Remark:} The above rule is actually a definition, hence the corresponding |
| 189 |
sufficiency conditions hold. That is, if it is a full key, then it starts with |
| 190 |
a slash; if it is a partial key, then it does not start with a slash. Moreover, |
| 191 |
a path always starts with a slash. |
| 192 |
|
| 193 |
Note that the default path is not the same as a search path. In particular, the |
| 194 |
default path is just a single path. When a partial key is given, only this |
| 195 |
single default path is prefixed; |pgfkeys| does not try to look up the key in |
| 196 |
different parts of a search path. It is, however, possible to emulate search |
| 197 |
paths, but a much more complicated mechanism must be used. |
| 198 |
|
| 199 |
When you set keys (to be explained in a moment), you can freely mix partial and |
| 200 |
full keys and you can change the default path. This makes it possible to |
| 201 |
temporarily use keys from another part of the key tree (this turns out to be a |
| 202 |
very useful feature). |
| 203 |
|
| 204 |
Each key (may) store some \emph{tokens} and there exist commands, described |
| 205 |
below, for setting, getting, and changing the tokens stored in a key. However, |
| 206 |
you will only very seldom use these commands directly. Rather, the standard way |
| 207 |
of using keys is the |\pgfkeys| command or some command that uses it internally |
| 208 |
like, say, |\tikzset|. So, you may wish to skip the following commands and |
| 209 |
continue with the next subsection. |
| 210 |
|
| 211 |
\begin{command}{\pgfkeyssetvalue\marg{full key}\marg{token text}} |
| 212 |
Stores the \meta{token text} in the \meta{full key}. The \meta{full key} |
| 213 |
may not be a partial key, so no default-path-adding is done. The |
| 214 |
\meta{token text} can be arbitrary tokens and may even contain things like |
| 215 |
|#| or unbalanced \TeX-ifs. |
| 216 |
% |
| 217 |
\begin{codeexample}[] |
| 218 |
\pgfkeyssetvalue{/my family/my key}{Hello, world!} |
| 219 |
\pgfkeysvalueof{/my family/my key} |
| 220 |
\end{codeexample} |
| 221 |
|
| 222 |
The setting of a key is always local to the current \TeX\ group. |
| 223 |
\end{command} |
| 224 |
|
| 225 |
\begin{command}{\pgfkeyssetevalue\marg{full key}\marg{token text}} |
| 226 |
The |\edef| version of |\pgfkeyssetvalue|. |
| 227 |
\end{command} |
| 228 |
|
| 229 |
\begin{command}{\pgfkeyslet\marg{full key}\marg{macro}} |
| 230 |
Performs a |\let| statement so the \meta{full key} points to the contents |
| 231 |
of \meta{macro}. |
| 232 |
% |
| 233 |
\begin{codeexample}[] |
| 234 |
\def\helloworld{Hello, world!} |
| 235 |
\pgfkeyslet{/my family/my key}{\helloworld} |
| 236 |
\pgfkeysvalueof{/my family/my key} |
| 237 |
\end{codeexample} |
| 238 |
% |
| 239 |
You should never let a key be equal to |\relax|. Such a key may or may not |
| 240 |
be indistinguishable from an undefined key. |
| 241 |
\end{command} |
| 242 |
|
| 243 |
\begin{command}{\pgfkeysgetvalue\marg{full key}\marg{macro}} |
| 244 |
Retrieves the tokens stored in the \meta{full key} and lets \meta{macro} be |
| 245 |
equal to these tokens. If the key has not been set, the \meta{macro} will |
| 246 |
be equal to |\relax|. |
| 247 |
% |
| 248 |
\begin{codeexample}[] |
| 249 |
\pgfkeyssetvalue{/my family/my key}{Hello, world!} |
| 250 |
\pgfkeysgetvalue{/my family/my key}{\helloworld} |
| 251 |
\helloworld |
| 252 |
\end{codeexample} |
| 253 |
% |
| 254 |
\end{command} |
| 255 |
|
| 256 |
\begin{command}{\pgfkeysvalueof\marg{full key}} |
| 257 |
Inserts the value stored in \meta{full key} at the current position into the |
| 258 |
text. It expands to an alias of the primitive |\relax| if the key is undefined. |
| 259 |
% |
| 260 |
\begin{codeexample}[] |
| 261 |
\pgfkeyssetvalue{/my family/my key}{Hello, world!} |
| 262 |
\pgfkeysvalueof{/my family/my key} |
| 263 |
\end{codeexample} |
| 264 |
% |
| 265 |
\emph{Note:} It is an error to assign to the result of the expansion of |
| 266 |
|\pgfkeysvalueof|, not only semantically but in recent versions of \pgfname\ |
| 267 |
also logically. To set the value of a key \emph{always} use the appropriate |
| 268 |
interfaces, e.g.\ |\pgfkeyssetvalue|. |
| 269 |
\end{command} |
| 270 |
|
| 271 |
\begin{command}{\pgfkeysifdefined\marg{full key}\marg{if}\marg{else}} |
| 272 |
Checks whether this key was previously set using either |\pgfkeyssetvalue| |
| 273 |
or |\pgfkeyslet|. If so, the code in \meta{if} is executed, otherwise the |
| 274 |
code in \meta{else}. |
| 275 |
% |
| 276 |
\begin{codeexample}[] |
| 277 |
\pgfkeyssetvalue{/my family/my key}{Hello, world!} |
| 278 |
\pgfkeysifdefined{/my family/my key}{yes}{no} |
| 279 |
\end{codeexample} |
| 280 |
% |
| 281 |
\end{command} |
| 282 |
|
| 283 |
|
| 284 |
\subsection{Setting Keys} |
| 285 |
|
| 286 |
Setting keys is done using a powerful command called |\pgfkeys|. This command |
| 287 |
takes a list of so-called \emph{key--value pairs}. These are pairs of the form |
| 288 |
\meta{key}|=|\meta{value}. The principal idea is the following: For each pair |
| 289 |
in the list, some \emph{action} is taken. This action can be one of the |
| 290 |
following: |
| 291 |
% |
| 292 |
\begin{enumerate} |
| 293 |
\item A command is executed whose argument(s) are \meta{value}. This |
| 294 |
command is stored in a special subkey of \meta{key}. |
| 295 |
\item The \meta{value} is stored in the \meta{key} itself. |
| 296 |
\item If the key's name (the part after the last slash) is a known |
| 297 |
\emph{handler}, then this handler will take care of the key. |
| 298 |
\item If the key is totally unknown, one of several possible \emph{unknown |
| 299 |
key handlers} is called. |
| 300 |
\end{enumerate} |
| 301 |
|
| 302 |
Additionally, if the \meta{value} is missing, a default value may or may not be |
| 303 |
substituted. Before we plunge into all the details, let us have a quick look at |
| 304 |
the command itself. |
| 305 |
|
| 306 |
\begin{command}{\pgfkeys\marg{key list}} |
| 307 |
The \meta{key list} should be a list of key--value pairs, separated by |
| 308 |
commas. A key--value pair can have the following two forms: |
| 309 |
\meta{key}|=|\meta{value} or just \meta{key}. Any spaces around the |
| 310 |
\meta{key} or around the \meta{value} are removed. It is permissible to |
| 311 |
surround both the \meta{key} or the \meta{value} in curly braces, which are |
| 312 |
also removed. Especially putting the \meta{value} in curly braces needs to |
| 313 |
be done quite often, namely whenever the \meta{value} contains an |
| 314 |
equal-sign or a comma. |
| 315 |
|
| 316 |
The key--value pairs in the list are handled in the order they appear. How |
| 317 |
this handling is done, exactly, is described in the rest of this section. |
| 318 |
|
| 319 |
If a \meta{key} is a partial key, the current value of the default path is |
| 320 |
prefixed to the \meta{key} and this ``upgraded'' key is then used. The |
| 321 |
default path is just the root path |/| when the first key is handled, but |
| 322 |
it may change later on. At the end of the command, the default path is |
| 323 |
reset to the value it had before this command was executed. |
| 324 |
|
| 325 |
Calls of this command may be nested. Thus, it is permissible to call |
| 326 |
|\pgfkeys| inside the code that is executed for a key. Since the default |
| 327 |
path is restored after a call of |\pgfkeys|, the default path will not |
| 328 |
change when you call |\pgfkeys| while executing code for a key (which is |
| 329 |
exactly what you want). |
| 330 |
\end{command} |
| 331 |
|
| 332 |
\begin{command}{\pgfqkeys\marg{default path}\marg{key list}} |
| 333 |
This command has the same effect as |\pgfkeys{|\meta{default |
| 334 |
path}|/.cd,|\meta{key list}|}|, it is only marginally quicker. This command |
| 335 |
should not be used in user code, but rather in commands like |\tikzset| or |
| 336 |
|\pgfset| that get called very often. |
| 337 |
\end{command} |
| 338 |
|
| 339 |
\begin{command}{\pgfkeysalso\marg{key list}} |
| 340 |
This command has exactly the same effect as |\pgfkeys|, only the default |
| 341 |
path is not modified before or after the keys are being set. This command |
| 342 |
is mainly intended to be called by the code that is being processed for a |
| 343 |
key. |
| 344 |
\end{command} |
| 345 |
|
| 346 |
\begin{command}{\pgfqkeysalso\marg{default path}\marg{key list}} |
| 347 |
This command has the same effect as |\pgfkeysalso{|\meta{default |
| 348 |
path}|/.cd,|\meta{key list}|}|, it is only quicker. Changing the default |
| 349 |
path inside a |\pgfkeyalso| is dangerous, so use with care. A rather safe |
| 350 |
place to call this command is at the beginning of a \TeX\ group. |
| 351 |
\end{command} |
| 352 |
|
| 353 |
|
| 354 |
\subsubsection{First Char Syntax Detection} |
| 355 |
\label{sec:pgf:first:char:syntax} |
| 356 |
|
| 357 |
Usually, keys are of the form \meta{key}|=|\meta{value} and how such keys are |
| 358 |
handled is discussed in the rest of this section. However, it is also possible |
| 359 |
to setup a different syntax for certain parts of the input to |\pgfkeys|. Since |
| 360 |
this is a rather advanced option, most readers may wish to skip the following |
| 361 |
discussion upon first reading; it is discussed here because this special syntax |
| 362 |
detection is the very first thing that is done when a key is processed, before |
| 363 |
any of the following operations are performed. |
| 364 |
|
| 365 |
The |\pgfkeys| command and its variants decompose their input into a list of |
| 366 |
\meta{string}s that are separated by commas. By default, each such |
| 367 |
\meta{string} must either have the form \meta{key}|=|\meta{value} or of the |
| 368 |
form \meta{key} with the value-part missing. However, you might wish to |
| 369 |
interpret some of these strings differently. For instance, when a \meta{string} |
| 370 |
has the form |"|\meta{text}|"|, you might wish the \meta{string} to be |
| 371 |
interpreted as if one had written |label text={|\meta{text}|}|. Then, people |
| 372 |
could write |
| 373 |
% |
| 374 |
\begin{codeexample}[code only] |
| 375 |
\myset{red, "main valve", thick} |
| 376 |
\end{codeexample} |
| 377 |
% |
| 378 |
instead of the more cumbersome |
| 379 |
% |
| 380 |
\begin{codeexample}[code only] |
| 381 |
\myset{red, label text=main valve, thick} |
| 382 |
\end{codeexample} |
| 383 |
% |
| 384 |
An example where such a syntax reinterpretation is done is the |quotes| |
| 385 |
library, which allows you to write things like |
| 386 |
% |
| 387 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs,quotes}}] |
| 388 |
\tikz \graph { a ->["1" red] b ->["0"] c }; |
| 389 |
\end{codeexample} |
| 390 |
% |
| 391 |
\noindent instead of the somewhat longer |
| 392 |
% |
| 393 |
\begin{codeexample}[preamble={\usetikzlibrary{graphs}}] |
| 394 |
\tikz \graph { a ->[edge node={node[red,auto]{1}}] b ->[edge label=0] c }; |
| 395 |
\end{codeexample} |
| 396 |
|
| 397 |
In order to detect whether a \meta{string} has a special syntax, you can |
| 398 |
request that the \emph{first character} of \meta{string} is analysed by the key |
| 399 |
parser. If this first character matches a character that has been flagged as a |
| 400 |
special character, the \meta{string} is not interpreted as a usual key--value |
| 401 |
pair. Instead, \meta{string} is passed as a parameter to a special macro that |
| 402 |
should take care of the \meta{string}. After this macro has finished, the |
| 403 |
parsing continues with the \meta{next string} in the list. |
| 404 |
|
| 405 |
In order to setup a special syntax handling for \meta{strings} that begin with |
| 406 |
a certain character, two things need to be done: |
| 407 |
% |
| 408 |
\begin{enumerate} |
| 409 |
\item First, the whole |first char syntax| detection must be ``switched on'', |
| 410 |
since, by default, it is turned off for efficiency reasons (the |
| 411 |
overhead is rather small, however). This is done by setting the |
| 412 |
following key: |
| 413 |
% |
| 414 |
\begin{key}{/handlers/first char syntax=\opt{\meta{true or false}} (default true, initially false)} |
| 415 |
\end{key} |
| 416 |
\item Second, in order to handle strings starting with a certain |
| 417 |
\meta{character} in a special way, you need to store a macro in the |
| 418 |
following key: |
| 419 |
% |
| 420 |
\begin{key}{/handlers/first char syntax/\meta{meaning of character}} |
| 421 |
The \meta{meaning of character} should be the text that \TeX's |
| 422 |
command |\meaning| returns for a macro that has been |\let| to the |
| 423 |
\meta{character}. For instance, when strings starting with |"| |
| 424 |
should be treated in a special way, the \meta{meaning of character} |
| 425 |
would be the string |the character "| since this is what \TeX\ |
| 426 |
writes when you say |
| 427 |
% |
| 428 |
\begin{codeexample}[] |
| 429 |
\let\mycharacter=" |
| 430 |
\meaning\mycharacter |
| 431 |
\end{codeexample} |
| 432 |
% |
| 433 |
Now, the key |/handlers/first char syntax/|\meta{meaning of |
| 434 |
character} should be setup (using |\pgfkeyssetvalue| or using the |
| 435 |
|.initial| handler) to store a \meta{macro name}. |
| 436 |
|
| 437 |
If this is the case and if \meta{string} starts with the |
| 438 |
\meta{character} (blanks at the beginning of \meta{string} are |
| 439 |
deleted prior to this test), then \meta{macro name} is called with |
| 440 |
\meta{string} as its argument. |
| 441 |
\end{key} |
| 442 |
\end{enumerate} |
| 443 |
|
| 444 |
Let us now have a look at an example. We install two handlers, one for strings |
| 445 |
starting with |"| and one for strings starting with |<|. |
| 446 |
% |
| 447 |
\begin{codeexample}[] |
| 448 |
\pgfkeys{ |
| 449 |
/handlers/first char syntax=true, |
| 450 |
/handlers/first char syntax/the character "/.initial=\myquotemacro, |
| 451 |
/handlers/first char syntax/the character </.initial=\mypointedmacro, |
| 452 |
} |
| 453 |
|
| 454 |
\def\myquotemacro#1{Quoted: #1. } |
| 455 |
\def\mypointedmacro#1{Pointed: #1. } |
| 456 |
|
| 457 |
\ttfamily \pgfkeys{"foo", <bar>} |
| 458 |
\end{codeexample} |
| 459 |
|
| 460 |
Naturally, in the above examples, the two handling macros did not do something |
| 461 |
particularly exciting. In the next example, we setup a more elaborate macro |
| 462 |
that mimics a small part the behavior of the |quotes| library, only for single |
| 463 |
quotes: |
| 464 |
% |
| 465 |
\begin{codeexample}[] |
| 466 |
\pgfkeys{ |
| 467 |
/handlers/first char syntax=true, |
| 468 |
/handlers/first char syntax/the character '/.initial=\mysinglequotemacro |
| 469 |
} |
| 470 |
|
| 471 |
\def\mysinglequotemacro#1{\pgfkeysalso{label={#1}}} |
| 472 |
|
| 473 |
\tikz \node [circle, 'foo', draw] {bar}; |
| 474 |
\end{codeexample} |
| 475 |
|
| 476 |
Note that in the above example, the macro |\mysinglequotemacro| gets passed the |
| 477 |
complete string, including the single quotes. It is the job of the macro to get |
| 478 |
rid of them, if this is necessary. |
| 479 |
|
| 480 |
The first char syntax detection allows you to perform rather powerful |
| 481 |
transformations on the syntax of keys -- provided you can ``pin down'' the |
| 482 |
syntax on the first character. In the following example, you can write |
| 483 |
expressions in parentheses in front of a key--value pair and the pair will only |
| 484 |
be executed when the expression evaluates to true: |
| 485 |
% |
| 486 |
\begin{codeexample}[] |
| 487 |
\pgfkeys{ |
| 488 |
/handlers/first char syntax=true, |
| 489 |
/handlers/first char syntax/the character (/.initial=\myparamacro |
| 490 |
} |
| 491 |
|
| 492 |
\def\myparamacro#1{\myparaparser#1\someendtext} |
| 493 |
\def\myparaparser(#1)#2\someendtext{ |
| 494 |
\pgfmathparse{#1} |
| 495 |
\ifx\pgfmathresult\onetext |
| 496 |
\pgfkeysalso{#2} |
| 497 |
\fi |
| 498 |
} |
| 499 |
\def\onetext{1} |
| 500 |
|
| 501 |
\foreach \i in {1,...,4} |
| 502 |
\tikz \node [draw, thick, rectangle, (pi>\i) circle, (pi>\i*2) draw=red] {x}; |
| 503 |
\end{codeexample} |
| 504 |
|
| 505 |
|
| 506 |
\subsubsection{Default Arguments} |
| 507 |
|
| 508 |
The arguments of the |\pgfkeys| command can either be of the form |
| 509 |
\meta{key}|=|\meta{value} or of the form \meta{key} with the value-part |
| 510 |
missing. In the second case, the |\pgfkeys| will try to provide a \emph{default |
| 511 |
value} for the \meta{value}. If such a default value is defined, it will be |
| 512 |
used as if you had written \meta{key}|=|\meta{default value}. |
| 513 |
|
| 514 |
In the following, the details of how default values are determined is |
| 515 |
described; however, you should normally use the handlers |/.default| and |
| 516 |
|/.value required| as described in Section~\ref{section-default-handlers} and |
| 517 |
you may wish to skip the following details. |
| 518 |
|
| 519 |
When |\pgfkeys| encounters a \meta{key} without an equal-sign, the following |
| 520 |
happens: |
| 521 |
% |
| 522 |
\begin{enumerate} |
| 523 |
\item The input is replaced by \meta{key}|=\pgfkeysnovalue|. In particular, |
| 524 |
the commands |\pgfkeys{my key}| and |
| 525 |
% FIXME: there is a bug in the pretty printer ... fix it and get rid of '||' here: |
| 526 |
|\pgfkeys{my key=||\pgfkeysnovalue}| have exactly the same effect and |
| 527 |
you can ``simulate'' a missing value by providing the value |
| 528 |
|\pgfkeysnovalue|, which is sometimes useful. |
| 529 |
\item If the \meta{value} is |\pgfkeysnovalue|, then it is checked whether |
| 530 |
the subkey \meta{key}|/.@def| exists. For instance, if you write |
| 531 |
|\pgfkeys{/my key}|, then it is checked whether the key |/my key/.@def| |
| 532 |
exists. |
| 533 |
\item If the key \meta{key}|/.@def| exists, then the tokens stored in this |
| 534 |
key are used as \meta{value}. |
| 535 |
\item If the key does not exist, then |\pgfkeysnovalue| is used as the |
| 536 |
\meta{value}. |
| 537 |
\item At the end, if the \meta{value} is now equal to |
| 538 |
|\pgfkeysvaluerequired|, then the code (or something fairly equivalent) |
| 539 |
|\pgfkeys{/errors/value required=|\meta{key}|{}}| is executed. Thus, by |
| 540 |
changing this key you can change the error message that is printed or |
| 541 |
you can handle the missing value in some other way. |
| 542 |
\end{enumerate} |
| 543 |
|
| 544 |
|
| 545 |
\subsubsection{Keys That Execute Commands} |
| 546 |
\label{section-key-code} |
| 547 |
|
| 548 |
After the transformation process described in the previous subsection, we |
| 549 |
arrive at a key of the form \meta{key}=\meta{value}, where \meta{key} is a full |
| 550 |
key. Different things can now happen, but always the macro |\pgfkeyscurrentkey| |
| 551 |
will have been set up to expand to the text of the \meta{key} that is currently |
| 552 |
being processed. |
| 553 |
|
| 554 |
The first things that is tested is whether the key \meta{key}|/.@cmd| exists. |
| 555 |
If this is the case, then it is assumed that this key stores the code of a |
| 556 |
macro and this macro is executed. The argument of this macro is \meta{value} |
| 557 |
directly followed by |\pgfeov|, which stands for ``end of value''. The |
| 558 |
\meta{value} is not surrounded by braces. After this code has been executed, |
| 559 |
|\pgfkeys| continues with the next key in the \meta{key list}. |
| 560 |
|
| 561 |
It may seem quite peculiar that the macro stored in the key \meta{key}|/.@cmd| |
| 562 |
is not simply executed with the argument |{|\meta{value}|}|. However, the |
| 563 |
approach taken in the |pgfkeys| packages allows for more flexibility. For |
| 564 |
instance, assume that you have a key that expects a \meta{value} of the form |
| 565 |
``\meta{text}|+|\meta{more text}'' and wishes to store \meta{text} and |
| 566 |
\meta{more text} in two different macros. This can be achieved as follows: |
| 567 |
% |
| 568 |
\begin{codeexample}[preamble={\usepackage{shortvrb} \MakeShortVerb{\|}}] |
| 569 |
\def\mystore#1+#2\pgfeov{\def\a{#1}\def\b{#2}} |
| 570 |
\pgfkeyslet{/my key/.@cmd}{\mystore} |
| 571 |
\pgfkeys{/my key=hello+world} |
| 572 |
|
| 573 |
|\a| is `\a', |\b| is `\b'. |
| 574 |
\end{codeexample} |
| 575 |
|
| 576 |
Naturally, defining the code to be stored in a key in the above manner is too |
| 577 |
awkward. The following commands simplify things a bit, but the usual manner of |
| 578 |
setting up code for a key is to use one of the handlers described in |
| 579 |
Section~\ref{section-code-handlers}. |
| 580 |
|
| 581 |
\begin{command}{\pgfkeysdef\marg{key}\marg{code}} |
| 582 |
This command temporarily defines a \TeX-macro with the argument list |
| 583 |
|#1\pgfeov| and then lets \meta{key}|/.@cmd| be equal to this macro. The |
| 584 |
net effect of all this is that you have then set up code for the key |
| 585 |
\meta{key} so that when you write |\pgfkeys{|\meta{key}|=|\meta{value}|}|, |
| 586 |
then the \meta{code} is executed with all occurrences of |#1| in |
| 587 |
\meta{code} being replaced by \meta{value}. (This behavior is quite |
| 588 |
similar to the |\define@key| command of |keyval| and |xkeyval|). |
| 589 |
% |
| 590 |
\begin{codeexample}[] |
| 591 |
\pgfkeysdef{/my key}{#1, #1.} |
| 592 |
\pgfkeys{/my key=hello} |
| 593 |
\end{codeexample} |
| 594 |
\end{command} |
| 595 |
|
| 596 |
\begin{command}{\pgfkeysedef\marg{key}\marg{code}} |
| 597 |
This command works like |\pgfkeysdef|, but it uses |\edef| rather than |
| 598 |
|\def| when defining the key macro. If you do not know the difference |
| 599 |
between the two, then you will not need this command; and if you know the |
| 600 |
difference, then you will know when you need this command. |
| 601 |
\end{command} |
| 602 |
|
| 603 |
\begin{command}{\pgfkeysdefnargs\marg{key}\marg{argument count}\marg{code}} |
| 604 |
This command works like |\pgfkeysdef|, but it allows you to provide an |
| 605 |
arbitrary \meta{argument count} between $0$ and $9$ (inclusive). |
| 606 |
% |
| 607 |
\begin{codeexample}[preamble={\usepackage{shortvrb} \MakeShortVerb{\|}}] |
| 608 |
\pgfkeysdefnargs{/my key}{2}{\def\a{#1}\def\b{#2}} |
| 609 |
\pgfkeys{/my key= |
| 610 |
{hello} |
| 611 |
{world}} |
| 612 |
|
| 613 |
|\a| is `\a', |\b| is `\b'. |
| 614 |
\end{codeexample} |
| 615 |
% |
| 616 |
The resulting key will expect exactly \marg{argument count} arguments. |
| 617 |
\end{command} |
| 618 |
% |
| 619 |
\begin{command}{\pgfkeysedefnargs\marg{key}\marg{argument count}\marg{code}} |
| 620 |
The |\edef| version of |\pgfkeysdefnargs|. |
| 621 |
\end{command} |
| 622 |
|
| 623 |
\begin{command}{\pgfkeysdefargs\marg{key}\marg{argument pattern}\marg{code}} |
| 624 |
This command works like |\pgfkeysdefnargs|, but it allows you to provide an |
| 625 |
arbitrary \meta{argument pattern} rather than just a number of arguments. |
| 626 |
% |
| 627 |
\begin{codeexample}[preamble={\usepackage{shortvrb} \MakeShortVerb{\|}}] |
| 628 |
\pgfkeysdefargs{/my key}{#1+#2}{\def\a{#1}\def\b{#2}} |
| 629 |
\pgfkeys{/my key=hello+world} |
| 630 |
|
| 631 |
|\a| is `\a', |\b| is `\b'. |
| 632 |
\end{codeexample} |
| 633 |
% |
| 634 |
Note that |\pgfkeysdefnargs| is \emph{better} when it comes to simple |
| 635 |
argument \emph{counts}\footnote{When the resulting keys are used, the |
| 636 |
\texttt{defnargs} variant allows spaces between arguments whereas the |
| 637 |
\texttt{defargs} variant does not; it considers the spaces as part of the |
| 638 |
argument.}. |
| 639 |
\end{command} |
| 640 |
|
| 641 |
\begin{command}{\pgfkeysedefargs\marg{key}\marg{argument pattern}\marg{code}} |
| 642 |
The |\edef| version of |\pgfkeysdefargs|. |
| 643 |
\end{command} |
| 644 |
|
| 645 |
|
| 646 |
\subsubsection{Keys That Store Values} |
| 647 |
|
| 648 |
Let us continue with what happens when |\pgfkeys| processes the current key and |
| 649 |
the subkey \meta{key}|/.@cmd| is not defined. Then it is checked whether the |
| 650 |
\meta{key} itself exists (has been previously assigned a value using, for |
| 651 |
instance, |\pgfkeyssetvalue|). In this case, the tokens stored in \meta{key} |
| 652 |
are replaced by \meta{value} and |\pgfkeys| proceeds with the next key in the |
| 653 |
\meta{key list}. |
| 654 |
|
| 655 |
|
| 656 |
\subsubsection{Keys That Are Handled} |
| 657 |
\label{section-key-handlers} |
| 658 |
|
| 659 |
If neither the \meta{key} itself nor the subkey \meta{key}|/.@cmd| are defined, |
| 660 |
then the \meta{key} cannot be processed ``all by itself''. Rather, a |
| 661 |
\meta{handler} is needed for this key. Most of the power of |pgfkeys| comes |
| 662 |
from the proper use of such handlers. |
| 663 |
|
| 664 |
Recall that the \meta{key} is always a full key (if it was not originally, it |
| 665 |
has already been upgraded at this point to a full key). It decomposed into two |
| 666 |
parts: |
| 667 |
|
| 668 |
\begin{enumerate} |
| 669 |
\item The \meta{path} of \meta{key} (everything before the last slash) is |
| 670 |
stored in the macro |\pgfkeyscurrentpath|. |
| 671 |
\item The \meta{name} of \meta{key} (everything after the last slash) is |
| 672 |
stored in the macro |\pgfkeyscurrentname|. |
| 673 |
|
| 674 |
It is recommended (but not necessary) that the name of a handler starts |
| 675 |
with a dot (but not with |.@|), so that they are easy to detect for the |
| 676 |
reader. |
| 677 |
\end{enumerate} |
| 678 |
|
| 679 |
(For efficiency reasons, these two macros are only set up at this point; so |
| 680 |
when code is executed for a key in the ``usual'' manner then these macros are |
| 681 |
not set up.) |
| 682 |
|
| 683 |
The |\pgfkeys| command now checks whether the key |
| 684 |
|/handlers/|\meta{name}|/.@cmd| exists. If so, it should store a command and |
| 685 |
this command is executed exactly in the same manner as described in |
| 686 |
Section~\ref{section-key-code}. Thus, this code gets the \meta{value} that was |
| 687 |
originally intended for \meta{key} as its argument, followed by |\pgfeov|. It |
| 688 |
is the job of the handlers to do something useful with the \meta{value}. |
| 689 |
|
| 690 |
For an example, let us write a handler that will output the value stored in a |
| 691 |
key to the log file. We call this handler |/.print to log|. The idea is that |
| 692 |
when someone tries to use the key |/my key/.print to log|, then this key will |
| 693 |
not be defined and the handler gets executed. The handler will then have access |
| 694 |
to the path-part of the key, which is |/my key|, via the macro |
| 695 |
|\pgfkeyscurrentpath|. It can then lookup which value is stored in this key and |
| 696 |
print it. |
| 697 |
% |
| 698 |
\begin{codeexample}[code only] |
| 699 |
\pgfkeysdef{/handlers/.print to log} |
| 700 |
{% |
| 701 |
\pgfkeysgetvalue{\pgfkeyscurrentpath}{\temp} |
| 702 |
\writetolog{\temp} |
| 703 |
} |
| 704 |
\pgfkeyssetvalue{/my key}{Hi!} |
| 705 |
... |
| 706 |
\pgfkeys{/my key/.print to log} |
| 707 |
\end{codeexample} |
| 708 |
% |
| 709 |
The above code will print |Hi!| in the log, provided the macro |\writetolog| is |
| 710 |
set up appropriately. |
| 711 |
|
| 712 |
For a more interesting handler, let us program a handler that will set up a key |
| 713 |
so that when the key is used, some code is executed. This code is given as |
| 714 |
\meta{value}. All the handler must do is to call |\pgfkeysdef| for the path of |
| 715 |
the key (which misses the handler's name) and assign the parameter value to it. |
| 716 |
% |
| 717 |
\begin{codeexample}[] |
| 718 |
\pgfkeysdef{/handlers/.my code}{\pgfkeysdef{\pgfkeyscurrentpath}{#1}} |
| 719 |
\pgfkeys{/my key/.my code=(#1)} |
| 720 |
\pgfkeys{/my key=hallo} |
| 721 |
\end{codeexample} |
| 722 |
|
| 723 |
There are some parameters for handled keys which prove to be useful in some |
| 724 |
(possibly rare) special cases: |
| 725 |
% |
| 726 |
\begin{key}{/handler config=\mchoice{all,only existing,full or existing} (initially all)} |
| 727 |
Changes the initial configuration how key handlers will be used. |
| 728 |
|
| 729 |
This configuration is for advanced users and rarely necessary. |
| 730 |
% |
| 731 |
\begin{description} |
| 732 |
\item[\texttt{all}] The preconfigured setting |all| works as described |
| 733 |
above and imposes no restriction on the key setting process. |
| 734 |
\item[\texttt{only existing}] The value |only existing| modifies the |
| 735 |
algorithm for handled keys as follows: a handler \meta{key |
| 736 |
name}|/.|\meta{handler} will be executed only if \meta{key name} is |
| 737 |
either a key which stores its value directly or a command key for |
| 738 |
which |/.@cmd| exists. If \meta{key name} does \emph{not} exist |
| 739 |
already, the complete string \meta{key name}|/.|\meta{handler} is |
| 740 |
considered to be an unknown key and the procedure described in the |
| 741 |
next section applies (for the path of \meta{key name}). |
| 742 |
% |
| 743 |
\begin{codeexample}[] |
| 744 |
% Define a test key and error handlers: |
| 745 |
\pgfkeys{/the/key/.code={Initial definition. }} |
| 746 |
\pgfkeys{/handlers/.unknown/.code={Unknown key `\pgfkeyscurrentkey'. }} |
| 747 |
|
| 748 |
% calling the test key yields 'Initial definition. ': |
| 749 |
\pgfkeys{/the/key} |
| 750 |
|
| 751 |
% Change configuration: |
| 752 |
\pgfkeys{/handler config=only existing} |
| 753 |
|
| 754 |
% allowed: key *re*-definition: |
| 755 |
\pgfkeys{/the/key/.code={Re-Definition. }} |
| 756 |
% calling the key yields 'Re-Definition. ': |
| 757 |
\pgfkeys{/the/key} |
| 758 |
|
| 759 |
% not allowed: definition of new keys: |
| 760 |
% this checks for '/the/other key/.unknown' |
| 761 |
% and '/handlers/.unknown' |
| 762 |
% and yields finally |
| 763 |
% 'Unknown key `/the/other key/.code`' |
| 764 |
\pgfkeys{/the/other key/.code={New definition. }} |
| 765 |
\end{codeexample} |
| 766 |
% |
| 767 |
It is necessary to exclude some key handlers from this procedure. |
| 768 |
Altogether, the detailed procedure is as follows: |
| 769 |
% |
| 770 |
\begin{enumerate} |
| 771 |
\item If a handled key like |/a path/a key/.a handler=value| is |
| 772 |
encountered, it is checked whether the handler should be |
| 773 |
invoked. This is the case if |
| 774 |
% |
| 775 |
\begin{itemize} |
| 776 |
\item An exception from |only existing| for this key |
| 777 |
exists (see below), |
| 778 |
\item The key |/a path/a key| exists already -- either |
| 779 |
directly as storage key or with the |.@cmd| suffix. |
| 780 |
\end{itemize} |
| 781 |
% |
| 782 |
\item If the check passes, everything works as before. |
| 783 |
\item If the check fails, the complete key will be considered |
| 784 |
to be unknown. In that case, the handling of unknown keys |
| 785 |
as described in the next section applies. There, the |
| 786 |
current key path will be set to |/a path| and the current |
| 787 |
key's name to |key/.a handler|. |
| 788 |
\end{enumerate} |
| 789 |
|
| 790 |
A consequence of this configuration is to provide more meaningful |
| 791 |
processing of handled keys if a search path for keys is in effect, |
| 792 |
see section~\ref{sec:pgf:unknown:keys} for an example. |
| 793 |
\item[\texttt{full or existing}] Finally, the choice |full or existing| |
| 794 |
is a variant of |only existing|: it works in the same way for keys |
| 795 |
which do not have a full key path. For example, the style |
| 796 |
|
| 797 |
|\pgfkeys{/my path/.cd,key/.style={|$\dotsc$|}}| |
| 798 |
|
| 799 |
can only be redefined: it doesn't have a full path, so the |
| 800 |
|only existing| mechanism applies. But the style |
| 801 |
|
| 802 |
|\pgfkeys{/my path/key/.style={|$\dotsc$|}}| |
| 803 |
|
| 804 |
will still work. This allows users to override the |only existing| |
| 805 |
feature if they know what they're doing (and provide full key |
| 806 |
paths). |
| 807 |
\end{description} |
| 808 |
\end{key} |
| 809 |
|
| 810 |
\begin{key}{/handler config/only existing/add exception=\marg{key handler name}} |
| 811 |
Allows to add exceptions to the |/handler config=only existing| feature. |
| 812 |
Initially exceptions for the key handlers |/.cd|, |/.try|, |/.retry|, |
| 813 |
|/.lastretry| and |/.unknown| are defined. The value \marg{key handler |
| 814 |
name} should be the name of a key handler. |
| 815 |
\end{key} |
| 816 |
|
| 817 |
|
| 818 |
\subsubsection{Keys That Are Unknown} |
| 819 |
\label{sec:pgf:unknown:keys} |
| 820 |
|
| 821 |
For some keys, neither the key, nor its |.@cmd| subkey nor a handler is |
| 822 |
defined. In this case, it is checked whether the key \meta{current |
| 823 |
path}|/.unknown/.@cmd| exists. Thus, when you try to use the key |
| 824 |
|/tikz/strange|, then it is checked whether |/tikz/.unknown/.@cmd| exists. If |
| 825 |
this key exists (which it does), it is executed. This code can then try to make |
| 826 |
sense of the key. For instance, the handler for \tikzname\ will try to |
| 827 |
interpret the key's name as a color or as an arrow specification or as a |
| 828 |
\pgfname\ option. |
| 829 |
|
| 830 |
You can set up unknown key handlers for your own keys by simply setting the |
| 831 |
code of the key \meta{my path prefix}|/.unknown|. This also allows you to set |
| 832 |
up ``search paths''. The idea is that you would like keys to be searched not |
| 833 |
only in a single default path, but in several. Suppose, for instance, that you |
| 834 |
would like keys to be searched for in |/a|, |/b|, and |/b/c|. We set up a key |
| 835 |
|/my search path| for this: |
| 836 |
% |
| 837 |
\begin{codeexample}[code only] |
| 838 |
\pgfkeys{/my search path/.unknown/.code= |
| 839 |
{% |
| 840 |
\let\searchname=\pgfkeyscurrentname% |
| 841 |
\pgfkeysalso{% |
| 842 |
/a/\searchname/.try=#1, |
| 843 |
/b/\searchname/.retry=#1, |
| 844 |
/b/c/\searchname/.retry=#1% |
| 845 |
}% |
| 846 |
}% |
| 847 |
} |
| 848 |
\pgfkeys{/my search path/.cd,foo,bar} |
| 849 |
\end{codeexample} |
| 850 |
% |
| 851 |
In the above code, |foo| and |bar| will be searched for in the three |
| 852 |
directories |/a|, |/b|, and |/b/c|. Before you start implementing search paths |
| 853 |
using this pattern, consider the |/.search also| handler discussed below. |
| 854 |
|
| 855 |
If the key \meta{current path}|/.unknown/.@cmd| does not exist, the handler |
| 856 |
|/handlers/.unknown| is invoked instead, which is always defined and which |
| 857 |
prints an error message by default. |
| 858 |
|
| 859 |
|
| 860 |
\subsubsection{Search Paths And Handled Keys} |
| 861 |
|
| 862 |
There is one special case which occurs in the search path example above. What |
| 863 |
happens if we want to change a style? For example, |
| 864 |
% |
| 865 |
\begin{codeexample}[code only] |
| 866 |
\pgfkeys{/my search path/.cd,custom/.style={variables}} |
| 867 |
\end{codeexample} |
| 868 |
% |
| 869 |
\noindent could mean a style in |/my search path/|, |/a/|, |/b/| or even |
| 870 |
|/b/c/|! |
| 871 |
|
| 872 |
Due to the rules for handled keys, the answer is |
| 873 |
|/my search path/custom/.style={variables}|. It may be useful to modify this |
| 874 |
default behavior. One useful thing would be to search for \emph{existing} |
| 875 |
styles named |custom| and redefine them. For example, if a style |/b/custom| |
| 876 |
exists, the assignment |custom/.style={variables}| should probably redefine |
| 877 |
|/b/custom| instead of |/my search path/custom|. This can be done using |
| 878 |
|handler config|: |
| 879 |
% |
| 880 |
\begin{codeexample}[] |
| 881 |
\pgfkeys{/my search path/.unknown/.code= |
| 882 |
{% |
| 883 |
\let\searchname=\pgfkeyscurrentname% |
| 884 |
\pgfkeysalso{% |
| 885 |
/a/\searchname/.try=#1, |
| 886 |
/b/\searchname/.retry=#1, |
| 887 |
/b/c/\searchname/.retry=#1% |
| 888 |
}% |
| 889 |
}% |
| 890 |
} |
| 891 |
|
| 892 |
% Let's define /b/custom here: |
| 893 |
\pgfkeys{/b/custom/.code={This is `\pgfkeyscurrentkey'. }} |
| 894 |
|
| 895 |
% Reconfigure treatment of key handlers: |
| 896 |
\pgfkeys{/handler config=only existing} |
| 897 |
|
| 898 |
% The search path procedure will find /b/custom |
| 899 |
% -> leads to This is `/b/custom' |
| 900 |
\pgfkeys{/my search path/.cd,custom} |
| 901 |
|
| 902 |
% Due to the reconfiguration, this will find /b/custom instead of |
| 903 |
% defining /my search path/custom: |
| 904 |
\pgfkeys{/my search path/.cd,custom/.append code={Modified. }} |
| 905 |
|
| 906 |
% So using the search path, we again find /b/custom which |
| 907 |
% leads to This is `/b/custom' Modified |
| 908 |
\pgfkeys{/my search path/.cd,custom} |
| 909 |
\end{codeexample} |
| 910 |
|
| 911 |
A slightly different approach to search paths can be realized using the |
| 912 |
|/.search also| key handler, see below. |
| 913 |
|
| 914 |
|
| 915 |
\subsection{Key Handlers} |
| 916 |
|
| 917 |
We now describe which key handlers are defined by default. You can also define |
| 918 |
new ones as described in Section~\ref{section-key-handlers}. |
| 919 |
|
| 920 |
|
| 921 |
\subsubsection{Handlers for Path Management} |
| 922 |
|
| 923 |
\begin{handler}{{.cd}} |
| 924 |
This handler causes the default path to be set to \meta{key}. Note that the |
| 925 |
default path is reset at the beginning of each call to |\pgfkeys| to be |
| 926 |
equal to~|/|. |
| 927 |
|
| 928 |
\example |\pgfkeys{/tikz/.cd,...}| |
| 929 |
\end{handler} |
| 930 |
|
| 931 |
\begin{handler}{{.is family}} |
| 932 |
\label{section-is family-handler} |
| 933 |
This handler sets up things such that when \meta{key} is executed, then the |
| 934 |
current path is set to \meta{key}. A typical use is the following: |
| 935 |
% |
| 936 |
\begin{codeexample}[code only] |
| 937 |
\pgfkeys{/tikz/.is family} |
| 938 |
\pgfkeys{tikz,line width=1cm} |
| 939 |
\end{codeexample} |
| 940 |
% |
| 941 |
The effect of this handler is the same as if you had written |
| 942 |
\meta{key}|/.style=|\meta{key}|/.cd|, only the code produced by the |
| 943 |
|/.is family| handler is quicker. |
| 944 |
\end{handler} |
| 945 |
|
| 946 |
|
| 947 |
\subsubsection{Setting Defaults} |
| 948 |
\label{section-default-handlers} |
| 949 |
|
| 950 |
\begin{handler}{{.default}|=|\meta{value}} |
| 951 |
Sets the default value of \meta{key} to \meta{value}. This means that |
| 952 |
whenever no value is provided in a call to |\pgfkeys|, then this |
| 953 |
\meta{value} will be used instead. |
| 954 |
|
| 955 |
\example |\pgfkeys{/width/.default=1cm}| |
| 956 |
\end{handler} |
| 957 |
|
| 958 |
\begin{handler}{{.value required}} |
| 959 |
This handler causes the error message key |/errors/value required| to be |
| 960 |
issued whenever the \meta{key} is used without a value. |
| 961 |
|
| 962 |
\example |\pgfkeys{/width/.value required}| |
| 963 |
\end{handler} |
| 964 |
|
| 965 |
\begin{handler}{{.value forbidden}} |
| 966 |
This handler causes the error message key |/errors/value forbidden| to be |
| 967 |
issued whenever the \meta{key} is used with a value. |
| 968 |
|
| 969 |
This handler works be adding code to the code of the key. This means that |
| 970 |
you have to define the key first before you can use this handler. |
| 971 |
% |
| 972 |
\begin{codeexample}[code only] |
| 973 |
\pgfkeys{/my key/.code=I do not want an argument!} |
| 974 |
\pgfkeys{/my key/.value forbidden} |
| 975 |
|
| 976 |
\pgfkeys{/my key} % Ok |
| 977 |
\pgfkeys{/my key=foo} % Error |
| 978 |
\end{codeexample} |
| 979 |
% |
| 980 |
\end{handler} |
| 981 |
|
| 982 |
|
| 983 |
\subsubsection{Defining Key Codes} |
| 984 |
\label{section-code-handlers} |
| 985 |
|
| 986 |
A number of handlers exist for defining the code of keys. |
| 987 |
|
| 988 |
\begin{handler}{{.code}|=|\meta{code}} |
| 989 |
This handler executes |\pgfkeysdef| with the parameters \meta{key} and |
| 990 |
\meta{code}. This means that, afterwards, whenever the \meta{key} is used, |
| 991 |
the \meta{code} gets executed. More precisely, when |
| 992 |
\meta{key}|=|\meta{value} is encountered in a key list, \meta{code} is |
| 993 |
executed with any occurrence of |#1| replaced by \meta{value}. As always, |
| 994 |
if no \meta{value} is given, the default value is used, if defined, or the |
| 995 |
special value |\pgfkeysnovalue|. |
| 996 |
|
| 997 |
It is permissible that \meta{code} calls the command |\pgfkeys|. It is also |
| 998 |
permissible that \meta{code} calls the command |\pgfkeysalso|, which is |
| 999 |
useful for styles, see below. |
| 1000 |
% |
| 1001 |
\begin{codeexample}[code only] |
| 1002 |
\pgfkeys{/par indent/.code={\parindent=#1},/par indent/.default=2em} |
| 1003 |
\pgfkeys{/par indent=1cm} |
| 1004 |
... |
| 1005 |
\pgfkeys{/par indent} |
| 1006 |
\end{codeexample} |
| 1007 |
% |
| 1008 |
\end{handler} |
| 1009 |
|
| 1010 |
\begin{handler}{{.ecode}|=|\meta{code}} |
| 1011 |
This handler works like |/.code|, only the command |\pgfkeysedef| is used. |
| 1012 |
\end{handler} |
| 1013 |
|
| 1014 |
\begin{handler}{{.code 2 args}|=|\meta{code}} |
| 1015 |
This handler works like |/.code|, only two arguments rather than one are |
| 1016 |
expected when the \meta{code} is executed. This means that when |
| 1017 |
\meta{key}|=|\meta{value} is encountered in a key list, the \meta{value} |
| 1018 |
should consist of two arguments. For instance, \meta{value} could be |
| 1019 |
|{first}{second}|. Then \meta{code} is executed with any occurrence of |#1| |
| 1020 |
replaced |first| and any occurrence of |#2| replaced by |second|. |
| 1021 |
% |
| 1022 |
\begin{codeexample}[code only] |
| 1023 |
\pgfkeys{/page size/.code 2 args={\paperheight=#2\paperwidth=#1}} |
| 1024 |
\pgfkeys{/page size={30cm}{20cm}} |
| 1025 |
\end{codeexample} |
| 1026 |
% |
| 1027 |
Because of the special way the \meta{value} is parsed, if you set |
| 1028 |
\meta{value} to, for instance, |first| (without any braces), then |#1| will |
| 1029 |
be set to |f| and |#2| will be set to |irst|. |
| 1030 |
\end{handler} |
| 1031 |
|
| 1032 |
\begin{handler}{{.ecode 2 args}|=|\meta{code}} |
| 1033 |
This handler works like |/.code 2 args|, only an |\edef| is used rather |
| 1034 |
than a |\def| to define the macro. |
| 1035 |
\end{handler} |
| 1036 |
|
| 1037 |
\begin{handler}{{.code n args}|=|\marg{argument count}\marg{code}} |
| 1038 |
This handler also works like |/.code|, but you can now specify a number of |
| 1039 |
arguments between $0$ and $9$ (inclusive). |
| 1040 |
% |
| 1041 |
\begin{codeexample}[] |
| 1042 |
\pgfkeys{/a key/.code n args={2}{First=`#1', Second=`#2'}} |
| 1043 |
\pgfkeys{/a key={A}{B}} |
| 1044 |
\end{codeexample} |
| 1045 |
% |
| 1046 |
In contrast to |/.code 2 args|, there must be exactly \meta{argument count} |
| 1047 |
arguments, not more and not less and these arguments should be properly |
| 1048 |
delimited. |
| 1049 |
\end{handler} |
| 1050 |
|
| 1051 |
\begin{handler}{{.ecode n args}|=|\marg{argument count}\marg{code}} |
| 1052 |
This handler works like |/.code n args|, only an |\edef| is used rather |
| 1053 |
than a |\def| to define the macro. |
| 1054 |
\end{handler} |
| 1055 |
|
| 1056 |
\begin{handler}{{.code args}|=|\marg{argument pattern}\marg{code}} |
| 1057 |
This handler is the most flexible way to define a |/.code| key: you can now |
| 1058 |
specify an arbitrary \meta{argument pattern}. Such a pattern is a usual |
| 1059 |
\TeX\ macro pattern. For instance, suppose \meta{argument pattern} is |
| 1060 |
|(#1/#2)| and \meta{key}|=|\meta{value} is encountered in a key list with |
| 1061 |
\meta{value} being |(first/second)|. Then \meta{code} is executed with any |
| 1062 |
occurrence of |#1| replaced |first| and any occurrence of |#2| replaced by |
| 1063 |
|second|. So, the actual \meta{value} is matched against the \meta{argument |
| 1064 |
pattern} in the standard \TeX\ way. |
| 1065 |
% |
| 1066 |
\begin{codeexample}[code only] |
| 1067 |
\pgfkeys{/page size/.code args={#1 and #2}{\paperheight=#2\paperwidth=#1}} |
| 1068 |
\pgfkeys{/page size=30cm and 20cm} |
| 1069 |
\end{codeexample} |
| 1070 |
|
| 1071 |
Note that |/.code n args| should be preferred in case you need just a |
| 1072 |
number of arguments (when the resulting keys are used, |/.code n args| |
| 1073 |
gobbles spaces between the arguments whereas |/.code args| considers spaces |
| 1074 |
to be part of the argument). |
| 1075 |
\end{handler} |
| 1076 |
|
| 1077 |
\begin{handler}{{.ecode args}|=|\marg{argument pattern}\marg{code}} |
| 1078 |
This handler works like |/.code args|, only an |\edef| is used rather than |
| 1079 |
a |\def| to define the macro. |
| 1080 |
\end{handler} |
| 1081 |
|
| 1082 |
There are also handlers for modifying existing keys. |
| 1083 |
|
| 1084 |
\begin{handler}{{.add code}|=|\marg{prefix code}\marg{append code}} |
| 1085 |
This handler adds code to an existing key. The \meta{prefix code} is added |
| 1086 |
to the code stored in \meta{key}|/.@cmd| at the beginning, the \meta{append |
| 1087 |
code} is added to this code at the end. Either can be empty. The argument |
| 1088 |
list of \meta{code} cannot be changed using this handler. Note that both |
| 1089 |
\meta{prefix code} and \meta{append code} may contain parameters like |#2|. |
| 1090 |
% |
| 1091 |
\begin{codeexample}[code only] |
| 1092 |
\pgfkeys{/par indent/.code={\parindent=#1}} |
| 1093 |
\newdimen\myparindent |
| 1094 |
\pgfkeys{/par indent/.add code={}{\myparindent=#1}} |
| 1095 |
... |
| 1096 |
\pgfkeys{/par indent=1cm} % This will set both \parindent and |
| 1097 |
% \myparindent to 1cm |
| 1098 |
\end{codeexample} |
| 1099 |
% |
| 1100 |
\end{handler} |
| 1101 |
|
| 1102 |
\begin{handler}{{.prefix code}|=|\meta{prefix code}} |
| 1103 |
This handler is a shortcut for \meta{key}|/.add code={|\meta{prefix |
| 1104 |
code}|}{}|. That is, this handler adds the \meta{prefix code} at the |
| 1105 |
beginning of the code stored in \meta{key}|/.@cmd|. |
| 1106 |
\end{handler} |
| 1107 |
|
| 1108 |
\begin{handler}{{.append code}|=|\meta{append code}} |
| 1109 |
This handler is a shortcut for \meta{key}|/.add code={}{|\meta{append |
| 1110 |
code}|}|. |
| 1111 |
\end{handler} |
| 1112 |
|
| 1113 |
|
| 1114 |
\subsubsection{Defining Styles} |
| 1115 |
|
| 1116 |
The following handlers allow you to define \emph{styles}. A style is a key list |
| 1117 |
that is processed whenever the style is given as a key in a key list. Thus, a |
| 1118 |
style ``stands for'' a certain key value list. Styles can be parameterized just |
| 1119 |
like normal code. |
| 1120 |
|
| 1121 |
\begin{handler}{{.style}|=|\meta{key list}} |
| 1122 |
This handler sets things up so that whenever \meta{key}|=|\meta{value} is |
| 1123 |
encountered in a key list, then the \meta{key list}, with every occurrence |
| 1124 |
of |#1| replaced by \meta{value}, is processed instead. As always, if no |
| 1125 |
\meta{value} is given, the default value is used, if defined, or the |
| 1126 |
special value |\pgfkeysnovalue|. |
| 1127 |
|
| 1128 |
You can achieve the same effect by writing |
| 1129 |
\meta{key}|/.code=\pgfkeysalso{|\meta{key list}|}|. This means, in |
| 1130 |
particular, that the code of a key could also first execute some normal |
| 1131 |
code and only then process some further keys. |
| 1132 |
% |
| 1133 |
\begin{codeexample}[code only] |
| 1134 |
\pgfkeys{/par indent/.code={\parindent=#1}} |
| 1135 |
\pgfkeys{/no indent/.style={/par indent=0pt}} |
| 1136 |
\pgfkeys{/normal indent/.style={/par indent=2em}} |
| 1137 |
\pgfkeys{/no indent} |
| 1138 |
... |
| 1139 |
\pgfkeys{/normal indent} |
| 1140 |
\end{codeexample} |
| 1141 |
% |
| 1142 |
The following example shows a parameterized style ``in action''. |
| 1143 |
% |
| 1144 |
\begin{codeexample}[] |
| 1145 |
\begin{tikzpicture}[outline/.style={draw=#1,fill=#1!20}] |
| 1146 |
\node [outline=red] {red box}; |
| 1147 |
\node [outline=blue] at (0,-1) {blue box}; |
| 1148 |
\end{tikzpicture} |
| 1149 |
\end{codeexample} |
| 1150 |
% |
| 1151 |
\end{handler} |
| 1152 |
|
| 1153 |
\begin{handler}{{.estyle}|=|\meta{key list}} |
| 1154 |
This handler works like |/.style|, only the \meta{code} is set using |
| 1155 |
|\edef| rather than |\def|. Thus, all macros in the \meta{code} are |
| 1156 |
expanded prior to saving the style. |
| 1157 |
\end{handler} |
| 1158 |
|
| 1159 |
For styles the corresponding handlers as for normal code exist: |
| 1160 |
|
| 1161 |
\begin{handler}{{.style 2 args}|=|\meta{key list}} |
| 1162 |
This handler works like |/.code 2 args|, only for styles. Thus, the |
| 1163 |
\meta{key list} may contain occurrences of both |#1| and |#2| and when the |
| 1164 |
style is used, two parameters must be given as \meta{value}. |
| 1165 |
% |
| 1166 |
\begin{codeexample}[code only] |
| 1167 |
\pgfkeys{/paper height/.code={\paperheight=#1},/paper width/.code={\paperwidth=#1}} |
| 1168 |
\pgfkeys{/page size/.style 2 args={/paper height=#1,/paper width=#2}} |
| 1169 |
\pgfkeys{/page size={30cm}{20cm}} |
| 1170 |
\end{codeexample} |
| 1171 |
% |
| 1172 |
\end{handler} |
| 1173 |
|
| 1174 |
\begin{handler}{{.estyle 2 args}|=|\meta{key list}} |
| 1175 |
This handler works like |/.style 2 args|, only an |\edef| is used rather |
| 1176 |
than a |\def| to define the macro. |
| 1177 |
\end{handler} |
| 1178 |
|
| 1179 |
\begin{handler}{{.style n args}|=|\marg{argument count}\meta{key list}} |
| 1180 |
This handler works like |/.code n args|, only for styles. Here, \meta{key |
| 1181 |
list} may depend on all \meta{argument count} parameters. |
| 1182 |
\end{handler} |
| 1183 |
|
| 1184 |
\begin{handler}{{.add style}|=|\marg{prefix key list}\marg{append key list}} |
| 1185 |
This handler works like |/.add code|, only for styles. However, it is |
| 1186 |
permissible to add styles to keys that have previously been set using |
| 1187 |
|/.code|. (It is also permissible to add normal \meta{code} to a key that |
| 1188 |
has previously been set using |/.style|). When you add a style to a key |
| 1189 |
that was previously set using |/.code|, the following happens: When |
| 1190 |
\meta{key} is processed, the \meta{prefix key list} will be processed |
| 1191 |
first, then the \meta{code} that was previously stored in |
| 1192 |
\meta{key}|/.@cmd|, and then the keys in \meta{append key list} are |
| 1193 |
processed. |
| 1194 |
% |
| 1195 |
\begin{codeexample}[code only] |
| 1196 |
\pgfkeys{/par indent/.code={\parindent=#1}} |
| 1197 |
\pgfkeys{/par indent/.add style={}{/my key=#1}} |
| 1198 |
... |
| 1199 |
\pgfkeys{/par indent=1cm} % This will set \parindent and |
| 1200 |
% then execute /my key=#1 |
| 1201 |
\end{codeexample} |
| 1202 |
% |
| 1203 |
\end{handler} |
| 1204 |
|
| 1205 |
\begin{handler}{{.style args}|=|\marg{argument pattern}\marg{key list}} |
| 1206 |
This handler works like |/.code args|, only for styles. |
| 1207 |
\end{handler} |
| 1208 |
|
| 1209 |
\begin{handler}{{.estyle args}|=|\marg{argument pattern}\marg{code}} |
| 1210 |
This handler works like |/.ecode args|, only for styles. |
| 1211 |
\end{handler} |
| 1212 |
|
| 1213 |
\begin{handler}{{.prefix style}|=|\meta{prefix key list}} |
| 1214 |
Works like |/.add style|, but only for the prefix key list. |
| 1215 |
\end{handler} |
| 1216 |
|
| 1217 |
\begin{handler}{{.append style}|=|\meta{append key list}} |
| 1218 |
Works like |/.add style|, but only for the append key list. |
| 1219 |
\end{handler} |
| 1220 |
|
| 1221 |
|
| 1222 |
\subsubsection{Defining Value-, Macro-, If- and Choice-Keys} |
| 1223 |
|
| 1224 |
For some keys, the code that should be executed for them is rather |
| 1225 |
``specialized''. For instance, it happens often that the code for a key just |
| 1226 |
sets a certain \TeX-if to true or false. For these cases, predefined handlers |
| 1227 |
make it easier to install the necessary code. |
| 1228 |
|
| 1229 |
However, we start with some handlers that are used to manage the value that is |
| 1230 |
directly stored in a key. |
| 1231 |
|
| 1232 |
\begin{handler}{{.initial}|=|\meta{value}} |
| 1233 |
This handler sets the value of \meta{key} to \meta{value}. Note that no |
| 1234 |
subkeys are involved. After this handler has been used, by the rules |
| 1235 |
governing keys, you can subsequently change the value of the \meta{key} by |
| 1236 |
just writing \meta{key}|=|\meta{value}. Thus, this handler is used to set |
| 1237 |
the initial value of key. |
| 1238 |
% |
| 1239 |
\begin{codeexample}[code only] |
| 1240 |
\pgfkeys{/my key/.initial=red} |
| 1241 |
% "/my key" now stores the value "red" |
| 1242 |
\pgfkeys{/my key=blue} |
| 1243 |
% "/my key" now stores the value "blue" |
| 1244 |
\end{codeexample} |
| 1245 |
|
| 1246 |
Note that with this configuration, writing |\pgfkeys{/my key}| will not |
| 1247 |
have the effect you might expect (namely that |blue| is inserted into the |
| 1248 |
main text). Rather, |/my key| will be promoted to |/my key=\pgfkeysnovalue| |
| 1249 |
and, thus, |\pgfkeysnovalue| will be stored in |/my key|. |
| 1250 |
|
| 1251 |
To retrieve the value stored in a key, the handler |/.get| is used. |
| 1252 |
|
| 1253 |
\medskip |
| 1254 |
\emph{Remark:} A key can both store a value and execute commands% |
| 1255 |
\footnote{This behavior was partially changed in \pgfname{} 3.1.6 and then |
| 1256 |
restored in 3.1.7. For compatibility reasons, this behavior will not be |
| 1257 |
changed in future releases anymore.}. |
| 1258 |
If so, using \meta{key} will \emph{always} execute commands with the passed |
| 1259 |
value, or the default value |\pgfkeysnovalue| if no value is provided. |
| 1260 |
Note that the stored value is never used. To update the stored value, the |
| 1261 |
handler |/.initial| or command |\pgfkeyssetvalue| is used. |
| 1262 |
% |
| 1263 |
\begin{codeexample}[] |
| 1264 |
\pgfkeys{/my key/.initial=red} |
| 1265 |
\pgfkeys{/my key/.code=#1} |
| 1266 |
% "/my key" now both stores the value "red" and executes commands |
| 1267 |
\pgfkeys{/my key=blue} |
| 1268 |
% "/my key" now still stores the value "red" |
| 1269 |
\end{codeexample} |
| 1270 |
% |
| 1271 |
\end{handler} |
| 1272 |
|
| 1273 |
\begin{handler}{{.get}|=|\meta{macro}} |
| 1274 |
Executes a |\let| command so that \meta{macro} contains the contents stored |
| 1275 |
in \meta{key}. |
| 1276 |
% |
| 1277 |
\begin{codeexample}[] |
| 1278 |
\pgfkeys{/my key/.initial=red} |
| 1279 |
\pgfkeys{/my key=blue} |
| 1280 |
\pgfkeys{/my key/.get=\mymacro} |
| 1281 |
\mymacro |
| 1282 |
\end{codeexample} |
| 1283 |
% |
| 1284 |
\end{handler} |
| 1285 |
|
| 1286 |
\begin{handler}{{.add}|=|\marg{prefix value}\marg{append value}} |
| 1287 |
Adds the \meta{prefix value} at the beginning and the \meta{append value} |
| 1288 |
at the end of the value stored in \meta{key}. |
| 1289 |
\end{handler} |
| 1290 |
|
| 1291 |
\begin{handler}{{.prefix}|=|\marg{prefix value}} |
| 1292 |
Adds the \meta{prefix value} at the beginning of the value stored in |
| 1293 |
\meta{key}. |
| 1294 |
\end{handler} |
| 1295 |
|
| 1296 |
\begin{handler}{{.append}|=|\marg{append value}} |
| 1297 |
Adds the \meta{append value} at the end of the value stored in \meta{key}. |
| 1298 |
\end{handler} |
| 1299 |
|
| 1300 |
\begin{handler}{{.link}|=|\meta{another key}} |
| 1301 |
Stores the value |\pgfkeysvalueof{|\meta{another key}|}| in the \meta{key}. |
| 1302 |
The idea is that when you expand the \meta{key}, the value of \meta{another |
| 1303 |
key} is expanded instead. This corresponds loosely to the notion of soft |
| 1304 |
links in Unix, hence the name. |
| 1305 |
\end{handler} |
| 1306 |
|
| 1307 |
The next handler is useful for the common situation where |
| 1308 |
\meta{key}|=|\meta{value} should cause the \meta{value} to be stored in some |
| 1309 |
macro. Note that, typically, you could just as well store the value in the key |
| 1310 |
itself. |
| 1311 |
|
| 1312 |
\begin{handler}{{.store in}|=|\meta{macro}} |
| 1313 |
This handler has the following effect: When you write |
| 1314 |
\meta{key}|=|\meta{value}, the code |\def|\meta{macro}|{|\meta{value}|}| is |
| 1315 |
executed. Thus, the given value is ``stored'' in the \meta{macro}. |
| 1316 |
% |
| 1317 |
\begin{codeexample}[] |
| 1318 |
\pgfkeys{/text/.store in=\mytext} |
| 1319 |
\def\a{world} |
| 1320 |
\pgfkeys{/text=Hello \a!} |
| 1321 |
\def\a{Gruffalo} |
| 1322 |
\mytext |
| 1323 |
\end{codeexample} |
| 1324 |
% |
| 1325 |
\end{handler} |
| 1326 |
|
| 1327 |
\begin{handler}{{.estore in}|=|\meta{macro}} |
| 1328 |
This handler is similar to |/.store in|, only the code |
| 1329 |
|\edef|\meta{macro}|{|\meta{value}|}| is used. Thus, the macro-expanded |
| 1330 |
version of \meta{value} is stored in the \meta{macro}. |
| 1331 |
% |
| 1332 |
\begin{codeexample}[] |
| 1333 |
\pgfkeys{/text/.estore in=\mytext} |
| 1334 |
\def\a{world} |
| 1335 |
\pgfkeys{/text=Hello \a!} |
| 1336 |
\def\a{Gruffalo} |
| 1337 |
\mytext |
| 1338 |
\end{codeexample} |
| 1339 |
% |
| 1340 |
\end{handler} |
| 1341 |
|
| 1342 |
In another common situation a key is used to set a \TeX-if to true or false. |
| 1343 |
|
| 1344 |
\begin{handler}{{.is if}|=|\meta{\TeX-if name}} |
| 1345 |
This handler has the following effect: When you write |
| 1346 |
\meta{key}|=|\meta{value}, it is first checked that \meta{value} is |true| |
| 1347 |
or |false| (the default is |true| if no \meta{value} is given). If this is |
| 1348 |
not the case, the error key |/errors/boolean expected| is executed. |
| 1349 |
Otherwise, the code |\|\meta{\TeX-if name}\meta{value} is executed, which |
| 1350 |
sets the \TeX-if accordingly. |
| 1351 |
% |
| 1352 |
\begin{codeexample}[] |
| 1353 |
\newif\iftheworldisflat |
| 1354 |
\pgfkeys{/flat world/.is if=theworldisflat} |
| 1355 |
\pgfkeys{/flat world=false} |
| 1356 |
\iftheworldisflat |
| 1357 |
Flat |
| 1358 |
\else |
| 1359 |
Round? |
| 1360 |
\fi |
| 1361 |
\end{codeexample} |
| 1362 |
% |
| 1363 |
\end{handler} |
| 1364 |
|
| 1365 |
The next handler deals with the problem when a \meta{key}|=|\meta{value} makes |
| 1366 |
sense only for a small set of possible \meta{value}s. For instance, the line |
| 1367 |
cap can only be |rounded| or |rect| or |butt|, but nothing else. For this |
| 1368 |
situation the following handler is useful. |
| 1369 |
|
| 1370 |
\begin{handler}{{.is choice}} |
| 1371 |
This handler sets things up so that writing \meta{key}|=|\meta{value} will |
| 1372 |
cause the subkey \meta{key}|/|\meta{value} to be executed. So, each of the |
| 1373 |
different possible choices should be given by a subkey of \meta{key}. |
| 1374 |
% |
| 1375 |
\begin{codeexample}[code only] |
| 1376 |
\pgfkeys{/line cap/.is choice} |
| 1377 |
\pgfkeys{/line cap/round/.code={\pgfsetroundcap}} |
| 1378 |
\pgfkeys{/line cap/butt/.code={\pgfsetbuttcap}} |
| 1379 |
\pgfkeys{/line cap/rect/.code={\pgfsetrectcap}} |
| 1380 |
\pgfkeys{/line cap/rectangle/.style={/line cap=rect}} |
| 1381 |
... |
| 1382 |
\draw [/line cap=butt] ... |
| 1383 |
\end{codeexample} |
| 1384 |
% |
| 1385 |
If the subkey \meta{key}|/|\meta{value} does not exist, the error key |
| 1386 |
|/errors/unknown choice value| is executed. |
| 1387 |
\end{handler} |
| 1388 |
|
| 1389 |
|
| 1390 |
\subsubsection{Expanded and Multiple Values} |
| 1391 |
|
| 1392 |
When you write \meta{key}|=|\meta{value}, you usually wish to use the |
| 1393 |
\meta{value} ``as is''. Indeed, great care is taken to ensure that you can even |
| 1394 |
use things like |#1| or unbalanced \TeX-ifs inside \meta{value}. However, |
| 1395 |
sometimes you want the \meta{value} to be expanded before it is used. For |
| 1396 |
instance, \meta{value} might be a macro name like |\mymacro| and you do not |
| 1397 |
want |\mymacro| to be used as the macro, but rather the \emph{contents} of |
| 1398 |
|\mymacro|. Thus, instead of using \meta{value}, you wish to use whatever |
| 1399 |
\meta{value} expands to. Instead of using some fancy |\expandafter| hackery, |
| 1400 |
you can use the following handlers: |
| 1401 |
|
| 1402 |
\begin{handler}{{.expand once}|=|\meta{value}} |
| 1403 |
This handler expands \meta{value} once (more precisely, it executes an |
| 1404 |
|\expandafter| command on the first token of \meta{value}) and then process |
| 1405 |
the resulting \meta{result} as if you had written |
| 1406 |
\meta{key}|=|\meta{result}. Note that if \meta{key} contains a handler |
| 1407 |
itself, this handler will be called normally. |
| 1408 |
% |
| 1409 |
\begin{codeexample}[] |
| 1410 |
\def\a{bottom} |
| 1411 |
\def\b{\a} |
| 1412 |
\def\c{\b} |
| 1413 |
|
| 1414 |
\pgfkeys{/key1/.initial=\c} |
| 1415 |
\pgfkeys{/key2/.initial/.expand once=\c} |
| 1416 |
\pgfkeys{/key3/.initial/.expand twice=\c} |
| 1417 |
\pgfkeys{/key4/.initial/.expanded=\c} |
| 1418 |
|
| 1419 |
\def\a{{\ttfamily\string\a}} |
| 1420 |
\def\b{{\ttfamily\string\b}} |
| 1421 |
\def\c{{\ttfamily\string\c}} |
| 1422 |
|
| 1423 |
\begin{tabular}{ll} |
| 1424 |
Key 1:& \pgfkeys{/key1} \\ |
| 1425 |
Key 2:& \pgfkeys{/key2} \\ |
| 1426 |
Key 3:& \pgfkeys{/key3} \\ |
| 1427 |
Key 4:& \pgfkeys{/key4} |
| 1428 |
\end{tabular} |
| 1429 |
\end{codeexample} |
| 1430 |
% |
| 1431 |
\end{handler} |
| 1432 |
|
| 1433 |
\begin{handler}{{.expand twice}|=|\meta{value}} |
| 1434 |
This handler works like saying |
| 1435 |
\meta{key}|/.expand once/.expand once=|\meta{value}. |
| 1436 |
\end{handler} |
| 1437 |
|
| 1438 |
\begin{handler}{{.expanded}|=|\meta{value}} |
| 1439 |
This handler will completely expand \meta{value} (using |\edef|) before |
| 1440 |
processing \meta{key}|=|\meta{result}. |
| 1441 |
\end{handler} |
| 1442 |
|
| 1443 |
\begin{handler}{{.evaluated}|=|\meta{value}} |
| 1444 |
This handler will evaluate \meta{value} as a mathematical |
| 1445 |
expression with |\pgfmathparse| and assign \meta{key}|=\pgfmathresult|. |
| 1446 |
% |
| 1447 |
\begin{codeexample}[] |
| 1448 |
\pgfkeys{ |
| 1449 |
/golden ratio/.initial/.evaluated={(1 + sqrt(5))/2}, |
| 1450 |
} |
| 1451 |
\pgfkeys{/golden ratio} |
| 1452 |
\end{codeexample} |
| 1453 |
% |
| 1454 |
\end{handler} |
| 1455 |
|
| 1456 |
\begin{handler}{{.list}|=|\meta{comma-separated list of values}} |
| 1457 |
This handler causes the key to be used repeatedly, namely once for every |
| 1458 |
element of the list of values. Note that the list of values should |
| 1459 |
typically be surrounded by braces since, otherwise, \TeX\ will not be able |
| 1460 |
to tell whether a comma starts a new key or a new value. |
| 1461 |
|
| 1462 |
The \meta{list of values} is processed using the |\foreach| statement, so |
| 1463 |
you can use the |...| notation. |
| 1464 |
% |
| 1465 |
\begin{codeexample}[] |
| 1466 |
\pgfkeys{/foo/.code=(#1)} |
| 1467 |
\pgfkeys{/foo/.list={a,b,0,1,...,5}} |
| 1468 |
\end{codeexample} |
| 1469 |
% |
| 1470 |
\end{handler} |
| 1471 |
|
| 1472 |
|
| 1473 |
\subsubsection{Handlers for Forwarding} |
| 1474 |
|
| 1475 |
\begin{handler}{{.forward to}|=|\meta{another key}} |
| 1476 |
This handler causes the \meta{key} to ``forward'' its argument to |
| 1477 |
\meta{another key}. When the \meta{key} is used, its normal code will be |
| 1478 |
executed first. Then, the value is (additionally) passed to \meta{another |
| 1479 |
key}. If the \meta{key} has not yet been defined prior to the use of |
| 1480 |
|.forward to|, it will be defined then (and do nothing by itself, expect |
| 1481 |
for forwarding it to \meta{key name}). The \meta{another key} must be a |
| 1482 |
fully qualified key name. |
| 1483 |
% |
| 1484 |
\begin{codeexample}[] |
| 1485 |
\pgfkeys{ |
| 1486 |
/a/.code=(a:#1), |
| 1487 |
/b/.code=(b:#1), |
| 1488 |
/b/.forward to=/a, |
| 1489 |
/c/.forward to=/a |
| 1490 |
} |
| 1491 |
\pgfkeys{/b=1} \pgfkeys{/c=2} |
| 1492 |
\end{codeexample} |
| 1493 |
% |
| 1494 |
\end{handler} |
| 1495 |
|
| 1496 |
\begin{handler}{{.search also}=\marg{path list}} |
| 1497 |
A style which installs a |/.unknown| handler into \meta{key}. This |
| 1498 |
|/.unknown| handler will then search for unknown keys in every path |
| 1499 |
provided in \marg{path list}. |
| 1500 |
% |
| 1501 |
\begin{codeexample}[] |
| 1502 |
% define a key: |
| 1503 |
\pgfkeys{/secondary path/option/.code={Invoking /secondary path/option with `#1'}} |
| 1504 |
|
| 1505 |
% set up a search path: |
| 1506 |
\pgfkeys{/main path/.search also={/secondary path}} |
| 1507 |
|
| 1508 |
% try searching for `option=value' in '/main path': |
| 1509 |
% -> this finds `/secondary path/option'! |
| 1510 |
\pgfkeys{/main path/.cd,option=value} |
| 1511 |
\end{codeexample} |
| 1512 |
|
| 1513 |
The |/.search also| handler follows the strategy |
| 1514 |
% |
| 1515 |
\begin{enumerate} |
| 1516 |
\item If a user provides a fully qualified key which could not be |
| 1517 |
found, for example the full string |/main path/option|, it assumes |
| 1518 |
that the user knew what she is doing -- and does \emph{not} |
| 1519 |
continue searching for |option| in \marg{path list}. |
| 1520 |
\item If a user provides only the key's name, for example |option| and |
| 1521 |
|option| cannot be found in the current default path (which is |
| 1522 |
|/main path| in our example above), the current default path is set |
| 1523 |
to the next element in \marg{path list} (which is |/secondary path| |
| 1524 |
here) and |\pgfkeys| will be restarted. |
| 1525 |
|
| 1526 |
This will be iterated until either a match has been found or all |
| 1527 |
elements in \marg{path list} have been tested. |
| 1528 |
\item If all |
| 1529 |
elements in \marg{path list} have been checked and the key is still |
| 1530 |
unknown, the fall-back handler |/handlers/.unknown| will be |
| 1531 |
invoked. |
| 1532 |
\end{enumerate} |
| 1533 |
% |
| 1534 |
\begin{codeexample}[] |
| 1535 |
% define a key: |
| 1536 |
\pgfkeys{/secondary path/option/.code={Invoking /secondary path/option with `#1'}} |
| 1537 |
|
| 1538 |
% set up a search path: |
| 1539 |
\pgfkeys{/main path/.search also={/secondary path}} |
| 1540 |
|
| 1541 |
% try searching for `option=value' in '/main path': |
| 1542 |
% -> this finds `/secondary path/option'! |
| 1543 |
\pgfkeys{/main path/.cd,option=value} |
| 1544 |
|
| 1545 |
% negative example: |
| 1546 |
% try searching for fully qualified key /main path/option. |
| 1547 |
% This won't be handled by .search also. |
| 1548 |
\pgfkeys{/handlers/.unknown/.code={Found unknown option \pgfkeyscurrentkeyRAW={#1}!}}% |
| 1549 |
\pgfkeys{/main path/.cd,/main path/option=value} |
| 1550 |
\end{codeexample} |
| 1551 |
|
| 1552 |
Please note that the strategy of |/.search also| is different from the |
| 1553 |
first example provided in section~\ref{sec:pgf:unknown:keys} ``Unknown |
| 1554 |
Keys'' because |/.search also| only applies to keys that are not fully |
| 1555 |
qualified. |
| 1556 |
|
| 1557 |
For those who are familiar with |\pgfkeys|, the actual implementation of |
| 1558 |
|/.search also| might be interesting: |
| 1559 |
% |
| 1560 |
\begin{enumerate} |
| 1561 |
\item |\pgfkeys{/path/.search also={/tikz}}| is equivalent to |
| 1562 |
% |
| 1563 |
\begin{codeexample}[code only] |
| 1564 |
\pgfkeys{/path/.unknown/.code={% |
| 1565 |
\def\pgfkeys@searchalso@temp@value{#1}% |
| 1566 |
\ifpgfkeysaddeddefaultpath |
| 1567 |
\expandafter\pgfkeys@firstoftwo |
| 1568 |
\else |
| 1569 |
\expandafter\pgfkeys@secondoftwo |
| 1570 |
\fi{% |
| 1571 |
% only process keys for which no full path has been |
| 1572 |
% provided: |
| 1573 |
\pgfkeyssuccessfalse |
| 1574 |
\let\pgfkeys@searchalso@name=\pgfkeyscurrentkeyRAW |
| 1575 |
\ifpgfkeyssuccess |
| 1576 |
\else |
| 1577 |
% search with /tikz as default path: |
| 1578 |
\pgfqkeys{/tikz}{\pgfkeys@searchalso@name/.expand once=% |
| 1579 |
\pgfkeys@searchalso@temp@value}% |
| 1580 |
\fi |
| 1581 |
}{% |
| 1582 |
\pgfkeysgetvalue{/handlers/.unknown/.@cmd}{\pgfkeys@code}% |
| 1583 |
\expandafter\pgfkeys@code\pgfkeys@searchalso@temp@value\pgfeov |
| 1584 |
}% |
| 1585 |
} |
| 1586 |
} |
| 1587 |
\end{codeexample} |
| 1588 |
% |
| 1589 |
\item |\pgfkeys{/path/.search also={/tikz,/pgf}}| is equivalent to |
| 1590 |
% |
| 1591 |
\begin{codeexample}[code only] |
| 1592 |
\pgfkeys{/path/.unknown/.code={% |
| 1593 |
\def\pgfkeys@searchalso@temp@value{#1}% |
| 1594 |
\ifpgfkeysaddeddefaultpath |
| 1595 |
\expandafter\pgfkeys@firstoftwo |
| 1596 |
\else |
| 1597 |
\expandafter\pgfkeys@secondoftwo |
| 1598 |
\fi{% |
| 1599 |
\pgfkeyssuccessfalse |
| 1600 |
\let\pgfkeys@searchalso@name=\pgfkeyscurrentkeyRAW |
| 1601 |
\ifpgfkeyssuccess |
| 1602 |
\else |
| 1603 |
% step 1: search in /tikz with .try: |
| 1604 |
\pgfqkeys{/tikz}{\pgfkeys@searchalso@name/.try/.expand once=% |
| 1605 |
\pgfkeys@searchalso@temp@value}% |
| 1606 |
\fi |
| 1607 |
\ifpgfkeyssuccess |
| 1608 |
\else |
| 1609 |
% step 2: search in /pgf (without .try!): |
| 1610 |
\pgfqkeys{/pgf}{\pgfkeys@searchalso@name/.expand once=\pgfkeys@searchalso@}% |
| 1611 |
\fi |
| 1612 |
}{% |
| 1613 |
\pgfkeysgetvalue{/handlers/.unknown/.@cmd}{\pgfkeys@code}% |
| 1614 |
\expandafter\pgfkeys@code\pgfkeys@searchalso@temp@value\pgfeov |
| 1615 |
}% |
| 1616 |
} |
| 1617 |
} |
| 1618 |
\end{codeexample} |
| 1619 |
\end{enumerate} |
| 1620 |
|
| 1621 |
To also enable searching for styles (or other handled keys), consider |
| 1622 |
changing the configuration for handled keys to |
| 1623 |
|/handler config=full or existing| when you use |/.search also|, that is, |
| 1624 |
use |
| 1625 |
% |
| 1626 |
\begin{codeexample}[code only] |
| 1627 |
\pgfkeys{ |
| 1628 |
/main path/.search also={/secondary path}, |
| 1629 |
/handler config=full or existing} |
| 1630 |
\end{codeexample} |
| 1631 |
% |
| 1632 |
\end{handler} |
| 1633 |
|
| 1634 |
|
| 1635 |
\subsubsection{Handlers for Testing Keys} |
| 1636 |
|
| 1637 |
\begin{handler}{{.try}|=|\meta{value}} |
| 1638 |
This handler causes the same things to be done as if |
| 1639 |
\meta{key}|=|\meta{value} had been written instead. However, if neither |
| 1640 |
\meta{key}|/.@cmd| nor the key itself is defined, no handlers will be |
| 1641 |
called. Instead, the execution of the key just stops. Thus, this handler |
| 1642 |
will ``try'' to use the key, but no further action is taken when the key is |
| 1643 |
not defined. |
| 1644 |
|
| 1645 |
The \TeX-if |\ifpgfkeyssuccess| will be set according to whether the |
| 1646 |
\meta{key} was successfully executed or not. |
| 1647 |
% |
| 1648 |
\begin{codeexample}[] |
| 1649 |
\pgfkeys{/a/.code=(a:#1)} |
| 1650 |
\pgfkeys{/b/.code=(b:#1)} |
| 1651 |
\pgfkeys{/x/.try=hmm,/a/.try=hallo,/b/.try=welt} |
| 1652 |
\end{codeexample} |
| 1653 |
% |
| 1654 |
\end{handler} |
| 1655 |
|
| 1656 |
\begin{handler}{{.retry}|=|\meta{value}} |
| 1657 |
This handler works just like |/.try|, only it will not do anything if |
| 1658 |
|\ifpgfkeyssuccess| is false. Thus, this handler will only retry to set a |
| 1659 |
key if ``the last attempt failed''. |
| 1660 |
% |
| 1661 |
\begin{codeexample}[] |
| 1662 |
\pgfkeys{/a/.code=(a:#1)} |
| 1663 |
\pgfkeys{/b/.code=(b:#1)} |
| 1664 |
\pgfkeys{/x/.try=hmm,/a/.retry=hallo,/b/.retry=welt} |
| 1665 |
\end{codeexample} |
| 1666 |
% |
| 1667 |
\end{handler} |
| 1668 |
|
| 1669 |
\begin{handler}{{.lastretry}|=|\meta{value}} |
| 1670 |
This handler works like |/.retry|, only it will invoke the usual handlers |
| 1671 |
for unknowns keys if |\ifpgfkeyssuccess| is false. Thus, this handler |
| 1672 |
will only try to set a key if ``the last attempt failed''. Furthermore, |
| 1673 |
this here is the last such attempt. |
| 1674 |
\end{handler} |
| 1675 |
|
| 1676 |
|
| 1677 |
\subsubsection{Handlers for Key Inspection} |
| 1678 |
|
| 1679 |
\begin{handler}{{.show value}} |
| 1680 |
This handler executes a |\show| command on the value stored in \meta{key}. |
| 1681 |
This is useful mostly for debugging. |
| 1682 |
|
| 1683 |
\example |\pgfkeys{/my/obscure key/.show value}| |
| 1684 |
\end{handler} |
| 1685 |
|
| 1686 |
\begin{handler}{{.show code}} |
| 1687 |
This handler executes a |\show| command on the code stored in |
| 1688 |
\meta{key}|/.@cmd|. This is useful mostly for debugging. |
| 1689 |
|
| 1690 |
\example |\pgfkeys{/my/obscure key/.show code}| |
| 1691 |
\end{handler} |
| 1692 |
|
| 1693 |
The following key is not a handler, but it also commonly used for inspecting |
| 1694 |
things: |
| 1695 |
% |
| 1696 |
\begin{key}{/utils/exec=\meta{code}} |
| 1697 |
This key will simply execute the given \meta{code}. |
| 1698 |
|
| 1699 |
% FIXME: there is a bug in the pretty printer ... fix it! |
| 1700 |
\example \verb|\pgfkeys{some key=some value,/utils/exec=\show\hallo,obscure key=obscure}| |
| 1701 |
\end{key} |
| 1702 |
|
| 1703 |
|
| 1704 |
\subsection{Error Keys} |
| 1705 |
|
| 1706 |
In certain situations errors can occur, like using an undefined key. In these |
| 1707 |
situations error keys are executed. They should store a macro that gets two |
| 1708 |
arguments: The first is the offending key (possibly only after macro |
| 1709 |
expansion), the second is the value that was passed as a parameter (also |
| 1710 |
possibly only after macro expansion). |
| 1711 |
|
| 1712 |
Currently, error keys are simply executed. In the future it might be a good |
| 1713 |
idea to have different subkeys that are executed depending on the language |
| 1714 |
currently set so that users get a localized error message. |
| 1715 |
|
| 1716 |
\begin{key}{/errors/value required=\marg{offending key}\marg{value}} |
| 1717 |
This key is executed whenever an \meta{offending key} is used without a |
| 1718 |
value when a value is actually required. |
| 1719 |
\end{key} |
| 1720 |
|
| 1721 |
\begin{key}{/errors/value forbidden=\marg{offending key}\marg{value}} |
| 1722 |
This key is executed whenever a key is used with a value when a value is |
| 1723 |
actually forbidden. |
| 1724 |
\end{key} |
| 1725 |
|
| 1726 |
\begin{key}{/errors/boolean expected=\marg{offending key}\marg{value}} |
| 1727 |
This key is executed whenever a key set up using |/.is if| gets called with |
| 1728 |
a \meta{value} other than |true| or |false|. |
| 1729 |
\end{key} |
| 1730 |
|
| 1731 |
\begin{key}{/errors/unknown choice value=\marg{offending key}\marg{value}} |
| 1732 |
This key is executed whenever a choice is used as a \meta{value} for a key |
| 1733 |
set up using the |/.is choice| handler that is not defined. |
| 1734 |
\end{key} |
| 1735 |
|
| 1736 |
\begin{key}{/errors/unknown key=\marg{offending key}\marg{value}} |
| 1737 |
This key is executed whenever a key is unknown and no specific |/.unknown| |
| 1738 |
handler is found. |
| 1739 |
\end{key} |
| 1740 |
|
| 1741 |
|
| 1742 |
\input{pgfmanual-en-pgfkeysfiltered.tex} |