| 1 |
|
| 2 |
\subsection{Key Filtering} |
| 3 |
\begingroup |
| 4 |
|
| 5 |
{\small \emph{An extension by Christian Feuersänger}} |
| 6 |
\vspace{0.4cm}% |
| 7 |
|
| 8 |
\noindent Normally, a call to |\pgfkeys| sets all keys provided in its argument |
| 9 |
list. This is usually what users expect it to do. However, implementations of |
| 10 |
different packages or \pgfname-libraries may need more control over the key |
| 11 |
setting procedure: library~A may want to set its options directly and |
| 12 |
communicate all remaining ones to library~B. |
| 13 |
|
| 14 |
\begin{pgfkeyslibrary}{filtered} |
| 15 |
The |filtered| library provides functionality to filter keys and only process |
| 16 |
selected ones, while forwarding the others to another namespace. |
| 17 |
|
| 18 |
This library is loaded by default by |pgfkeys|. |
| 19 |
\end{pgfkeyslibrary} |
| 20 |
|
| 21 |
This section describes key filtering methods of \pgfname, including options for |
| 22 |
family groupings. If you merely want to use \pgfname\ (or its libraries), you |
| 23 |
can skip this section. It is addressed to package (or library) authors. |
| 24 |
|
| 25 |
\subsubsection{Starting With An Example} |
| 26 |
\label{section-key-filter-example} |
| 27 |
|
| 28 |
Users of |xkeyval| are familiar with the concept of key families: keys belong |
| 29 |
to groups and those keys can be `filtered' out of other options. \pgfname\ |
| 30 |
supports family groupings and more abstract key selection mechanism with |
| 31 |
|\pgfkeysfiltered|, a variant of |\pgfkeys|. Suppose we have the example key |
| 32 |
grouping |
| 33 |
|
| 34 |
\begin{codeexample}[setup code,hidden] |
| 35 |
\pgfkeys{ |
| 36 |
/my group/A1/.code=(A1:#1), |
| 37 |
/my group/A2/.code=(A2:#1), |
| 38 |
/my group/A3/.code=(A3:#1), |
| 39 |
/my group/B/.code=(B:#1), |
| 40 |
/my group/C/.code=(B:#1), |
| 41 |
/my group/A/.is family, |
| 42 |
/my group/A1/.belongs to family=/my group/A, |
| 43 |
/my group/A2/.belongs to family=/my group/A, |
| 44 |
/my group/A3/.belongs to family=/my group/A, |
| 45 |
/pgf/key filters/active families/.install key filter, |
| 46 |
/my group/A/.activate family, |
| 47 |
} |
| 48 |
\end{codeexample} |
| 49 |
% |
| 50 |
\begin{codeexample}[code only] |
| 51 |
\pgfkeys{ |
| 52 |
/my group/A1/.code=(A1:#1), |
| 53 |
/my group/A2/.code=(A2:#1), |
| 54 |
/my group/A3/.code=(A3:#1), |
| 55 |
/my group/B/.code=(B:#1), |
| 56 |
/my group/C/.code=(B:#1), |
| 57 |
} |
| 58 |
\end{codeexample} |
| 59 |
|
| 60 |
\noindent and we want to set options |A1|, |A2| and |A3| only. A call to |
| 61 |
|\pgfkeys| yields |
| 62 |
% |
| 63 |
\begin{codeexample}[] |
| 64 |
\pgfkeys{/my group/A1=a1, /my group/A2=a2, /my group/B=b, /my group/C=c} |
| 65 |
\end{codeexample} |
| 66 |
% |
| 67 |
\noindent because all those command option are processed consecutively. |
| 68 |
|
| 69 |
Now, let's define a family named |A| which contains |A1|, |A2| and |A3| and set |
| 70 |
only family members of |A|. We prepare our key settings with |
| 71 |
% |
| 72 |
\begin{codeexample}[code only] |
| 73 |
\pgfkeys{ |
| 74 |
/my group/A/.is family, |
| 75 |
/my group/A1/.belongs to family=/my group/A, |
| 76 |
/my group/A2/.belongs to family=/my group/A, |
| 77 |
/my group/A3/.belongs to family=/my group/A, |
| 78 |
} |
| 79 |
\end{codeexample} |
| 80 |
% |
| 81 |
\noindent and |
| 82 |
% |
| 83 |
\begin{codeexample}[code only,preamble={\usepgfkeyslibrary{filtered}}] |
| 84 |
\pgfkeys{/pgf/key filters/active families/.install key filter} |
| 85 |
\end{codeexample} |
| 86 |
% |
| 87 |
\noindent After this preparation, we can use |\pgfkeysfiltered| with |
| 88 |
% |
| 89 |
\begin{codeexample}[preamble={\usepgfkeyslibrary{filtered}}] |
| 90 |
\pgfkeys{/my group/A/.activate family} |
| 91 |
\pgfkeysfiltered{/my group/A1=a1, /my group/A2=a2, |
| 92 |
/my group/B=b, /my group/C=c} |
| 93 |
\end{codeexample} |
| 94 |
% |
| 95 |
\noindent or |
| 96 |
% |
| 97 |
\begin{codeexample}[preamble={\usepgfkeyslibrary{filtered}}] |
| 98 |
\pgfkeys{/my group/A/.activate family} |
| 99 |
\pgfkeysfiltered{/my group/A1=a1, /my group/A2=a2, |
| 100 |
/my group/B=b, /my group/C=c, /tikz/color=blue, /my group/A3=a3} |
| 101 |
\end{codeexample} |
| 102 |
% |
| 103 |
\noindent to set only keys which belong to an `active' family -- in our case, |
| 104 |
only family~|A| was active, so the remaining options have not been processed. |
| 105 |
The family processing is quite fast and allows an arbitrary number of active |
| 106 |
key families. |
| 107 |
|
| 108 |
Unprocessed options can be collected into a macro (similar to |xkeyval|'s |
| 109 |
|\xkv@rm|), discarded or handled manually. The details of key selection and |
| 110 |
family declaration are described in the following sections. |
| 111 |
|
| 112 |
|
| 113 |
\subsubsection{Setting Filters} |
| 114 |
|
| 115 |
The command |\pgfkeysfiltered| is the main tool to process only selected |
| 116 |
options. It works as follows. |
| 117 |
% |
| 118 |
\begin{command}{\pgfkeysfiltered\marg{key--value-list}} |
| 119 |
Processes all options in exactly the same way as |
| 120 |
|\pgfkeys|\marg{key--value-list}, but a key filter is considered as soon as |
| 121 |
key identification is complete. |
| 122 |
|
| 123 |
The key filter tells |\pgfkeysfiltered| whether it should continue to apply |
| 124 |
the current option (return value is `true') or whether something different |
| 125 |
shall be done (filter returns `false'). |
| 126 |
|
| 127 |
There is exactly one key filter in effect, and it is installed by the |
| 128 |
|.install key filter| handler or by |\pgfkeysinstallkeyfilter|. |
| 129 |
|
| 130 |
If the key filter returns `false', a unique key filter handler gets |
| 131 |
control. This handler is installed by the |.install key filter handler| |
| 132 |
method and has access to the key's full name, value and (possibly) path. |
| 133 |
|
| 134 |
Key filtering applies to any (possibly nested) call to |\pgfkeys|, |
| 135 |
|\pgfkeysalso|, |\pgfqkeys| and |\pgfqkeysalso| during the evaluation of |
| 136 |
\marg{key--value-list}. It does \emph{not} apply to routines like |
| 137 |
|\pgfkeyssetvalue| or |\pgfkeysgetvalue|. Furthermore, keys belonging to |
| 138 |
|/errors| are always processed. Key filtering routines can't be nested: you |
| 139 |
can't combine different key filters automatically. |
| 140 |
\end{command} |
| 141 |
|
| 142 |
\begin{command}{\pgfqkeysfiltered\marg{default-path}\marg{key--value-list}} |
| 143 |
A variant of |\pgfkeysfiltered| which uses the `quick' search path setting. |
| 144 |
It is the |\pgfqkeys| variant of |\pgfkeysfiltered|, see the documentation |
| 145 |
for |\pgfqkeys| for more details. |
| 146 |
\end{command} |
| 147 |
|
| 148 |
\begin{command}{\pgfkeysalsofrom\marg{macro}} |
| 149 |
A variant of |\pgfkeysalso| which loads its key list from \marg{macro}. |
| 150 |
|
| 151 |
It is useful in conjunction with the |
| 152 |
|/pgf/key filter handlers/append filtered to=|\meta{macro} handler. |
| 153 |
|
| 154 |
The following example uses the same settings as in the intro |
| 155 |
section~\ref{section-key-filter-example}. |
| 156 |
% |
| 157 |
\begin{codeexample}[preamble={\usepgfkeyslibrary{filtered}}] |
| 158 |
\pgfkeys{/pgf/key filter handlers/append filtered to/.install key filter handler=\remainingoptions} |
| 159 |
\def\remainingoptions{} |
| 160 |
\pgfkeysfiltered{/my group/A1=a1, /my group/A2=a2, |
| 161 |
/my group/B=b, /my group/C=c, /tikz/color=blue, /my group/A3=a3} |
| 162 |
|
| 163 |
Remaining: `\remainingoptions'. |
| 164 |
\pgfkeysalsofrom{\remainingoptions} |
| 165 |
\end{codeexample} |
| 166 |
% |
| 167 |
\end{command} |
| 168 |
|
| 169 |
\begin{command}{\pgfkeysalsofiltered\marg{key--value-list}} |
| 170 |
This command works as |\pgfkeysfiltered|, but it does not change the |
| 171 |
current default path. See the documentation of |\pgfkeysalso| for more |
| 172 |
details. |
| 173 |
\end{command} |
| 174 |
|
| 175 |
\begin{command}{\pgfkeysalsofilteredfrom\marg{macro}} |
| 176 |
A variant of |\pgfkeysalsofiltered| which loads its key list from |
| 177 |
\marg{macro}. |
| 178 |
\end{command} |
| 179 |
|
| 180 |
\begin{handler}{{.install key filter}|=|\meta{optional arguments}} |
| 181 |
This handler installs a key filter. A key filter is a command key which |
| 182 |
sets the \TeX-boolean |\ifpgfkeysfiltercontinue|, that means a key with |
| 183 |
existing `|/.@cmd|' suffix. A simple example is a key filter which returns |
| 184 |
always true: |
| 185 |
% |
| 186 |
\begin{codeexample}[code only,preamble={\usepgfkeyslibrary{filtered}}] |
| 187 |
\pgfkeys{/foo/bar/true key filter/.code={\pgfkeysfiltercontinuetrue}} |
| 188 |
\pgfkeys{/foo/bar/true key filter/.install key filter} |
| 189 |
\end{codeexample} |
| 190 |
% |
| 191 |
If key filters require arguments, they are installed by |
| 192 |
|.install key filter| as well. An example is the |/pgf/key filters/equals| |
| 193 |
handler: |
| 194 |
% |
| 195 |
\begin{codeexample}[preamble={\usepgfkeyslibrary{filtered}}] |
| 196 |
\pgfkeys{/pgf/key filters/equals/.install key filter={/my group/A1}} |
| 197 |
\pgfkeysfiltered{/my group/A1=a1, /my group/A2=a2, |
| 198 |
/my group/B=b, /my group/C=c, /tikz/color=blue, /my group/A3=a3} |
| 199 |
\end{codeexample} |
| 200 |
% |
| 201 |
If a key filter requires more than one argument, you need to provide the |
| 202 |
complete argument list in braces like |{{first}{second}}|. |
| 203 |
|
| 204 |
You can also use |\pgfkeysinstallkeyfilter|\meta{full key}\meta{optional |
| 205 |
arguments}, it has the same effect. |
| 206 |
|
| 207 |
See section~\ref{section-key-writing-filters} for how to write key filters. |
| 208 |
\end{handler} |
| 209 |
|
| 210 |
\begin{handler}{{.install key filter handler}|=|\meta{optional arguments}} |
| 211 |
This handler installs the routine which will be invoked for every |
| 212 |
\emph{unprocessed} option, that means any option for which the key filter |
| 213 |
returned `false'. |
| 214 |
|
| 215 |
The |.install key filter handler| is used in the same way as |
| 216 |
|.install key filter|. There exists a macro version, |
| 217 |
|\pgfkeysinstallkeyfilterhandler|\meta{full key}\meta{optional arguments}, |
| 218 |
which has the same effect. |
| 219 |
|
| 220 |
See section~\ref{section-key-writing-filters} for how to write key filter |
| 221 |
handlers. |
| 222 |
\end{handler} |
| 223 |
|
| 224 |
|
| 225 |
\subsubsection{Handlers For Unprocessed Keys} |
| 226 |
|
| 227 |
Each option for which key filters decided to skip them is handed over to a `key |
| 228 |
filter handler'. There are several predefined key filter handlers. |
| 229 |
|
| 230 |
\begin{key}{/pgf/key filter handlers/append filtered to=\marg{macro}} |
| 231 |
Install this filter handler to append any unprocessed options to macro |
| 232 |
\marg{macro}. |
| 233 |
% |
| 234 |
\begin{codeexample}[preamble={\usepgfkeyslibrary{filtered}}] |
| 235 |
\pgfkeys{/pgf/key filter handlers/append filtered to/.install key filter handler=\remainingoptions} |
| 236 |
\def\remainingoptions{} |
| 237 |
\pgfkeysfiltered{/my group/A1=a1, /my group/A2=a2, |
| 238 |
/my group/B=b, /my group/C=c, /tikz/color=blue} |
| 239 |
|
| 240 |
Remaining options: `\remainingoptions'. |
| 241 |
\end{codeexample} |
| 242 |
% |
| 243 |
This example uses the same keys as defined in the intro |
| 244 |
section~\ref{section-key-filter-example}. |
| 245 |
\end{key} |
| 246 |
|
| 247 |
\begin{key}{/pgf/key filter handlers/ignore} |
| 248 |
Install this filter handler if you simply want to ignore any unprocessed |
| 249 |
option. This is the default. |
| 250 |
\end{key} |
| 251 |
|
| 252 |
\begin{key}{/pgf/key filter handlers/log} |
| 253 |
This key filter handler writes messages for any unprocessed option to your |
| 254 |
logfile (and terminal). |
| 255 |
\end{key} |
| 256 |
|
| 257 |
|
| 258 |
\subsubsection{Family Support} |
| 259 |
|
| 260 |
\pgfname{} supports a family concept: every option can be associated with (at |
| 261 |
most) one family. Families form loose key groups which are independent of the |
| 262 |
key hierarchy. For example, |/my tree/key1| can belong to family |/tikz|. |
| 263 |
|
| 264 |
It is possible to `activate' or `deactivate' single families. Furthermore, it |
| 265 |
is possible to set only keys which belong to active families using appropriate |
| 266 |
key filter handlers. |
| 267 |
|
| 268 |
The family support is fast: if there are $N$ options in a key--value-list and |
| 269 |
there are $K$ active families, the runtime for |\pgfkeysfiltered| is $O(N+K)$ |
| 270 |
(activate every family $O(K)$, check every option $O(N)$, deactivate every |
| 271 |
family $O(K)$). |
| 272 |
|
| 273 |
\begin{handler}{{.is family}} |
| 274 |
Defines a new family. This option has already been described in |
| 275 |
section~\ref{section-is family-handler} on page~\pageref{section-is |
| 276 |
family-handler}. |
| 277 |
\end{handler} |
| 278 |
|
| 279 |
\begin{handler}{{.activate family}} |
| 280 |
Activates a family. The family needs to be defined, otherwise |
| 281 |
|/errors/family unknown| will be raised. |
| 282 |
|
| 283 |
Activation means a \TeX-boolean will be set to |true|, indicating that a |
| 284 |
family should be processed. |
| 285 |
|
| 286 |
You can also use |\pgfkeysactivatefamily|\meta{full path} to get the same |
| 287 |
effect. Furthermore, you can use |\pgfkeysactivatefamilies|\meta{list of |
| 288 |
families}\meta{macro name for de-activation} to activate a list of families |
| 289 |
(see section~\ref{section-key-filter-api}). |
| 290 |
\end{handler} |
| 291 |
|
| 292 |
\begin{handler}{{.deactivate family}} |
| 293 |
Deactivates a family. The family needs to be defined, otherwise |
| 294 |
|/errors/family unknown| will be raised. |
| 295 |
|
| 296 |
You can also use |\pgfkeysdeactivatefamily|\meta{full path} to get the same |
| 297 |
effect. |
| 298 |
\end{handler} |
| 299 |
|
| 300 |
\begin{handler}{{.belongs to family}|=|\marg{family name}} |
| 301 |
Associates the current option with \marg{family name}, which is expected to |
| 302 |
be a full path of a family. |
| 303 |
% |
| 304 |
\begin{codeexample}[code only,preamble={\usepgfkeyslibrary{filtered}}] |
| 305 |
\pgfkeys{/foo/bar/.is family} |
| 306 |
\pgfkeys{ |
| 307 |
/foo/a/.belongs to family=/foo/bar, |
| 308 |
/foo/b/.belongs to family=/foo/bar |
| 309 |
} |
| 310 |
\end{codeexample} |
| 311 |
% |
| 312 |
Each option can have up to one family, |.belongs to family| overwrites any |
| 313 |
old setting. |
| 314 |
\end{handler} |
| 315 |
|
| 316 |
\begin{key}{/pgf/key filters/active families} |
| 317 |
Install this key filter if |\pgfkeysfiltered| should only process activated |
| 318 |
families. If a key does not belong to any family, it is not processed. If a |
| 319 |
key is completely unknown within the default path, the normal `unknown' |
| 320 |
handlers of |\pgfkeys| are invoked. |
| 321 |
\end{key} |
| 322 |
|
| 323 |
\begin{key}{/pgf/key filters/active families or no family=\marg{key filter 1}\marg{key filter 2}} |
| 324 |
This key filter configures |\pgfkeysfiltered| to work as follows. |
| 325 |
% |
| 326 |
\begin{enumerate} |
| 327 |
\item If the current key belongs to a family, set |
| 328 |
|\ifpgfkeysfiltercontinue| to true if and only if its family is |
| 329 |
active. |
| 330 |
\item If the current key does \emph{not} belong to a family, assign |
| 331 |
|\ifpgfkeysfiltercontinue| as result of \marg{key filter 1}. |
| 332 |
\item If the current key is unknown within the default path, assign |
| 333 |
|\ifpgfkeysfiltercontinue| as result of \marg{key filter 2}. |
| 334 |
\end{enumerate} |
| 335 |
% |
| 336 |
The arguments \marg{key filter 1} and \marg{key filter 2} are other key |
| 337 |
filters (possibly with options) and allow fine-grained control over the |
| 338 |
filtering process. |
| 339 |
% |
| 340 |
\begin{codeexample}[code only,preamble={\usepgfkeyslibrary{filtered}}] |
| 341 |
\pgfkeysinstallkeyfilter |
| 342 |
{/pgf/key filters/active families or no family} |
| 343 |
{{/pgf/key filters/is descendant of=/tikz}% for keys without family |
| 344 |
{/pgf/key filters/false}% for unknown keys |
| 345 |
}% |
| 346 |
\end{codeexample} |
| 347 |
% |
| 348 |
This key filter will return true for any option with active family. If an |
| 349 |
option has no family, the return value is true if and only if it belongs to |
| 350 |
|/tikz|. If the option is unknown, the return value is |false| and unknown |
| 351 |
handlers won't be called. |
| 352 |
\end{key} |
| 353 |
|
| 354 |
\begin{key}{/pgf/key filters/active families or no family DEBUG=\marg{key filter 1}\marg{key filter 2}} |
| 355 |
A variant of |active families or no family| which protocols each action on |
| 356 |
your terminal (log-file). |
| 357 |
\end{key} |
| 358 |
|
| 359 |
\begin{key}{/pgf/key filters/active families and known} |
| 360 |
A fast alias for |
| 361 |
|
| 362 |
|/pgf/key filters/active families or no family=|\par |
| 363 |
\noindent\hskip10pt|{/pgf/keys filters/false}|\par |
| 364 |
\noindent\hskip10pt|{/pgf/keys filters/false}|. |
| 365 |
\end{key} |
| 366 |
% |
| 367 |
\begin{key}{/pgf/key filters/active families or descendants of=\marg{path prefix}} |
| 368 |
A fast alias for |
| 369 |
|
| 370 |
|/pgf/key filters/active families or no family=|\par |
| 371 |
\noindent\hskip10pt|{/pgf/keys filters/is descendant of=|\marg{path prefix}|}|\par |
| 372 |
\noindent\hskip10pt|{/pgf/keys filters/false}|. |
| 373 |
\end{key} |
| 374 |
|
| 375 |
\begin{command}{\pgfkeysactivatefamiliesandfilteroptions\marg{family list}\marg{key--value-list}} |
| 376 |
A simple shortcut macro which activates any family in the comma separated |
| 377 |
\marg{family list}, invokes |\pgfkeysfiltered|\meta{key--value-list} and |
| 378 |
deactivates the families afterwards. |
| 379 |
|
| 380 |
Please note that you will need to install a family key filter, otherwise |
| 381 |
family activation has no effect. |
| 382 |
\end{command} |
| 383 |
% |
| 384 |
\begin{command}{\pgfqkeysactivatefamiliesandfilteroptions\marg{family list}\marg{default path}\marg{key--value-list}} |
| 385 |
The `quick' default path variant of |\pgfkeysactivatefamiliesandfilteroptions|. |
| 386 |
\end{command} |
| 387 |
|
| 388 |
\begin{command}{\pgfkeysactivatesinglefamilyandfilteroptions\marg{family name}\marg{key--value-list}} |
| 389 |
A shortcut macro which activates a single family and invokes |\pgfkeysfiltered|. |
| 390 |
|
| 391 |
Please note that you will need to install a family key filter, otherwise |
| 392 |
family activation has no effect. |
| 393 |
\end{command} |
| 394 |
% |
| 395 |
\begin{command}{\pgfqkeysactivatesinglefamilyandfilteroptions\marg{family name}\marg{default path}\marg{key--value-list}}% |
| 396 |
The `quick' default path variant of |\pgfkeysactivatesinglefamilyandfilteroptions|. |
| 397 |
\end{command} |
| 398 |
|
| 399 |
|
| 400 |
\subsubsection{Other Key Filters} |
| 401 |
|
| 402 |
There are some more key filters which have nothing to do with family handling. |
| 403 |
% |
| 404 |
\begin{key}{/pgf/key filters/is descendant of=\marg{path}} |
| 405 |
Install this key filter to process only options belonging to the key tree |
| 406 |
\meta{path}. It returns true for every key whose key path is equal to |
| 407 |
\meta{path}. It also returns true for any unknown key, that means unknown |
| 408 |
keys are processed using the standard unknown handlers of \pgfname. |
| 409 |
% |
| 410 |
\begin{codeexample}[preamble={\usepgfkeyslibrary{filtered}}] |
| 411 |
\pgfkeys{ |
| 412 |
/group 1/A/.code={(A:#1)}, |
| 413 |
/group 1/foo/bar/B/.code={(B:#1)}, |
| 414 |
/group 2/C/.code={(C:#1)}, |
| 415 |
/pgf/key filters/is descendant of/.install key filter=/group 1} |
| 416 |
\pgfkeysfiltered{/group 1/A=a,/group 1/foo/bar/B=b,/group 2/C=c} |
| 417 |
\end{codeexample} |
| 418 |
% |
| 419 |
\end{key} |
| 420 |
|
| 421 |
\begin{key}{/pgf/key filters/equals=\marg{full key}} |
| 422 |
Install this key filter to process only the fully qualified option |
| 423 |
\marg{full key}. The filter returns true for any unknown key or if the key |
| 424 |
equals \marg{full key}. |
| 425 |
% |
| 426 |
\begin{codeexample}[preamble={\usepgfkeyslibrary{filtered}}] |
| 427 |
\pgfkeys{ |
| 428 |
/group 1/A/.code={(A:#1)}, |
| 429 |
/group 1/B/.code={(B:#1)}, |
| 430 |
/pgf/key filters/equals/.install key filter=/group 1/A} |
| 431 |
\pgfqkeysfiltered{/group 1}{A=a,B=b} |
| 432 |
\end{codeexample} |
| 433 |
% |
| 434 |
\end{key} |
| 435 |
|
| 436 |
\begin{key}{/pgf/key filters/not=\marg{key filter}} |
| 437 |
This key filter logically inverts the result of \marg{key filter}. |
| 438 |
% |
| 439 |
\begin{codeexample}[preamble={\usepgfkeyslibrary{filtered}}] |
| 440 |
\pgfkeys{ |
| 441 |
/group 1/A/.code={(A:#1)}, |
| 442 |
/group 1/foo/bar/B/.code={(B:#1)}, |
| 443 |
/group 2/C/.code={(C:#1)}, |
| 444 |
/pgf/key filters/not/.install key filter= |
| 445 |
{/pgf/key filters/is descendant of=/group 1}} |
| 446 |
\pgfkeysfiltered{/group 1/A=a,/group 1/foo/bar/B=b,/group 2/C=c} |
| 447 |
\end{codeexample} |
| 448 |
% |
| 449 |
Please note that unknown keys will be handed to the usual unknown handlers. |
| 450 |
\end{key} |
| 451 |
|
| 452 |
\begin{key}{/pgf/key filters/and=\marg{key filter 1}\marg{key filter 2}} |
| 453 |
This key filter returns true if and only if both, \marg{key filter 1} and |
| 454 |
\marg{key filter 2} return true. |
| 455 |
\end{key} |
| 456 |
|
| 457 |
\begin{key}{/pgf/key filters/or=\marg{key filter 1}\marg{key filter 2}} |
| 458 |
This key filter returns true if one of \marg{key filter 1} and \marg{key |
| 459 |
filter 2} returns true. |
| 460 |
\end{key} |
| 461 |
|
| 462 |
\begin{key}{/pgf/key filters/true} |
| 463 |
This key filter returns always true. |
| 464 |
\end{key} |
| 465 |
|
| 466 |
\begin{key}{/pgf/key filters/false} |
| 467 |
This key filter returns always false (including unknown keys). |
| 468 |
\end{key} |
| 469 |
|
| 470 |
\begin{key}{/pgf/key filters/defined} |
| 471 |
This key filter returns false if the current key is unknown, which avoids |
| 472 |
calling the unknown handlers. |
| 473 |
\end{key} |
| 474 |
|
| 475 |
|
| 476 |
\subsubsection{Programmer Interface} |
| 477 |
\label{section-key-filter-api} |
| 478 |
|
| 479 |
\begin{plainenvironment}{{pgfkeysinterruptkeyfilter}} |
| 480 |
Temporarily disables key filtering inside the environment. If key filtering |
| 481 |
is not active, this has no effect at all. |
| 482 |
|
| 483 |
Please note that no \TeX-group is introduced. |
| 484 |
\end{plainenvironment} |
| 485 |
|
| 486 |
\begin{command}{\pgfkeyssavekeyfilterstateto\marg{macro}} |
| 487 |
Creates \marg{macro} which contains commands to re-activate the current key |
| 488 |
filter and key filter handler. It can be used to temporarily switch the key |
| 489 |
filter. |
| 490 |
\end{command} |
| 491 |
|
| 492 |
\begin{command}{\pgfkeysinstallkeyfilter\marg{full key}\marg{optional arguments}} |
| 493 |
The command |
| 494 |
|\pgfkeysinstallkeyfilter{|\meta{full key}|}{|\meta{optional arguments}|}| |
| 495 |
has the same effect as |
| 496 |
|\pgfkeys{|\meta{full key}|/.install key filter={|\meta{optional arguments}|}}|. |
| 497 |
\end{command} |
| 498 |
|
| 499 |
\begin{command}{\pgfkeysinstallkeyfilterhandler\marg{full key}\marg{optional arguments}} |
| 500 |
The command |
| 501 |
|\pgfkeysinstallkeyfilterhandler{|\meta{full key}|}{|\meta{optional arguments}|}| |
| 502 |
has the same effect as |
| 503 |
|\pgfkeys{|\meta{full key}|/.install key filter handler={|\meta{optional arguments}|}}|. |
| 504 |
\end{command} |
| 505 |
|
| 506 |
\begin{command}{\pgfkeysactivatefamily\marg{family name}} |
| 507 |
Equivalent to |\pgfkeys{|\meta{family name}|/.activate family}|. |
| 508 |
\end{command} |
| 509 |
|
| 510 |
\begin{command}{\pgfkeysdeactivatefamily\marg{family name}} |
| 511 |
Equivalent to |\pgfkeys{|\meta{family name}|/.deactivate family}|. |
| 512 |
\end{command} |
| 513 |
|
| 514 |
\begin{command}{\pgfkeysactivatefamilies\marg{family list}\marg{deactivate macro name}} |
| 515 |
Activates each family in \meta{family list} and creates a macro |
| 516 |
\meta{deactivate macro name} which deactivates each family in \meta{family |
| 517 |
list}. |
| 518 |
% |
| 519 |
\begin{codeexample}[code only,preamble={\usepgfkeyslibrary{filtered}}] |
| 520 |
\pgfkeysactivatefamilies{/family 1,/family 2,/family 3}{\deactivatename} |
| 521 |
\pgfkeysfiltered{foo,bar} |
| 522 |
\deactivatename |
| 523 |
\end{codeexample} |
| 524 |
% |
| 525 |
\end{command} |
| 526 |
|
| 527 |
\begin{command}{\pgfkeysiffamilydefined\marg{family}\marg{true case}\marg{false case}}% |
| 528 |
Checks whether the full key \meta{family} is a family and executes either |
| 529 |
\meta{true case} or \meta{false case}. |
| 530 |
\end{command} |
| 531 |
|
| 532 |
\begin{command}{\pgfkeysisfamilyactive\marg{family}} |
| 533 |
Sets the \TeX-boolean |\ifpgfkeysfiltercontinue| to whether \meta{family} |
| 534 |
is active or not. |
| 535 |
\end{command} |
| 536 |
|
| 537 |
\begin{command}{\pgfkeysgetfamily\marg{full key}\marg{resultmacro}} |
| 538 |
Returns the family associated to a \meta{full key} into macro |
| 539 |
\meta{resultmacro}. |
| 540 |
\end{command} |
| 541 |
|
| 542 |
\begin{command}{\pgfkeyssetfamily\marg{full key}\marg{family}} |
| 543 |
The command |\pgfkeyssetfamily|\marg{full key}\marg{family} has the same |
| 544 |
effect as |\pgfkeys{|\meta{full key}|/.belongs to family=|\marg{family}|}|. |
| 545 |
\end{command} |
| 546 |
|
| 547 |
|
| 548 |
\subsubsection{Defining Own Filters Or Filter Handlers} |
| 549 |
\label{section-key-writing-filters} |
| 550 |
|
| 551 |
During |\pgfkeysfiltered|, the key filter code will be invoked. At this time, |
| 552 |
the full key path including key name is available as |\pgfkeyscurrentkey|, the |
| 553 |
key name before default paths have been considered as |\pgfkeyscurrentkeyRAW| |
| 554 |
and the values as |\pgfkeyscurrentvalue|. |
| 555 |
|
| 556 |
Furthermore, the macro |\pgfkeyscasenumber| contains the current key's type as |
| 557 |
an integer: |
| 558 |
% |
| 559 |
\begin{itemize} |
| 560 |
\item[\meta{1}] The key is a command key (i.e.\ |.../.@cmd| exists). |
| 561 |
\item[\meta{2}] The key contains its value directly. |
| 562 |
\item[\meta{3}] The key is handled (for example it is |.code| or |.cd|). |
| 563 |
|
| 564 |
In this case, the macros |\pgfkeyscurrentname| and |
| 565 |
|\pgfkeyscurrentpath| are set to the handlers name and path, |
| 566 |
respectively. Invoke |\pgfkeyssplitpath{}| to extract these values for |
| 567 |
non-handled keys. |
| 568 |
\item[\meta{0}] The key is unknown. |
| 569 |
\end{itemize} |
| 570 |
% |
| 571 |
Any key filter or key filter handler can access these variables. Key filters |
| 572 |
are expected to set the \TeX-boolean |\ifpgfkeysfiltercontinue| to whether the |
| 573 |
current key shall be processed or not. |
| 574 |
|
| 575 |
\begin{command}{\pgfkeysevalkeyfilterwith\marg{full key}=\marg{filter arguments}} |
| 576 |
Evaluates a fully qualified key filter \meta{full key} with argument(s) |
| 577 |
\meta{filter arguments}. |
| 578 |
% |
| 579 |
\begin{codeexample}[code only,preamble={\usepgfkeyslibrary{filtered}}] |
| 580 |
\pgfkeysevalkeyfilterwith{/pgf/key filters/equals=/tikz} |
| 581 |
\end{codeexample} |
| 582 |
% |
| 583 |
\end{command} |
| 584 |
|
| 585 |
\endgroup |