| 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[Hierarchical Structures: Package, Environments, Scopes, and Styles] |
| 12 |
{Hierarchical Structures:\\ |
| 13 |
Package, Environments, Scopes, and Styles} |
| 14 |
|
| 15 |
The present section explains how your files should be structured when you use |
| 16 |
\tikzname. On the top level, you need to include the |tikz| package. In the |
| 17 |
main text, each graphic needs to be put in a |{tikzpicture}| environment. |
| 18 |
Inside these environments, you can use |{scope}| environments to create |
| 19 |
internal groups. Inside the scopes you use |\path| commands to actually draw |
| 20 |
something. On all levels (except for the package level), graphic options can be |
| 21 |
given that apply to everything within the environment. |
| 22 |
|
| 23 |
|
| 24 |
\subsection{Loading the Package and the Libraries} |
| 25 |
|
| 26 |
\begin{package}{tikz} |
| 27 |
This package does not have any options. |
| 28 |
|
| 29 |
This will automatically load the \pgfname\ and the |pgffor| package. |
| 30 |
|
| 31 |
\pgfname\ needs to know what \TeX\ driver you are intending to use. In most |
| 32 |
cases \pgfname\ is clever enough to determine the correct driver for you; |
| 33 |
this is true in particular if you use \LaTeX. One situation where \pgfname\ |
| 34 |
cannot know the driver ``by itself'' is when you use plain \TeX\ or Con\TeX |
| 35 |
t together with |dvipdfm|. In this case, you have to write |
| 36 |
|\def\pgfsysdriver{pgfsys-dvipdfm.def}| \emph{before} you input |tikz.tex|. |
| 37 |
\end{package} |
| 38 |
|
| 39 |
\begin{command}{\usetikzlibrary\marg{list of libraries}} |
| 40 |
Once \tikzname\ has been loaded, you can use this command to load further |
| 41 |
libraries. The list of libraries should contain the names of libraries |
| 42 |
separated by commas. Instead of curly braces, you can also use square |
| 43 |
brackets, which is something Con\TeX t users will like. If you try to load |
| 44 |
a library a second time, nothing will happen. |
| 45 |
|
| 46 |
\example |\usetikzlibrary{arrows.meta}| |
| 47 |
|
| 48 |
The above command will load a whole bunch of extra arrow tip definitions. |
| 49 |
|
| 50 |
What this command does is to load the file |
| 51 |
|tikzlibrary|\meta{library}|.code.tex| for each \meta{library} in the |
| 52 |
\meta{list of libraries}. If this file does not exist, the file |
| 53 |
|pgflibrary|\meta{library}|.code.tex| is loaded instead. If this file also |
| 54 |
does not exist, an error message is printed. Thus, to write your own |
| 55 |
library file, all you need to do is to place a file of the appropriate name |
| 56 |
somewhere where \TeX\ can find it. \LaTeX, plain \TeX, and Con\TeX t users |
| 57 |
can then use your library. |
| 58 |
\end{command} |
| 59 |
|
| 60 |
|
| 61 |
\subsection{Creating a Picture} |
| 62 |
|
| 63 |
\subsubsection{Creating a Picture Using an Environment} |
| 64 |
|
| 65 |
The ``outermost'' scope of \tikzname\ is the |{tikzpicture}| environment. You |
| 66 |
may give drawing commands only inside this environment, giving them outside (as |
| 67 |
is possible in many other packages) will result in chaos. |
| 68 |
|
| 69 |
In \tikzname, the way graphics are rendered is strongly influenced by graphic |
| 70 |
options. For example, there is an option for setting the color used for |
| 71 |
drawing, another for setting the color used for filling, and also more obscure |
| 72 |
ones like the option for setting the prefix used in the filenames of temporary |
| 73 |
files written while plotting functions using an external program. The graphic |
| 74 |
options are specified in \emph{key lists}, see |
| 75 |
Section~\ref{section-graphic-options} below for details. All graphic options |
| 76 |
are local to the |{tikzpicture}| to which they apply. |
| 77 |
|
| 78 |
\begin{environment}{{tikzpicture}\opt{\meta{animations spec}}\opt{\oarg{options}}} |
| 79 |
All \tikzname\ commands should be given inside this environment, except for |
| 80 |
the |\tikzset| command. You cannot use graphics commands like the low-level |
| 81 |
command |\pgfpathmoveto| outside this environment and doing so will result |
| 82 |
in chaos. For \tikzname, commands like |\path| are only defined inside this |
| 83 |
environment, so there is little chance that you will do something wrong |
| 84 |
here. |
| 85 |
|
| 86 |
When this environment is encountered, the \meta{options} are parsed, see |
| 87 |
Section~\ref{section-graphic-options}. All options given here will apply to |
| 88 |
the whole picture. Before the options you can specify animation commands, |
| 89 |
provided that the |animations| library is loaded, see |
| 90 |
Section~\ref{section-tikz-animations} for details. |
| 91 |
|
| 92 |
Next, the contents of the environment is processed and the graphic commands |
| 93 |
therein are put into a box. Non-graphic text is suppressed as well as |
| 94 |
possible, but non-\pgfname\ commands inside a |{tikzpicture}| environment |
| 95 |
should not produce any ``output'' since this may totally scramble the |
| 96 |
positioning system of the backend drivers. The suppressing of normal text, |
| 97 |
by the way, is done by temporarily switching the font to |\nullfont|. You |
| 98 |
can, however, ``escape back'' to normal \TeX\ typesetting. This happens, |
| 99 |
for example, when you specify a node. |
| 100 |
|
| 101 |
At the end of the environment, \pgfname\ tries to make a good guess at the |
| 102 |
size of a bounding box of the graphic and then resizes the picture box such |
| 103 |
that the box has this size. To ``make its guess'', every time \pgfname\ |
| 104 |
encounters a coordinate, it updates the bounding box's size such that it |
| 105 |
encompasses all these coordinates. This will usually give a good |
| 106 |
approximation of the bounding box, but will not always be accurate. First, |
| 107 |
the line thickness of diagonal lines is not taken into account correctly. |
| 108 |
Second, control points of a curve often lie far ``outside'' the curve and |
| 109 |
make the bounding box too large. In this case, you should use the |
| 110 |
|[use as bounding box]| option. |
| 111 |
|
| 112 |
The following key influences the baseline of the resulting picture: |
| 113 |
% |
| 114 |
\begin{key}{/tikz/baseline=\meta{dimension or coordinate or \texttt{default}} (default 0pt)} |
| 115 |
Normally, the lower end of the picture is put on the baseline of the |
| 116 |
surrounding text. For example, when you give the code |
| 117 |
|\tikz\draw(0,0)circle(.5ex);|, \pgfname\ will find out that the lower |
| 118 |
end of the picture is at $-.5\mathrm{ex} - 0.2\mathrm{pt}$ (the 0.2pt |
| 119 |
are half the line width, which is 0.4pt) and that the upper end is at |
| 120 |
$.5\mathrm{ex}+.2\mathrm{pt}$. Then, the lower end will be put on the |
| 121 |
baseline, resulting in the following: \tikz\draw(0,0)circle(.5ex);. |
| 122 |
|
| 123 |
Using this option, you can specify that the picture should be raised or |
| 124 |
lowered such that the height \meta{dimension} is on the baseline. For |
| 125 |
example, |\tikz[baseline=0pt]\draw(0,0)circle(.5ex);| yields |
| 126 |
\tikz[baseline=0pt]\draw(0,0)circle(.5ex); since, now, the baseline is |
| 127 |
on the height of the $x$-axis. |
| 128 |
|
| 129 |
This options is often useful for ``inlined'' graphics as in |
| 130 |
% |
| 131 |
\begin{codeexample}[] |
| 132 |
$A \mathbin{\tikz[baseline] \draw[->>] (0pt,.5ex) -- (3ex,.5ex);} B$ |
| 133 |
\end{codeexample} |
| 134 |
|
| 135 |
Instead of a \meta{dimension} you can also provide a coordinate in |
| 136 |
parentheses. Then the effect is to put the baseline on the |
| 137 |
$y$-coordinate that the given \meta{coordinate} has \emph{at the end of |
| 138 |
the picture}. This means that, at the end of the picture, the |
| 139 |
\meta{coordinate} is evaluated and then the baseline is set to the |
| 140 |
$y$-coordinate of the resulting point. This makes it easy to reference |
| 141 |
the $y$-coordinate of, say, the baseline of nodes. |
| 142 |
% |
| 143 |
\begin{codeexample}[preamble={\usetikzlibrary{shapes.misc}}] |
| 144 |
Hello |
| 145 |
\tikz[baseline=(X.base)] |
| 146 |
\node [cross out,draw] (X) {world.}; |
| 147 |
\end{codeexample} |
| 148 |
|
| 149 |
\begin{codeexample}[] |
| 150 |
Top align: |
| 151 |
\tikz[baseline=(current bounding box.north)] |
| 152 |
\draw (0,0) rectangle (1cm,1ex); |
| 153 |
\end{codeexample} |
| 154 |
|
| 155 |
Use |baseline=default| to reset the |baseline| option to its initial |
| 156 |
configuration. |
| 157 |
\end{key} |
| 158 |
|
| 159 |
\begin{key}{/tikz/execute at begin picture=\meta{code}} |
| 160 |
This option causes \meta{code} to be executed at the beginning of the |
| 161 |
picture. This option must be given in the argument of the |
| 162 |
|{tikzpicture}| environment itself since this option will not have an |
| 163 |
effect otherwise. After all, the picture has already ``started'' later |
| 164 |
on. The effect of multiply setting this option accumulates. |
| 165 |
|
| 166 |
This option is mainly used in styles like the |every picture| style to |
| 167 |
execute certain code at the start of a picture. |
| 168 |
\end{key} |
| 169 |
|
| 170 |
\begin{key}{/tikz/execute at end picture=\meta{code}} |
| 171 |
This option installs \meta{code} that will be executed at the end of |
| 172 |
the picture. Using this option multiple times will cause the code to |
| 173 |
accumulate. This option must also be given in the optional argument of |
| 174 |
the |{tikzpicture}| environment. |
| 175 |
% |
| 176 |
\begin{codeexample}[preamble={\usetikzlibrary{backgrounds}}] |
| 177 |
\begin{tikzpicture}[execute at end picture=% |
| 178 |
{ |
| 179 |
\begin{pgfonlayer}{background} |
| 180 |
\path[fill=yellow,rounded corners] |
| 181 |
(current bounding box.south west) rectangle |
| 182 |
(current bounding box.north east); |
| 183 |
\end{pgfonlayer} |
| 184 |
}] |
| 185 |
\node at (0,0) {X}; |
| 186 |
\node at (2,1) {Y}; |
| 187 |
\end{tikzpicture} |
| 188 |
\end{codeexample} |
| 189 |
\end{key} |
| 190 |
|
| 191 |
All options ``end'' at the end of the picture. To set an option |
| 192 |
``globally'' change the following style: |
| 193 |
% |
| 194 |
\begin{stylekey}{/tikz/every picture (initially \normalfont empty)} |
| 195 |
This style is installed at the beginning of each picture. |
| 196 |
% |
| 197 |
\begin{codeexample}[code only] |
| 198 |
\tikzset{every picture/.style=semithick} |
| 199 |
\end{codeexample} |
| 200 |
\end{stylekey} |
| 201 |
|
| 202 |
Note that you should not use |\tikzset| to set options directly. For |
| 203 |
instance, if you want to use a line width of |1pt| by default, do not try |
| 204 |
to say |\tikzset{line width=1pt}| at the beginning of your document. This |
| 205 |
will not work since the line width is changed in many places. Instead, say |
| 206 |
% |
| 207 |
\begin{codeexample}[code only] |
| 208 |
\tikzset{every picture/.style={line width=1pt}} |
| 209 |
\end{codeexample} |
| 210 |
% |
| 211 |
This will have the desired effect. |
| 212 |
\end{environment} |
| 213 |
|
| 214 |
In other \TeX\ formats, you should use the following commands instead: |
| 215 |
|
| 216 |
\begin{plainenvironment}{{tikzpicture}\opt{\oarg{options}}} |
| 217 |
This is the plain \TeX\ version of the environment. |
| 218 |
\end{plainenvironment} |
| 219 |
|
| 220 |
\begin{contextenvironment}{{tikzpicture}\opt{\oarg{options}}} |
| 221 |
This is the Con\TeX t version of the environment. |
| 222 |
\end{contextenvironment} |
| 223 |
|
| 224 |
|
| 225 |
\subsubsection{Creating a Picture Using a Command} |
| 226 |
|
| 227 |
The following command is an alternative to |{tikzpicture}| that is particular |
| 228 |
useful for graphics consisting of a single or few commands. |
| 229 |
|
| 230 |
\begin{command}{\tikz\opt{\meta{animations spec}}\opt{\oarg{options}}\marg{path commands}} |
| 231 |
This command places the \meta{path commands} inside a |{tikzpicture}| |
| 232 |
environment. The \meta{path commands} may contain paragraphs and fragile |
| 233 |
material (like verbatim text). |
| 234 |
|
| 235 |
If there is only one path command, it need not be surrounded by curly |
| 236 |
braces, if there are several, you need to add them (this is similar to the |
| 237 |
|\foreach| statement and also to the rules in programming languages like |
| 238 |
Java or C concerning the placement of curly braces). |
| 239 |
|
| 240 |
\example |\tikz{\draw (0,0) rectangle (2ex,1ex);}| yields |
| 241 |
\tikz{\draw (0,0) rectangle (2ex,1ex);} |
| 242 |
|
| 243 |
\example |\tikz \draw (0,0) rectangle (2ex,1ex);| yields |
| 244 |
\tikz \draw (0,0) rectangle (2ex,1ex); |
| 245 |
\end{command} |
| 246 |
|
| 247 |
|
| 248 |
\subsubsection{Handling Catcodes and the Babel Package} |
| 249 |
|
| 250 |
Inside a \tikzname\ picture, most symbols need to have the category code 12 |
| 251 |
(normal text) in order to ensure that the parser works properly. This is |
| 252 |
typically not the case when packages like |babel| are used, which change |
| 253 |
catcodes aggressively. |
| 254 |
|
| 255 |
To solve this problem, \tikzname\ provides a small library also called |babel| |
| 256 |
(which can, however, also be used together with any other package that globally |
| 257 |
changes category codes). What it does is to reset the category codes at the |
| 258 |
beginning of every |{tikzpicture}| and to restore them at the beginning of |
| 259 |
every node. In almost all cases, this is exactly what you would expect and |
| 260 |
need, so I recommend to always load this library by saying |
| 261 |
|\usetikzlibrary{babel}|. For details on what, exactly, happens with the |
| 262 |
category codes, see Section~\ref{section-library-babel}. |
| 263 |
|
| 264 |
|
| 265 |
\subsubsection{Adding a Background} |
| 266 |
|
| 267 |
By default, pictures do not have any background, that is, they are |
| 268 |
``transparent'' on all parts on which you do not draw anything. You may instead |
| 269 |
wish to have a colored background behind your picture or a black frame around |
| 270 |
it or lines above and below it or some other kind of decoration. |
| 271 |
|
| 272 |
Since backgrounds are often not needed at all, the definition of styles for |
| 273 |
adding backgrounds has been put in the library package |backgrounds|. This |
| 274 |
package is documented in Section~\ref{section-tikz-backgrounds}. |
| 275 |
|
| 276 |
|
| 277 |
\subsection{Using Scopes to Structure a Picture} |
| 278 |
|
| 279 |
Inside a |{tikzpicture}| environment you can create scopes using the |{scope}| |
| 280 |
environment. This environment is available only inside the |{tikzpicture}| |
| 281 |
environment, so once more, there is little chance of doing anything wrong. |
| 282 |
|
| 283 |
|
| 284 |
\subsubsection{The Scope Environment} |
| 285 |
|
| 286 |
\begin{environment}{{scope}\opt{\meta{animations spec}}\opt{\oarg{options}}} |
| 287 |
All \meta{options} are local to the \meta{environment contents}. |
| 288 |
Furthermore, the clipping path is also local to the environment, that is, |
| 289 |
any clipping done inside the environment ``ends'' at its end. |
| 290 |
% |
| 291 |
\begin{codeexample}[] |
| 292 |
\begin{tikzpicture}[ultra thick] |
| 293 |
\begin{scope}[red] |
| 294 |
\draw (0mm,10mm) -- (10mm,10mm); |
| 295 |
\draw (0mm,8mm) -- (10mm,8mm); |
| 296 |
\end{scope} |
| 297 |
\draw (0mm,6mm) -- (10mm,6mm); |
| 298 |
\begin{scope}[green] |
| 299 |
\draw (0mm,4mm) -- (10mm,4mm); |
| 300 |
\draw (0mm,2mm) -- (10mm,2mm); |
| 301 |
\draw[blue] (0mm,0mm) -- (10mm,0mm); |
| 302 |
\end{scope} |
| 303 |
\end{tikzpicture} |
| 304 |
\end{codeexample} |
| 305 |
|
| 306 |
\begin{key}{/tikz/name=\meta{scope name}} |
| 307 |
Assigns a name to a scope reference in animations. The name is a |
| 308 |
``high-level'' name that drivers do not see, so you can use spaces, |
| 309 |
number, letters, in a name, but you should \emph{not} use any |
| 310 |
punctuation like a dot, a comma, or a colon. |
| 311 |
\end{key} |
| 312 |
|
| 313 |
The following style influences scopes: |
| 314 |
% |
| 315 |
\begin{stylekey}{/tikz/every scope (initially \normalfont empty)} |
| 316 |
This style is installed at the beginning of every scope. |
| 317 |
\end{stylekey} |
| 318 |
|
| 319 |
The following options are useful for scopes: |
| 320 |
% |
| 321 |
\begin{key}{/tikz/execute at begin scope=\meta{code}} |
| 322 |
This option install some code that will be executed at the beginning of |
| 323 |
the scope. This option must be given in the argument of the |{scope}| |
| 324 |
environment. |
| 325 |
|
| 326 |
The effect applies only to the current scope, not to subscopes. |
| 327 |
\end{key} |
| 328 |
|
| 329 |
\begin{key}{/tikz/execute at end scope=\meta{code}} |
| 330 |
This option installs some code that will be executed at the end of the |
| 331 |
current scope. Using this option multiple times will cause the code to |
| 332 |
accumulate. This option must also be given in the optional argument of |
| 333 |
the |{scope}| environment. |
| 334 |
|
| 335 |
Again, the effect applies only to the current scope, not to subscopes. |
| 336 |
\end{key} |
| 337 |
\end{environment} |
| 338 |
|
| 339 |
\begin{plainenvironment}{{scope}\opt{\meta{animations spec}}\opt{\oarg{options}}} |
| 340 |
Plain \TeX\ version of the environment. |
| 341 |
\end{plainenvironment} |
| 342 |
|
| 343 |
\begin{contextenvironment}{{scope}\opt{\meta{animations spec}}\opt{\oarg{options}}} |
| 344 |
Con\TeX t version of the environment. |
| 345 |
\end{contextenvironment} |
| 346 |
|
| 347 |
|
| 348 |
\subsubsection{Shorthand for Scope Environments} |
| 349 |
|
| 350 |
There is a small library that makes using scopes a bit easier: |
| 351 |
% |
| 352 |
\begin{tikzlibrary}{scopes} |
| 353 |
This library defines a shorthand for starting and ending |{scope}| |
| 354 |
environments. |
| 355 |
\end{tikzlibrary} |
| 356 |
|
| 357 |
When this library is loaded, the following happens: At certain places inside a |
| 358 |
\tikzname\ picture, it is allowed to start a scope just using a single brace, |
| 359 |
provided the single brace is followed by options in square brackets: |
| 360 |
% |
| 361 |
\begin{codeexample}[preamble={\usetikzlibrary{scopes}}] |
| 362 |
\begin{tikzpicture} |
| 363 |
{ [ultra thick] |
| 364 |
{ [red] |
| 365 |
\draw (0mm,10mm) -- (10mm,10mm); |
| 366 |
\draw (0mm,8mm) -- (10mm,8mm); |
| 367 |
} |
| 368 |
\draw (0mm,6mm) -- (10mm,6mm); |
| 369 |
} |
| 370 |
{ [green] |
| 371 |
\draw (0mm,4mm) -- (10mm,4mm); |
| 372 |
\draw (0mm,2mm) -- (10mm,2mm); |
| 373 |
\draw[blue] (0mm,0mm) -- (10mm,0mm); |
| 374 |
} |
| 375 |
\end{tikzpicture} |
| 376 |
\end{codeexample} |
| 377 |
|
| 378 |
In the above example, |{ [ultra thick]| actually causes a |
| 379 |
|\begin{scope}[ultra thick]| to be inserted, and the corresponding closing |}| |
| 380 |
causes an |\end{scope}| to be inserted. |
| 381 |
|
| 382 |
The ``certain places'' where an opening brace has this special meaning are the |
| 383 |
following: First, right after the semicolon that ends a path. Second, right |
| 384 |
after the end of a scope. Third, right at the beginning of a scope, which |
| 385 |
includes the beginning of a picture. Also note that some square bracket must |
| 386 |
follow, otherwise the brace is treated as a normal \TeX\ scope. |
| 387 |
|
| 388 |
|
| 389 |
\subsubsection{Single Command Scopes} |
| 390 |
|
| 391 |
In some situations it is useful to create a scope for a single command. For |
| 392 |
instance, when you wish to use algorithm graph drawing in order to layout a |
| 393 |
tree, the path of the tree needs to be surrounded by a scope whose only purpose |
| 394 |
is to take a key that selects a layout for the scope. Similarly, in order to |
| 395 |
put something on a background layer, a scope needs to be created. In such |
| 396 |
cases, where it will cumbersome to create a |\begin{scope}| and |\end{scope}| |
| 397 |
pair just for a single command, the |\scoped| command may be useful: |
| 398 |
|
| 399 |
\begin{command}{\scoped\opt{\meta{animations spec}}\opt{\oarg{options}}\meta{path command}} |
| 400 |
This command works like |\tikz|, only you can use it inside a |
| 401 |
|{tikzpicture}|. It will take the following \meta{path command} and |
| 402 |
put it inside a |{scope}| with the \meta{options} set. The |
| 403 |
\meta{path command} may either be a single command ended by a |
| 404 |
semicolon or it may contain multiple commands, but then they must be |
| 405 |
surrounded by curly braces. |
| 406 |
% |
| 407 |
\begin{codeexample}[preamble={\usetikzlibrary{backgrounds}}] |
| 408 |
\begin{tikzpicture} |
| 409 |
\node [fill=white] at (1,1) {Hello world}; |
| 410 |
\scoped [on background layer] |
| 411 |
\draw (0,0) grid (3,2); |
| 412 |
\end{tikzpicture} |
| 413 |
\end{codeexample} |
| 414 |
% |
| 415 |
\end{command} |
| 416 |
|
| 417 |
|
| 418 |
\subsubsection{Using Scopes Inside Paths} |
| 419 |
|
| 420 |
The |\path| command, which is described in much more detail in later sections, |
| 421 |
also takes graphic options. These options are local to the path. Furthermore, |
| 422 |
it is possible to create local scopes within a path simply by using curly |
| 423 |
braces as in |
| 424 |
% |
| 425 |
\begin{codeexample}[] |
| 426 |
\tikz \draw (0,0) -- (1,1) |
| 427 |
{[rounded corners] -- (2,0) -- (3,1)} |
| 428 |
-- (3,0) -- (2,1); |
| 429 |
\end{codeexample} |
| 430 |
|
| 431 |
Note that many options apply only to the path as a whole and cannot be scoped |
| 432 |
in this way. For example, it is not possible to scope the |color| of the path. |
| 433 |
See the explanations in the section on paths for more details. |
| 434 |
|
| 435 |
Finally, certain elements that you specify in the argument to the |\path| |
| 436 |
command also take local options. For example, a node specification takes |
| 437 |
options. In this case, the options apply only to the node, not to the |
| 438 |
surrounding path. |
| 439 |
|
| 440 |
|
| 441 |
\subsection{Using Graphic Options} |
| 442 |
\label{section-graphic-options} |
| 443 |
|
| 444 |
\subsubsection{How Graphic Options Are Processed} |
| 445 |
|
| 446 |
Many commands and environments of \tikzname\ accept \emph{options}. These |
| 447 |
options are so-called \emph{key lists}. To process the options, the following |
| 448 |
command is used, which you can also call yourself. Note that it is usually |
| 449 |
better not to call this command directly, since this will ensure that the |
| 450 |
effect of options are local to a well-defined scope. |
| 451 |
|
| 452 |
\begin{command}{\tikzset\marg{options}} |
| 453 |
This command will process the \meta{options} using the |\pgfkeys| command, |
| 454 |
documented in detail in Section~\ref{section-keys}, with the default path |
| 455 |
set to |/tikz|. Under normal circumstances, the \meta{options} will be |
| 456 |
lists of comma-separated pairs of the form \meta{key}|=|\meta{value}, but |
| 457 |
more fancy things can happen when you use the power of the |pgfkeys| |
| 458 |
mechanism, see Section~\ref{section-keys} once more. |
| 459 |
|
| 460 |
When a pair \meta{key}|=|\meta{value} is processed, the following happens: |
| 461 |
% |
| 462 |
\begin{enumerate} |
| 463 |
\item If the \meta{key} is a full key (starts with a slash) it is |
| 464 |
handled directly as described in Section~\ref{section-keys}. |
| 465 |
\item Otherwise (which is usually the case), it is checked whether |
| 466 |
|/tikz/|\meta{key} is a key and, if so, it is executed. |
| 467 |
\item Otherwise, it is checked whether |/pgf/|\meta{key} is a key |
| 468 |
and, if so, it is executed. |
| 469 |
\item Otherwise, it is checked whether \meta{key} is a color and, if |
| 470 |
so, |color=|\meta{key} is executed. |
| 471 |
\item Otherwise, it is checked whether \meta{key} contains a dash |
| 472 |
and, if so, |arrows=|\meta{key} is executed. |
| 473 |
\item Otherwise, it is checked whether \meta{key} is the name of a |
| 474 |
shape and, if so, |shape=|\meta{key} is executed. |
| 475 |
\item Otherwise, an error message is printed. |
| 476 |
\end{enumerate} |
| 477 |
|
| 478 |
Note that by the above description, all keys starting with |/tikz| and also |
| 479 |
all keys starting with |/pgf| can be used as \meta{key}s in an |
| 480 |
\meta{options} list. |
| 481 |
\end{command} |
| 482 |
|
| 483 |
|
| 484 |
\subsubsection{Using Styles to Manage How Pictures Look} |
| 485 |
|
| 486 |
There is a way of organizing sets of graphic options ``orthogonally'' to the |
| 487 |
normal scoping mechanism. For example, you might wish all your ``help lines'' |
| 488 |
to be drawn in a certain way like, say, gray and thin (do \emph{not} dash them, |
| 489 |
that distracts). For this, you can use \emph{styles}. |
| 490 |
|
| 491 |
A style is a key that, when used, causes a set of graphic options to be |
| 492 |
processed. Once a style has been defined, it can be used like any other key. |
| 493 |
For example, the predefined |help lines| style, which you should use for lines |
| 494 |
in the background like grid lines or construction lines. |
| 495 |
% |
| 496 |
\begin{codeexample}[] |
| 497 |
\begin{tikzpicture} |
| 498 |
\draw (0,0) grid +(2,2); |
| 499 |
\draw[help lines] (2,0) grid +(2,2); |
| 500 |
\end{tikzpicture} |
| 501 |
\end{codeexample} |
| 502 |
|
| 503 |
Defining styles is also done using options. Suppose we wish to define a style |
| 504 |
called |my style| and when this style is used, we want the draw color to be set |
| 505 |
to |red| and the fill color be set to |red!20|. To achieve this, we use the |
| 506 |
following option: |
| 507 |
% |
| 508 |
\begin{codeexample}[code only] |
| 509 |
my style/.style={draw=red,fill=red!20} |
| 510 |
\end{codeexample} |
| 511 |
|
| 512 |
The meaning of the curious |/.style| is the following: ``The key |my style| |
| 513 |
should not be used here but, rather, be defined. So, set up things such that |
| 514 |
using the key |my style| will, in the following, have the same effect as if we |
| 515 |
had written |draw=red,fill=red!20| instead.'' |
| 516 |
|
| 517 |
Returning to the help lines example, suppose we prefer blue help lines. This |
| 518 |
could be achieved as follows: |
| 519 |
% |
| 520 |
\begin{codeexample}[] |
| 521 |
\begin{tikzpicture}[help lines/.style={blue!50,very thin}] |
| 522 |
\draw (0,0) grid +(2,2); |
| 523 |
\draw[help lines] (2,0) grid +(2,2); |
| 524 |
\end{tikzpicture} |
| 525 |
\end{codeexample} |
| 526 |
|
| 527 |
Naturally, one of the main ideas behind styles is that they can be used in |
| 528 |
different pictures. In this case, we have to use the |\tikzset| command |
| 529 |
somewhere at the beginning. |
| 530 |
% |
| 531 |
\begin{codeexample}[] |
| 532 |
\tikzset{help lines/.style={blue!50,very thin}} |
| 533 |
% ... |
| 534 |
\begin{tikzpicture} |
| 535 |
\draw (0,0) grid +(2,2); |
| 536 |
\draw[help lines] (2,0) grid +(2,2); |
| 537 |
\end{tikzpicture} |
| 538 |
\end{codeexample} |
| 539 |
|
| 540 |
Since styles are just special cases of |pgfkeys|'s general style facility, you |
| 541 |
can actually do quite a bit more. Let us start with adding options to an |
| 542 |
already existing style. This is done using |/.append style| instead of |
| 543 |
|/.style|: |
| 544 |
% |
| 545 |
\begin{codeexample}[] |
| 546 |
\begin{tikzpicture}[help lines/.append style=blue!50] |
| 547 |
\draw (0,0) grid +(2,2); |
| 548 |
\draw[help lines] (2,0) grid +(2,2); |
| 549 |
\end{tikzpicture} |
| 550 |
\end{codeexample} |
| 551 |
% |
| 552 |
In the above example, the option |blue!50| is appended to the style |
| 553 |
|help lines|, which now has the same effect as |black!50,very thin,blue!50|. |
| 554 |
Note that two colors are set, so the last one will ``win''. There also exists a |
| 555 |
handler called |/.prefix style| that adds something at the beginning of the |
| 556 |
style. |
| 557 |
|
| 558 |
Just as normal keys, styles can be parameterized. This means that you write |
| 559 |
\meta{style}|=|\meta{value} when you use the style instead of just |
| 560 |
\meta{style}. In this case, all occurrences of |#1| in \meta{style} are |
| 561 |
replaced by \meta{value}. Here is an example that shows how this can be used. |
| 562 |
% |
| 563 |
\begin{codeexample}[] |
| 564 |
\begin{tikzpicture}[outline/.style={draw=#1,thick,fill=#1!50}] |
| 565 |
\node [outline=red] at (0,1) {red}; |
| 566 |
\node [outline=blue] at (0,0) {blue}; |
| 567 |
\end{tikzpicture} |
| 568 |
\end{codeexample} |
| 569 |
|
| 570 |
For parameterized styles you can also set a \emph{default} value using the |
| 571 |
|/.default| handler: |
| 572 |
% |
| 573 |
\begin{codeexample}[] |
| 574 |
\begin{tikzpicture}[outline/.style={draw=#1,thick,fill=#1!50}, |
| 575 |
outline/.default=black] |
| 576 |
\node [outline] at (0,1) {default}; |
| 577 |
\node [outline=blue] at (0,0) {blue}; |
| 578 |
\end{tikzpicture} |
| 579 |
\end{codeexample} |
| 580 |
|
| 581 |
For more details on using and setting styles, see also |
| 582 |
Section~\ref{section-keys}. |