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