Debian Codegraph @

texmf-dist/doc/generic/pgf/pgfmanual-en-tikz-actions.tex

raw
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{Actions on Paths}
12
13 \subsection{Overview}
14
15 Once a path has been constructed, different things can be done with it. It can
16 be drawn (or stroked) with a ``pen'', it can be filled with a color or shading,
17 it can be used for clipping subsequent drawing, it can be used to specify the
18 extend of the picture -- or any combination of these actions at the same time.
19
20 To decide what is to be done with a path, two methods can be used. First, you
21 can use a special-purpose command like |\draw| to indicate that the path should
22 be drawn. However, commands like |\draw| and |\fill| are just abbreviations for
23 special cases of the more general method: Here, the |\path| command is used to
24 specify the path. Then, options encountered on the path indicate what should be
25 done with the path.
26
27 For example, |\path (0,0) circle (1cm);| means: ``This is a path consisting of
28 a circle around the origin. Do not do anything with it (throw it away).''
29 However, if the option |draw| is encountered anywhere on the path, the circle
30 will be drawn. ``Anywhere'' is any point on the path where an option can be
31 given, which is everywhere where a path command like |circle (1cm)| or
32 |rectangle (1,1)| or even just |(0,0)| would also be allowed. Thus, the
33 following commands all draw the same circle:
34 %
35 \begin{codeexample}[code only]
36 \path [draw] (0,0) circle (1cm);
37 \path (0,0) [draw] circle (1cm);
38 \path (0,0) circle (1cm) [draw];
39 \end{codeexample}
40 %
41 Finally, |\draw (0,0) circle (1cm);| also draws a path, because |\draw| is an
42 abbreviation for |\path [draw]| and thus the command expands to the first line
43 of the above example.
44
45 Similarly, |\fill| is an abbreviation for |\path[fill]| and |\filldraw| is an
46 abbreviation for the command |\path[fill,draw]|. Since options accumulate, the
47 following commands all have the same effect:
48 %
49 \begin{codeexample}[code only]
50 \path [draw,fill] (0,0) circle (1cm);
51 \path [draw] [fill] (0,0) circle (1cm);
52 \path [fill] (0,0) circle (1cm) [draw];
53 \draw [fill] (0,0) circle (1cm);
54 \fill (0,0) [draw] circle (1cm);
55 \filldraw (0,0) circle (1cm);
56 \end{codeexample}
57
58 In the following subsection the different actions that can be performed on a
59 path are explained. The following commands are abbreviations for certain sets
60 of actions, but for many useful combinations there are no abbreviations:
61
62 \begin{command}{\draw}
63 Inside |{tikzpicture}| this is an abbreviation for |\path[draw]|.
64 \end{command}
65
66 \begin{command}{\fill}
67 Inside |{tikzpicture}| this is an abbreviation for |\path[fill]|.
68 \end{command}
69
70 \begin{command}{\filldraw}
71 Inside |{tikzpicture}| this is an abbreviation for |\path[fill,draw]|.
72 \end{command}
73
74 \begin{command}{\pattern}
75 Inside |{tikzpicture}| this is an abbreviation for |\path[pattern]|.
76 \end{command}
77
78 \begin{command}{\shade}
79 Inside |{tikzpicture}| this is an abbreviation for |\path[shade]|.
80 \end{command}
81
82 \begin{command}{\shadedraw}
83 Inside |{tikzpicture}| this is an abbreviation for |\path[shade,draw]|.
84 \end{command}
85
86 \begin{command}{\clip}
87 Inside |{tikzpicture}| this is an abbreviation for |\path[clip]|.
88 \end{command}
89
90 \begin{command}{\useasboundingbox}
91 Inside |{tikzpicture}| this is an abbreviation for |\path[use as bounding box]|.
92 \end{command}
93
94
95 \subsection{Specifying a Color}
96
97 The most unspecific option for setting colors is the following:
98 %
99 \begin{key}{/tikz/color=\meta{color name}}
100 \indexoption{color option}%
101 This option sets the color that is used for fill, drawing, and text inside
102 the current scope. Any special settings for filling colors or drawing
103 colors are immediately ``overruled'' by this option.
104
105 The \meta{color name} is the name of a previously defined color. For
106 \LaTeX\ users, this is just a normal ``\LaTeX-color'' and the |xcolor|
107 extensions are allowed. Here is an example:
108 %
109 \begin{codeexample}[]
110 \tikz \fill[color=red!20] (0,0) circle (1ex);
111 \end{codeexample}
112
113 It is possible to ``leave out'' the |color=| part and you can also write:
114 %
115 \begin{codeexample}[]
116 \tikz \fill[red!20] (0,0) circle (1ex);
117 \end{codeexample}
118 %
119 What happens is that every option that \tikzname\ does not know, like
120 |red!20|, gets a ``second chance'' as a color name.
121
122 For plain \TeX\ users, it is not so easy to specify colors since plain
123 \TeX\ has no ``standardized'' color naming mechanism. Because of this,
124 \pgfname\ emulates the |xcolor| package, though the emulation is
125 \emph{extremely basic} (more precisely, what I could hack together in two
126 hours or so). The emulation allows you to do the following:
127 %
128 \begin{itemize}
129 \item Specify a new color using |\definecolor|. Only the color models
130 |gray|, |rgb|, and |RGB| are supported\footnote{Con\TeX t users
131 should be aware that \texttt{\textbackslash definecolor} has a
132 different meaning in Con\TeX t. There is a low-level equivalent
133 named \texttt{\textbackslash pgfutil@definecolor} which can be
134 used instead.}.
135 %
136 \example |\definecolor{orange}{rgb}{1,0.5,0}|
137 \item Use |\colorlet| to define a new color based on an old one.
138 Here, the |!| mechanism is supported, though only ``once'' (use
139 multiple |\colorlet| for more fancy colors).
140 %
141 \example |\colorlet{lightgray}{black!25}|
142 \item Use |\color|\marg{color name} to set the color in the current
143 \TeX\ group. |\aftergroup|-hackery is used to restore the color
144 after the group.
145 \end{itemize}
146 \end{key}
147
148 As pointed out above, the |color=| option applies to ``everything'' (except to
149 shadings), which is not always what you want. Because of this, there are
150 several more specialized color options. For example, the |draw=| option sets
151 the color used for drawing, but does not modify the color used for filling.
152 These color options are documented where the path action they influence is
153 described.
154
155
156 \subsection{Drawing a Path}
157
158 You can draw a path using the following option:
159 %
160 \begin{key}{/tikz/draw=\meta{color} (default \normalfont is scope's color setting)}
161 Causes the path to be drawn. ``Drawing'' (also known as ``stroking'') can
162 be thought of as picking up a pen and moving it along the path, thereby
163 leaving ``ink'' on the canvas.
164
165 There are numerous parameters that influence how a line is drawn, like the
166 thickness or the dash pattern. These options are explained below.
167
168 If the optional \meta{color} argument is given, drawing is done using the
169 given \meta{color}. This color can be different from the current filling
170 color, which allows you to draw and fill a path with different colors. If
171 no \meta{color} argument is given, the last usage of the |color=| option is
172 used.
173
174 If the special color name |none| is given, this option causes drawing to be
175 ``switched off''. This is useful if a style has previously switched on
176 drawing and you locally wish to undo this effect.
177
178 Although this option is normally used on paths to indicate that the path
179 should be drawn, it also makes sense to use the option with a |{scope}| or
180 |{tikzpicture}| environment. However, this will \emph{not} cause all paths
181 to be drawn. Instead, this just sets the \meta{color} to be used for
182 drawing paths inside the environment.
183 %
184 \begin{codeexample}[]
185 \begin{tikzpicture}
186 \path[draw=red] (0,0) -- (1,1) -- (2,1) circle (10pt);
187 \end{tikzpicture}
188 \end{codeexample}
189 %
190 \end{key}
191
192 The following subsections list the different options that influence how a path
193 is drawn. All of these options only have an effect if the |draw| option is
194 given (directly or indirectly).
195
196
197 \subsubsection{Graphic Parameters: Line Width, Line Cap, and Line Join}
198 \label{section-cap-joins}
199
200 \begin{key}{/tikz/line width=\meta{dimension} (initially 0.4pt)}
201 Specifies the line width. Note the space.
202 %
203 \begin{codeexample}[]
204 \tikz \draw[line width=5pt] (0,0) -- (1cm,1.5ex);
205 \end{codeexample}
206 %
207 \end{key}
208
209 There are a number of predefined styles that provide more ``natural'' ways of
210 setting the line width. You can also redefine these styles.
211
212 \begin{stylekey}{/tikz/ultra thin}
213 Sets the line width to 0.1pt.
214 %
215 \begin{codeexample}[]
216 \tikz \draw[ultra thin] (0,0) -- (1cm,1.5ex);
217 \end{codeexample}
218 %
219 \end{stylekey}
220
221 \begin{stylekey}{/tikz/very thin}
222 Sets the line width to 0.2pt.
223 %
224 \begin{codeexample}[]
225 \tikz \draw[very thin] (0,0) -- (1cm,1.5ex);
226 \end{codeexample}
227 %
228 \end{stylekey}
229
230 \begin{stylekey}{/tikz/thin}
231 Sets the line width to 0.4pt.
232 %
233 \begin{codeexample}[]
234 \tikz \draw[thin] (0,0) -- (1cm,1.5ex);
235 \end{codeexample}
236 %
237 \end{stylekey}
238
239 \begin{stylekey}{/tikz/semithick}
240 Sets the line width to 0.6pt.
241 %
242 \begin{codeexample}[]
243 \tikz \draw[semithick] (0,0) -- (1cm,1.5ex);
244 \end{codeexample}
245 %
246 \end{stylekey}
247
248 \begin{stylekey}{/tikz/thick}
249 Sets the line width to 0.8pt.
250 %
251 \begin{codeexample}[]
252 \tikz \draw[thick] (0,0) -- (1cm,1.5ex);
253 \end{codeexample}
254 %
255 \end{stylekey}
256
257 \begin{stylekey}{/tikz/very thick}
258 Sets the line width to 1.2pt.
259 %
260 \begin{codeexample}[]
261 \tikz \draw[very thick] (0,0) -- (1cm,1.5ex);
262 \end{codeexample}
263 %
264 \end{stylekey}
265
266 \begin{stylekey}{/tikz/ultra thick}
267 Sets the line width to 1.6pt.
268 %
269 \begin{codeexample}[]
270 \tikz \draw[ultra thick] (0,0) -- (1cm,1.5ex);
271 \end{codeexample}
272 %
273 \end{stylekey}
274
275 \label{section-line-cap}
276 \begin{key}{/tikz/line cap=\meta{type} (initially butt)}
277 Specifies how lines ``end''. Permissible \meta{type} are |round|, |rect|,
278 and |butt|. They have the following effects:
279 %
280 \begin{codeexample}[]
281 \begin{tikzpicture}
282 \begin{scope}[line width=10pt]
283 \draw[line cap=round] (0,1 ) -- +(1,0);
284 \draw[line cap=butt] (0,.5) -- +(1,0);
285 \draw[line cap=rect] (0,0 ) -- +(1,0);
286 \end{scope}
287 \draw[white,line width=1pt]
288 (0,0 ) -- +(1,0) (0,.5) -- +(1,0) (0,1 ) -- +(1,0);
289 \end{tikzpicture}
290 \end{codeexample}
291 %
292 \end{key}
293
294 \begin{key}{/tikz/line join=\meta{type} (initially miter)}
295 Specifies how lines ``join''. Permissible \meta{type} are |round|, |bevel|,
296 and |miter|. They have the following effects:
297 %
298 \begin{codeexample}[]
299 \begin{tikzpicture}[line width=10pt]
300 \draw[line join=round] (0,0) -- ++(.5,1) -- ++(.5,-1);
301 \draw[line join=bevel] (1.25,0) -- ++(.5,1) -- ++(.5,-1);
302 \draw[line join=miter] (2.5,0) -- ++(.5,1) -- ++(.5,-1);
303 \useasboundingbox (0,1.5); % enlarge bounding box
304 \end{tikzpicture}
305 \end{codeexample}
306
307 \begin{key}{/tikz/miter limit=\meta{factor} (initially 10)}
308 When you use the miter join and there is a very sharp corner (a small
309 angle), the miter join may protrude very far over the actual joining
310 point. In this case, if it were to protrude by more than \meta{factor}
311 times the line width, the miter join is replaced by a bevel join.
312 %
313 \begin{codeexample}[]
314 \begin{tikzpicture}[line width=5pt]
315 \draw (0,0) -- ++(5,.5) -- ++(-5,.5);
316 \draw[miter limit=25] (6,0) -- ++(5,.5) -- ++(-5,.5);
317 \useasboundingbox (14,0); % make bounding box bigger
318 \end{tikzpicture}
319 \end{codeexample}
320 \end{key}
321 \end{key}
322
323
324 \subsubsection{Graphic Parameters: Dash Pattern}
325
326 \begin{key}{/tikz/dash pattern=\meta{dash pattern}}
327 Sets the dashing pattern. The syntax is the same as in \textsc{metafont}.
328 For example following pattern |on 2pt off 3pt on 4pt off 4pt| means ``draw
329 2pt, then leave out 3pt, then draw 4pt once more, then leave out 4pt again,
330 repeat''.
331 %
332 \begin{codeexample}[]
333 \begin{tikzpicture}[dash pattern=on 2pt off 3pt on 4pt off 4pt]
334 \draw (0pt,0pt) -- (3.5cm,0pt);
335 \end{tikzpicture}
336 \end{codeexample}
337 %
338 \end{key}
339
340 \begin{key}{/tikz/dash phase=\meta{dash phase} (initially 0pt)}
341 Shifts the start of the dash pattern by \meta{phase}.
342 %
343 \begin{codeexample}[]
344 \begin{tikzpicture}[dash pattern=on 20pt off 10pt]
345 \draw[dash phase=0pt] (0pt,3pt) -- (3.5cm,3pt);
346 \draw[dash phase=10pt] (0pt,0pt) -- (3.5cm,0pt);
347 \end{tikzpicture}
348 \end{codeexample}
349 %
350 \end{key}
351
352 \begin{key}{/tikz/dash=\meta{dash pattern}|phase|\meta{dash phase}}
353 Sets the dashing pattern and phase at the same time.
354 %
355 \begin{codeexample}[]
356 \begin{tikzpicture}
357 \draw [dash=on 20pt off 10pt phase 0pt] (0pt,3pt) -- (3.5cm,3pt);
358 \draw [dash=on 20pt off 10pt phase 10pt] (0pt,0pt) -- (3.5cm,0pt);
359 \end{tikzpicture}
360 \end{codeexample}
361 %
362 \end{key}
363
364 \begin{key}{/tikz/dash expand off}
365 Makes the |off| part of a dash pattern expandable such that it can stretch.
366 This only works when there is a single |on| and a single |off| field and
367 requires the |decorations| library. Right now this option has to be
368 specified on the path where it is supposed to take effect after the
369 |dash pattern| option because the dash pattern has to be known at the point
370 where it is applied.
371 %
372 \begin{codeexample}[preamble={\usetikzlibrary{decorations}}]
373 \begin{tikzpicture}[|-|, dash pattern=on 4pt off 2pt]
374 \draw [dash expand off] (0pt,30pt) -- (26pt,30pt);
375 \draw [dash expand off] (0pt,20pt) -- (24pt,20pt);
376 \draw [dash expand off] (0pt,10pt) -- (22pt,10pt);
377 \draw [dash expand off] (0pt, 0pt) -- (20pt, 0pt);
378 \end{tikzpicture}
379 \end{codeexample}
380 %
381 \end{key}
382
383 As for the line thickness, some predefined styles allow you to set the dashing
384 conveniently.
385
386 \begin{stylekey}{/tikz/solid}
387 Shorthand for setting a solid line as ``dash pattern''. This is the default.
388 %
389 \begin{codeexample}[]
390 \tikz \draw[solid] (0pt,0pt) -- (50pt,0pt);
391 \end{codeexample}
392 %
393 \end{stylekey}
394
395 \begin{stylekey}{/tikz/dotted}
396 Shorthand for setting a dotted dash pattern.
397 %
398 \begin{codeexample}[]
399 \tikz \draw[dotted] (0pt,0pt) -- (50pt,0pt);
400 \end{codeexample}
401 %
402 \end{stylekey}
403
404 \begin{stylekey}{/tikz/densely dotted}
405 Shorthand for setting a densely dotted dash pattern.
406 %
407 \begin{codeexample}[]
408 \tikz \draw[densely dotted] (0pt,0pt) -- (50pt,0pt);
409 \end{codeexample}
410 %
411 \end{stylekey}
412
413 \begin{stylekey}{/tikz/loosely dotted}
414 Shorthand for setting a loosely dotted dash pattern.
415 %
416 \begin{codeexample}[]
417 \tikz \draw[loosely dotted] (0pt,0pt) -- (50pt,0pt);
418 \end{codeexample}
419 %
420 \end{stylekey}
421
422 \begin{stylekey}{/tikz/dashed}
423 Shorthand for setting a dashed dash pattern.
424 %
425 \begin{codeexample}[]
426 \tikz \draw[dashed] (0pt,0pt) -- (50pt,0pt);
427 \end{codeexample}
428 %
429 \end{stylekey}
430
431 \begin{stylekey}{/tikz/densely dashed}
432 Shorthand for setting a densely dashed dash pattern.
433 %
434 \begin{codeexample}[]
435 \tikz \draw[densely dashed] (0pt,0pt) -- (50pt,0pt);
436 \end{codeexample}
437 %
438 \end{stylekey}
439
440 \begin{stylekey}{/tikz/loosely dashed}
441 Shorthand for setting a loosely dashed dash pattern.
442 %
443 \begin{codeexample}[]
444 \tikz \draw[loosely dashed] (0pt,0pt) -- (50pt,0pt);
445 \end{codeexample}
446 %
447 \end{stylekey}
448
449 \begin{stylekey}{/tikz/dash dot}
450 Shorthand for setting a dashed and dotted dash pattern.
451 %
452 \begin{codeexample}[]
453 \tikz \draw[dash dot] (0pt,0pt) -- (50pt,0pt);
454 \end{codeexample}
455 %
456 \end{stylekey}
457
458 \begin{stylekey}{/tikz/densely dash dot}
459 Shorthand for setting a densely dashed and dotted dash pattern.
460 %
461 \begin{codeexample}[]
462 \tikz \draw[densely dash dot] (0pt,0pt) -- (50pt,0pt);
463 \end{codeexample}
464 %
465 \end{stylekey}
466
467 \begin{stylekey}{/tikz/loosely dash dot}
468 Shorthand for setting a loosely dashed and dotted dash pattern.
469 %
470 \begin{codeexample}[]
471 \tikz \draw[loosely dash dot] (0pt,0pt) -- (50pt,0pt);
472 \end{codeexample}
473 %
474 \end{stylekey}
475
476 \begin{stylekey}{/tikz/dash dot dot}
477 Shorthand for setting a dashed and dotted dash pattern with more dots.
478 %
479 \begin{codeexample}[]
480 \tikz \draw[dash dot dot] (0pt,0pt) -- (50pt,0pt);
481 \end{codeexample}
482 %
483 \end{stylekey}
484
485 \begin{stylekey}{/tikz/densely dash dot dot}
486 Shorthand for setting a densely dashed and dotted dash pattern with more dots.
487 %
488 \begin{codeexample}[]
489 \tikz \draw[densely dash dot dot] (0pt,0pt) -- (50pt,0pt);
490 \end{codeexample}
491 %
492 \end{stylekey}
493
494 \begin{stylekey}{/tikz/loosely dash dot dot}
495 Shorthand for setting a loosely dashed and dotted dash pattern with more dots.
496 %
497 \begin{codeexample}[]
498 \tikz \draw[loosely dash dot dot] (0pt,0pt) -- (50pt,0pt);
499 \end{codeexample}
500 %
501 \end{stylekey}
502
503
504 \subsubsection{Graphic Parameters: Draw Opacity}
505
506 When a line is drawn, it will normally ``obscure'' everything behind it as if
507 you had used perfectly opaque ink. It is also possible to ask \tikzname\ to use
508 an ink that is a little bit (or a big bit) transparent using the |draw opacity|
509 option. This is explained in Section~\ref{section-tikz-transparency} on
510 transparency in more detail.
511
512
513 \subsubsection{Graphic Parameters: Double Lines and Bordered Lines}
514
515 \begin{key}{/tikz/double=\meta{core color} (default white)}
516 This option causes ``two'' lines to be drawn instead of a single one.
517 However, this is not what really happens. In reality, the path is drawn
518 twice. First, with the normal drawing color, secondly with the \meta{core
519 color}, which is normally |white|. Upon the second drawing, the line width
520 is reduced. The net effect is that it appears as if two lines had been
521 drawn and this works well even with complicated, curved paths:
522 %
523 \begin{codeexample}[]
524 \tikz \draw[double]
525 plot[smooth cycle] coordinates{(0,0) (1,1) (1,0) (0,1)};
526 \end{codeexample}
527
528 You can also use the doubling option to create an effect in which a line
529 seems to have a certain ``border'':
530 %
531 \begin{codeexample}[]
532 \begin{tikzpicture}
533 \draw (0,0) -- (1,1);
534 \draw[draw=white,double=red,very thick] (0,1) -- (1,0);
535 \end{tikzpicture}
536 \end{codeexample}
537 %
538 \end{key}
539
540 \begin{key}{/tikz/double distance=\meta{dimension} (initially 0.6pt)}
541 Sets the distance the ``two'' lines are spaced apart. In reality, this is
542 the thickness of the line that is used to draw the path for the second
543 time. The thickness of the \emph{first} time the path is drawn is twice the
544 normal line width plus the given \meta{dimension}. As a side-effect, this
545 option ``selects'' the |double| option.
546 %
547 \begin{codeexample}[]
548 \begin{tikzpicture}
549 \draw[very thick,double] (0,0) arc (180:90:1cm);
550 \draw[very thick,double distance=2pt] (1,0) arc (180:90:1cm);
551 \draw[thin,double distance=2pt] (2,0) arc (180:90:1cm);
552 \end{tikzpicture}
553 \end{codeexample}
554 %
555 \end{key}
556
557 \begin{key}{/tikz/double distance between line centers=\meta{dimension}}
558 This option works like |double distance|, only the distance is not the
559 distance between (inner) borders of the two main lines, but between their
560 centers. Thus, the thickness the \emph{first} time the path is drawn is the
561 normal line width plus the given \meta{dimension}, while the line width of
562 the \emph{second} line that is drawn is \meta{dimension} minus the normal
563 line width. As a side-effect, this option ``selects'' the |double| option.
564 %
565 \begin{codeexample}[]
566 \begin{tikzpicture}[double distance between line centers=3pt]
567 \foreach \lw in {0.5,1,1.5,2,2.5}
568 \draw[line width=\lw pt,double] (\lw,0) -- ++(4mm,0);
569 \end{tikzpicture}
570 \end{codeexample}
571 %
572 \begin{codeexample}[]
573 \begin{tikzpicture}[double distance=3pt]
574 \foreach \lw in {0.5,1,1.5,2,2.5}
575 \draw[line width=\lw pt,double] (\lw,0) -- ++(4mm,0);
576 \end{tikzpicture}
577 \end{codeexample}
578 %
579 \end{key}
580
581 \begin{stylekey}{/tikz/double equal sign distance}
582 This style selects a double line distance such that it corresponds to the
583 distance of the two lines in an equal sign.
584 %
585 \begin{codeexample}[
586 preamble={\usepackage{amsmath}
587 \usetikzlibrary{arrows.meta}}
588 ]
589 \Huge $=\implies$\tikz[baseline,double equal sign distance]
590 \draw[double,thick,-{Implies[]}](0,0.55ex) --++(3ex,0);
591 \end{codeexample}
592 %
593 \begin{codeexample}[
594 preamble={\usepackage{amsmath}
595 \usetikzlibrary{arrows.meta}}
596 ]
597 \normalsize $=\implies$\tikz[baseline,double equal sign distance]
598 \draw[double,-{Implies[]}](0,0.6ex) --++(3ex,0);
599 \end{codeexample}
600 %
601 \begin{codeexample}[
602 preamble={\usepackage{amsmath}
603 \usetikzlibrary{arrows.meta}}
604 ]
605 \tiny $=\implies$\tikz[baseline,double equal sign distance]
606 \draw[double,very thin,-{Implies[]}](0,0.5ex) -- ++(3ex,0);
607 \end{codeexample}
608 %
609 \end{stylekey}
610
611
612 \subsection{Adding Arrow Tips to a Path}
613 \label{section-arrow-tip-action}
614
615 In different situations, \tikzname\ will add arrow tips to the end of a path.
616 For this to happen, a number of different things need to be specified:
617 %
618 \begin{enumerate}
619 \item You must have used the |arrows| key, explained in detail in
620 Section~\ref{section-tikz-arrows}, to setup which kinds of arrow tips
621 you would like.
622 \item The path may not be closed (like a circle or a rectangle) and, if
623 it consists of several subpaths, further restrictions apply as
624 explained in Section~\ref{section-tikz-arrows}.
625 \item The |tips| key must be set to an appropriate value, see
626 Section~\ref{section-tikz-arrows} once more.
627 \end{enumerate}
628
629 For the current section on paths, it is only important that when you add the
630 |tips| option to a path that is not drawn, arrow tips will still be added at
631 the beginning and at the end of the current path. This is true even when
632 ``only'' arrow tips get drawn for a path without drawing the path itself. Here
633 is an example:
634 %
635 \begin{codeexample}[width=2cm,preamble={\usetikzlibrary{arrows.meta,bending}}]
636 \tikz \path[tips, -{Latex[open,length=10pt,bend]}] (0,0) to[bend left] (1,0);
637 \end{codeexample}
638 %
639 \begin{codeexample}[width=2cm,preamble={\usetikzlibrary{arrows.meta,bending}}]
640 \tikz \draw[tips, -{Latex[open,length=10pt,bend]}] (0,0) to[bend left] (1,0);
641 \end{codeexample}
642
643
644 \subsection{Filling a Path}
645 \label{section-rules}
646
647 To fill a path, use the following option:
648 %
649 \begin{key}{/tikz/fill=\meta{color} (default \normalfont is scope's color setting)}
650 This option causes the path to be filled. All unclosed parts of the path
651 are first closed, if necessary. Then, the area enclosed by the path is
652 filled with the current filling color, which is either the last color set
653 using the general |color=| option or the optional color \meta{color}. For
654 self-intersection paths and for paths consisting of several closed areas,
655 the ``enclosed area'' is somewhat complicated to define and two different
656 definitions exist, namely the nonzero winding number rule and the even odd
657 rule, see the explanation of these options, below.
658
659 Just as for the |draw| option, setting \meta{color} to |none| disables
660 filling locally.
661 %
662 \begin{codeexample}[]
663 \begin{tikzpicture}
664 \fill (0,0) -- (1,1) -- (2,1);
665 \fill (4,0) circle (.5cm) (4.5,0) circle (.5cm);
666 \fill[even odd rule] (6,0) circle (.5cm) (6.5,0) circle (.5cm);
667 \fill (8,0) -- (9,1) -- (10,0) circle (.5cm);
668 \end{tikzpicture}
669 \end{codeexample}
670
671 If the |fill| option is used together with the |draw| option (either
672 because both are given as options or because a |\filldraw| command is
673 used), the path is filled \emph{first}, then the path is drawn
674 \emph{second}. This is especially useful if different colors are selected
675 for drawing and for filling. Even if the same color is used, there is a
676 difference between this command and a plain |fill|: A ``filldrawn'' area
677 will be slightly larger than a filled area because of the thickness of the
678 ``pen''.
679 %
680 \begin{codeexample}[]
681 \begin{tikzpicture}[fill=yellow!80!black,line width=5pt]
682 \filldraw (0,0) -- (1,1) -- (2,1);
683 \filldraw (4,0) circle (.5cm) (4.5,0) circle (.5cm);
684 \filldraw[even odd rule] (6,0) circle (.5cm) (6.5,0) circle (.5cm);
685 \filldraw (8,0) -- (9,1) -- (10,0) circle (.5cm);
686 \end{tikzpicture}
687 \end{codeexample}
688 %
689 \end{key}
690
691
692 \subsubsection{Graphic Parameters: Fill Pattern}
693 \label{section-fill-pattern}
694
695 Instead of filling a path with a single solid color, it is also possible to
696 fill it with a \emph{tiling pattern}. Imagine a small tile that contains a
697 simple picture like a star. Then these tiles are (conceptually) repeated
698 infinitely in all directions, but clipped against the path.
699
700 Tiling patterns come in two variants: \emph{inherently colored patterns} and
701 \emph{form-only patterns}. An inherently colored pattern is, say, a red star
702 with a black border and will always look like this. A form-only pattern may
703 have a different color each time it is used, only the form of the pattern will
704 stay the same. As such, form-only patterns do not have any colors of their own,
705 but when it is used the current \emph{pattern color} is used as its color.
706
707 Patterns are not overly flexible. In particular, it is not possible to change
708 the size or orientation of a pattern without declaring a new pattern. For
709 complicated cases, it may be easier to use two nested |\foreach| statements to
710 simulate a pattern, but patterns are rendered \emph{much} more quickly than
711 simulated ones.
712
713 \begin{key}{/tikz/pattern=\meta{name} (default \normalfont is scope's pattern)}
714 This option causes the path to be filled with a pattern. If the \meta{name}
715 is given, this pattern is used, otherwise the pattern set in the enclosing
716 scope is used. As for the |draw| and |fill| options, setting \meta{name} to
717 |none| disables filling locally.
718
719 The pattern works like a fill color. In particular, setting a new fill
720 color will fill the path with a solid color once more.
721
722 Strangely, no \meta{name}s are permissible by default. You need to load for
723 instance the |patterns| library, see
724 Section~\ref{section-library-patterns}, to install predefined patterns.
725 %
726 \begin{codeexample}[preamble={\usetikzlibrary{patterns}}]
727 \begin{tikzpicture}
728 \draw[pattern=dots] (0,0) circle (1cm);
729 \draw[pattern=fivepointed stars] (0,0) rectangle (3,1);
730 \end{tikzpicture}
731 \end{codeexample}
732 %
733 \end{key}
734
735 \begin{key}{/tikz/pattern color=\meta{color}}
736 This option is used to set the color to be used for form-only patterns.
737 This option has no effect on inherently colored patterns.
738 %
739 \begin{codeexample}[preamble={\usetikzlibrary{patterns}}]
740 \begin{tikzpicture}
741 \draw[pattern color=red,pattern=fivepointed stars] (0,0) circle (1cm);
742 \draw[pattern color=blue,pattern=fivepointed stars] (0,0) rectangle (3,1);
743 \end{tikzpicture}
744 \end{codeexample}
745
746 \begin{codeexample}[preamble={\usetikzlibrary{patterns}}]
747 \begin{tikzpicture}
748 \def\mypath{(0,0) -- +(0,1) arc (180:0:1.5cm) -- +(0,-1)}
749 \fill [red] \mypath;
750 \pattern[pattern color=white,pattern=bricks] \mypath;
751 \end{tikzpicture}
752 \end{codeexample}
753 %
754 \end{key}
755
756
757 \subsubsection{Graphic Parameters: Interior Rules}
758
759 The following two options can be used to decide how interior points should be
760 determined:
761 %
762 \begin{key}{/tikz/nonzero rule}
763 If this rule is used (which is the default), the following method is used
764 to determine whether a given point is ``inside'' the path: From the point,
765 shoot a ray in some direction towards infinity (the direction is chosen
766 such that no strange borderline cases occur). Then the ray may hit the
767 path. Whenever it hits the path, we increase or decrease a counter, which
768 is initially zero. If the ray hits the path as the path goes ``from left to
769 right'' (relative to the ray), the counter is increased, otherwise it is
770 decreased. Then, at the end, we check whether the counter is nonzero (hence
771 the name). If so, the point is deemed to lie ``inside'', otherwise it is
772 ``outside''. Sounds complicated? It is.
773 %
774 \begin{codeexample}[]
775 \begin{tikzpicture}
776 \filldraw[fill=yellow!80!black]
777 % Clockwise rectangle
778 (0,0) -- (0,1) -- (1,1) -- (1,0) -- cycle
779 % Counter-clockwise rectangle
780 (0.25,0.25) -- (0.75,0.25) -- (0.75,0.75) -- (0.25,0.75) -- cycle;
781
782 \draw[->] (0,1) -- (.4,1);
783 \draw[->] (0.75,0.75) -- (0.3,.75);
784
785 \draw[->] (0.5,0.5) -- +(0,1) node[above] {crossings: $-1+1 = 0$};
786
787 \begin{scope}[yshift=-3cm]
788 \filldraw[fill=yellow!80!black]
789 % Clockwise rectangle
790 (0,0) -- (0,1) -- (1,1) -- (1,0) -- cycle
791 % Clockwise rectangle
792 (0.25,0.25) -- (0.25,0.75) -- (0.75,0.75) -- (0.75,0.25) -- cycle;
793
794 \draw[->] (0,1) -- (.4,1);
795 \draw[->] (0.25,0.75) -- (0.4,.75);
796
797 \draw[->] (0.5,0.5) -- +(0,1) node[above] {crossings: $1+1 = 2$};
798 \end{scope}
799 \end{tikzpicture}
800 \end{codeexample}
801 %
802 \end{key}
803
804 \begin{key}{/tikz/even odd rule}
805 This option causes a different method to be used for determining the inside
806 and outside of paths. While it is less flexible, it turns out to be more
807 intuitive.
808
809 With this method, we also shoot rays from the point for which we wish to
810 determine whether it is inside or outside the filling area. However, this
811 time we only count how often we ``hit'' the path and declare the point to
812 be ``inside'' if the number of hits is odd.
813
814 Using the even-odd rule, it is easy to ``drill holes'' into a path.
815 %
816 \begin{codeexample}[]
817 \begin{tikzpicture}
818 \filldraw[fill=yellow!80!black,even odd rule]
819 (0,0) rectangle (1,1) (0.5,0.5) circle (0.4cm);
820 \draw[->] (0.5,0.5) -- +(0,1) [above] node{crossings: $1+1 = 2$};
821 \end{tikzpicture}
822 \end{codeexample}
823 %
824 \end{key}
825
826
827 \subsubsection{Graphic Parameters: Fill Opacity}
828 \label{section-fill-opacity}
829
830 Analogously to the |draw opacity|, you can also set the fill opacity. Please
831 see Section~\ref{section-tikz-transparency} for more details.
832
833
834 \subsection{Generalized Filling: Using Arbitrary Pictures to Fill a Path}
835
836 Sometimes you wish to ``fill'' a path with something even more complicated than
837 a pattern, let alone a single color. For instance, you might wish to use an
838 image to fill the path or some other, complicated drawing. In principle, this
839 effect can be achieved by first using the path for clipping and then,
840 subsequently, drawing the desired image or picture. However, there is an option
841 that makes this process much easier:
842
843 \begin{key}{/tikz/path picture=\meta{code}}
844 When this option is given on a path and when the \meta{code} is not empty,
845 the following happens: After all other ``filling'' operations are done with
846 the path, which are caused by the options |fill|, |pattern| and |shade|, a
847 local scope is opened and the path is temporarily installed as a clipping
848 path. Then, the \meta{code} is executed, which can now draw something.
849 Then, the local scope ends and, possibly, the path is stroked, provided the
850 |draw| option has been given.
851
852 As with other keys like |fill| or |draw| this option needs to be given on a
853 path, setting the |path picture| outside a path has no effect (the path
854 picture is cleared at the beginning of each path).
855
856 The \meta{code} can be any normal \tikzname\ code like |\draw ...| or
857 |\node ...|. As always, when you include an external graphic, you need to
858 put it inside a |\node|.
859
860 Note that no special actions are taken to transform the origin in any way.
861 This means that the coordinate |(0,0)| is still where is was when the path
862 was being constructed and not -- as one might expect -- at the lower left
863 corner of the path. However, you can use the following special node to
864 access the size of the path:
865 %
866 \begin{predefinednode}{path picture bounding box}
867 This node is of shape |rectangle|. Its size and position are those of
868 |current path bounding box| just before the \meta{code} of the path
869 picture started to be executed. The \meta{code} can construct its own
870 paths, so accessing the |current path bounding box| inside the
871 \meta{code} yields the bounding box of any path that is currently being
872 constructed inside the \meta{code}.
873 \end{predefinednode}
874 %
875 \begin{codeexample}[]
876 \begin{tikzpicture}
877 \draw [help lines] (0,0) grid (3,2);
878 \filldraw [fill=blue!10,draw=blue,thick] (1.5,1) circle (1)
879 [path picture={
880 \node at (path picture bounding box.center) {
881 This is a long text.
882 };}
883 ];
884 \end{tikzpicture}
885 \end{codeexample}
886
887 \begin{codeexample}[]
888 \begin{tikzpicture}[cross/.style={path picture={
889 \draw[black]
890 (path picture bounding box.south east) --
891 (path picture bounding box.north west)
892 (path picture bounding box.south west) --
893 (path picture bounding box.north east);
894 }}]
895 \draw [help lines] (0,0) grid (3,2);
896 \filldraw [cross,fill=blue!10,draw=blue,thick] (1,1) circle (1);
897 \path [cross,top color=red,draw=red,thick] (2,0) -- (3,2) -- (3,0);
898 \end{tikzpicture}
899 \end{codeexample}
900
901 \begin{codeexample}[]
902 \begin{tikzpicture}[path image/.style={
903 path picture={
904 \node at (path picture bounding box.center) {
905 \includegraphics[height=3cm]{#1}
906 };}}]
907 \draw [help lines] (0,0) grid (3,2);
908
909 \draw [path image=brave-gnu-world-logo,draw=blue,thick]
910 (0,1) circle (1);
911 \draw [path image=brave-gnu-world-logo,draw=red,very thick,->]
912 (1,0) parabola[parabola height=2cm] (3,0);
913
914 \end{tikzpicture}
915 \end{codeexample}
916 %
917 \end{key}
918
919
920 \subsection{Shading a Path}
921
922 You can shade a path using the |shade| option. A shading is like a filling,
923 only the shading changes its color smoothly from one color to another.
924
925 \begin{key}{/tikz/shade}
926 Causes the path to be shaded using the currently selected shading (more on
927 this later). If this option is used together with the |draw| option, then
928 the path is first shaded, then drawn.
929
930 It is not an error to use this option together with the |fill| option, but
931 it makes no sense.
932 %
933 \begin{codeexample}[]
934 \tikz \shade (0,0) circle (1ex);
935 \end{codeexample}
936
937 \begin{codeexample}[]
938 \tikz \shadedraw (0,0) circle (1ex);
939 \end{codeexample}
940 %
941 \end{key}
942
943 For some shadings it is not really clear how they can ``fill'' the path. For
944 example, the |ball| shading normally looks like this:
945 \tikz \shade[shading=ball] (0,0) circle (0.75ex);. How is this supposed to
946 shade a rectangle? Or a triangle?
947
948 To solve this problem, the predefined shadings like |ball| or |axis| fill a
949 large rectangle completely in a sensible way. Then, when the shading is used to
950 ``shade'' a path, what actually happens is that the path is temporarily used
951 for clipping and then the rectangular shading is drawn, scaled and shifted such
952 that all parts of the path are filled.
953
954 The default shading is a smooth transition from gray to white and from top to
955 bottom. However, other shadings are also possible, for example a shading that
956 will sweep a color from the center to the corners outward. To choose the
957 shading, you can use the |shading=| option, which will also automatically
958 invoke the |shade| option. Note that this does \emph{not} change the shading
959 color, only the way the colors sweep. For changing the colors, other options
960 are needed, which are explained below.
961
962 \begin{key}{/tikz/shading=\meta{name}}
963 This selects a shading named \meta{name}. The following shadings are
964 predefined: |axis|, |radial|, and |ball|.
965 %
966 \begin{codeexample}[]
967 \tikz \shadedraw [shading=axis] (0,0) rectangle (1,1);
968 \tikz \shadedraw [shading=radial] (0,0) rectangle (1,1);
969 \tikz \shadedraw [shading=ball] (0,0) circle (.5cm);
970 \end{codeexample}
971
972 The shadings as well as additional shadings are described in more detail in
973 Section~\ref{section-library-shadings}.
974
975 To change the color of a shading, special options are needed like
976 |left color|, which sets the color of an axis shading from left to right.
977 These options implicitly also select the correct shading type, see the
978 following example
979 %
980 \begin{codeexample}[]
981 \tikz \shadedraw [left color=red,right color=blue]
982 (0,0) rectangle (1,1);
983 \end{codeexample}
984
985 For a complete list of the possible options see
986 Section~\ref{section-library-shadings} once more.
987
988 \begin{key}{/tikz/shading angle=\meta{degrees} (initially 0)}
989 This option rotates the shading (not the path!) by the given angle. For
990 example, we can turn a top-to-bottom axis shading into a left-to-right
991 shading by rotating it by $90^\circ$.
992 %
993 \begin{codeexample}[]
994 \tikz \shadedraw [shading=axis,shading angle=90] (0,0) rectangle (1,1);
995 \end{codeexample}
996 \end{key}
997 \end{key}
998
999 You can also define new shading types yourself. However, for this, you need to
1000 use the basic layer directly, which is, well, more basic and harder to use.
1001 Details on how to create a shading appropriate for filling paths are given in
1002 Section~\ref{section-shading-a-path}.
1003
1004
1005 \subsection{Establishing a Bounding Box}
1006
1007 \pgfname\ is reasonably good at keeping track of the size of your picture and
1008 reserving just the right amount of space for it in the main document. However,
1009 in some cases you may want to say things like ``do not count this for the
1010 picture size'' or ``the picture is actually a little large''. For this you can
1011 use the option |use as bounding box| or the command |\useasboundingbox|, which
1012 is just a shorthand for |\path[use as bounding box]|.
1013
1014 \begin{key}{/tikz/use as bounding box}
1015 Normally, when this option is given on a path, the bounding box of the
1016 present path is used to determine the size of the picture and the size of
1017 all \emph{subsequent} paths are ignored. However, if there were previous
1018 path operations that have already established a larger bounding box, it
1019 will not be made smaller by this operation (consider the
1020 |\pgfresetboundingbox| command to reset the previous bounding box).
1021
1022 In a sense, |use as bounding box| has the same effect as clipping all
1023 subsequent drawing against the current path -- without actually doing the
1024 clipping, only making \pgfname\ treat everything as if it were clipped.
1025
1026 The first application of this option is to have a |{tikzpicture}| overlap
1027 with the main text:
1028 %
1029 \begin{codeexample}[]
1030 Left of picture\begin{tikzpicture}
1031 \draw[use as bounding box] (2,0) rectangle (3,1);
1032 \draw (1,0) -- (4,.75);
1033 \end{tikzpicture}right of picture.
1034 \end{codeexample}
1035
1036 In a second application this option can be used to get better control over
1037 the white space around the picture:
1038 %
1039 \begin{codeexample}[]
1040 Left of picture
1041 \begin{tikzpicture}
1042 \useasboundingbox (0,0) rectangle (3,1);
1043 \fill (.75,.25) circle (.5cm);
1044 \end{tikzpicture}
1045 right of picture.
1046 \end{codeexample}
1047
1048 Note: If this option is used on a path inside a \TeX\ group (scope), the
1049 effect ``lasts'' only until the end of the scope. Again, this behavior is
1050 the same as for clipping.
1051
1052 Consider using |\useasboundingbox| together with |\pgfresetboundingbox| in
1053 order to replace the bounding box with a new one.
1054 \end{key}
1055
1056 There is a node that allows you to get the size of the current bounding box.
1057 The |current bounding box| node has the |rectangle| shape and its size is
1058 always the size of the current bounding box.
1059
1060 Similarly, the |current path bounding box| node has the |rectangle| shape and
1061 the size of the bounding box of the current path.
1062 %
1063 \begin{codeexample}[]
1064 \begin{tikzpicture}
1065 \draw[red] (0,0) circle (2pt);
1066 \draw[red] (2,1) circle (3pt);
1067
1068 \draw (current bounding box.south west) rectangle
1069 (current bounding box.north east);
1070
1071 \draw[red] (3,-1) circle (4pt);
1072
1073 \draw[thick] (current bounding box.south west) rectangle
1074 (current bounding box.north east);
1075 \end{tikzpicture}
1076 \end{codeexample}
1077
1078 Occasionally, you may want to align multiple |tikzpicture| environments
1079 horizontally and/or vertically at some prescribed position. The vertical
1080 alignment can be realized by means of the |baseline| option since \TeX\
1081 supports the concept of box depth natively. For horizontal alignment, things
1082 are slightly more involved. The following approach is realized by means of
1083 negative |\hspace|s before and/or after the picture, thereby removing parts of
1084 the picture. However, the actual amount of negative horizontal space is
1085 provided by means of image coordinates using the |trim left| and |trim right|
1086 keys:
1087
1088 \begin{key}{/tikz/trim left=\meta{dimension or coordinate or \texttt{default}} (default 0pt)}
1089 The |trim left| key tells \pgfname\space to discard everything which is
1090 left of the provided \meta{dimension or coordinate}. Here, \meta{dimension}
1091 is a single $x$ coordinate of the picture and \meta{coordinate} is a point
1092 with $x$ and $y$ coordinates (but only its $x$ coordinate will be used).
1093 The effect is the same as if you issue |\hspace{-s}| where |s| is the
1094 difference of the picture's bounding box lower left $x$ coordinate and the
1095 $x$ coordinate specified as \meta{dimension or coordinate}:
1096 %
1097 \begin{codeexample}[]
1098 Text before image.%
1099 \begin{tikzpicture}[trim left]
1100 \draw (-1,-1) grid (3,2);
1101 \fill (0,0) circle (5pt);
1102 \end{tikzpicture}%
1103 Text after image.
1104 \end{codeexample}
1105 %
1106 Since |trim left| uses the default |trim left=0pt|, everything left of
1107 $x=0$ is removed from the bounding box.
1108
1109 The following example has once the relative long label $-1$ and once the
1110 shorter label $1$. Horizontal alignment is established with |trim left|:
1111 %
1112 \begin{codeexample}[pre={\vbox\bgroup\hsize=5cm},post=\egroup,width=8cm]
1113 \begin{tikzpicture}
1114 \draw (0,1) -- (0,0) -- (1,1) -- cycle;
1115 \fill (0,0) circle (2pt);
1116 \node[left] at (0,0) {$-1$};
1117 \end{tikzpicture}
1118 \par
1119 \begin{tikzpicture}
1120 \draw (0,1) -- (0,0) -- (1,1) -- cycle;
1121 \fill (0,0) circle (2pt);
1122 \node[left] at (0,0) {$1$};
1123 \end{tikzpicture}
1124 \par
1125 \begin{tikzpicture}[trim left]
1126 \draw (0,1) -- (0,0) -- (1,1) -- cycle;
1127 \fill (0,0) circle (2pt);
1128 \node[left] at (0,0) {$-1$};
1129 \end{tikzpicture}
1130 \par
1131 \begin{tikzpicture}[trim left]
1132 \draw (0,1) -- (0,0) -- (1,1) -- cycle;
1133 \fill (0,0) circle (2pt);
1134 \node[left] at (0,0) {$1$};
1135 \end{tikzpicture}
1136 \end{codeexample}
1137
1138 Use |trim left=default| to reset the value.
1139 \end{key}
1140
1141 \begin{key}{/tikz/trim right=\meta{dimension or coordinate or \texttt{default}}}
1142 This key is similar to |trim left|: it discards everything which is right
1143 of the provided \meta{dimension or coordinate}. As for |trim left|,
1144 \meta{dimension} denotes a single $x$ coordinate of the picture and
1145 \meta{coordinate} a coordinate with $x$ and $y$ value (although only its
1146 $x$ component will be used).
1147
1148 We use the same example from above and add |trim right|:
1149 %
1150 \begin{codeexample}[]
1151 Text before image.%
1152 \begin{tikzpicture}[trim left, trim right=2cm, baseline]
1153 \draw (-1,-1) grid (3,2);
1154 \fill (0,0) circle (5pt);
1155 \end{tikzpicture}%
1156 Text after image.
1157 \end{codeexample}
1158 %
1159 In addition to |trim left=0pt|, we also discard everything which is right
1160 of $x$|=2cm|. Furthermore, the |baseline| key supports vertical alignment
1161 as well (using the $y$|=0cm| baseline).
1162
1163 Use |trim right=default| to reset the value.
1164 \end{key}
1165
1166 Note that |baseline|, |trim left| and |trim right| are currently the
1167 \emph{only} supported way of truncated bounding boxes which are compatible with
1168 image externalization (see the |external| library for details).
1169
1170 \begin{key}{/pgf/trim lowlevel=\mchoice{true,false} (initially false)}
1171 This affects only the basic level image externalization: the initial
1172 configuration |trim lowlevel=false| stores the normal image, without
1173 trimming, and the trimming into a separate file. This allows reduced
1174 bounding boxes without clipping the rest away. The |trim lowlevel=true|
1175 information causes the image externalization to store the trimmed image,
1176 possibly resulting in clipping.
1177 \end{key}
1178
1179
1180 \subsection{Clipping and Fading (Soft Clipping)}
1181
1182 \emph{Clipping path} means that all painting on the page is restricted to a
1183 certain area. This area need not be rectangular, rather an arbitrary path can
1184 be used to specify this area. The |clip| option, explained below, is used to
1185 specify the region that is to be used for clipping.
1186
1187 A \emph{fading} (a term that I propose, fadings are commonly known as soft
1188 masks, transparency masks, opacity masks or soft clips) is similar to clipping,
1189 but a fading allows parts of the picture to be only ``half clipped''. This
1190 means that a fading can specify that newly painted pixels should be partly
1191 transparent. The specification and handling of fadings is a bit complex and it
1192 is detailed in Section~\ref{section-tikz-transparency}, which is devoted to
1193 transparency in general.
1194
1195 \begin{key}{/tikz/clip}
1196 This option causes all subsequent drawings to be clipped against the
1197 current path and the size of subsequent paths will not be important for the
1198 picture size. If you clip against a self-intersecting path, the even-odd
1199 rule or the nonzero winding number rule is used to determine whether a
1200 point is inside or outside the clipping region.
1201
1202 The clipping path is a graphic state parameter, so it will be reset at the
1203 end of the current scope. Multiple clippings accumulate, that is, clipping
1204 is always done against the intersection of all clipping areas that have
1205 been specified inside the current scopes. The only way of enlarging the
1206 clipping area is to end a |{scope}|.
1207 %
1208 \begin{codeexample}[]
1209 \begin{tikzpicture}
1210 \draw[clip] (0,0) circle (1cm);
1211 \fill[red] (1,0) circle (1cm);
1212 \end{tikzpicture}
1213 \end{codeexample}
1214
1215 It is usually a \emph{very} good idea to apply the |clip| option only to
1216 the first path command in a scope.
1217
1218 If you ``only wish to clip'' and do not wish to draw anything, you can use
1219 the |\clip| command, which is a shorthand for |\path[clip]|.
1220 %
1221 \begin{codeexample}[]
1222 \begin{tikzpicture}
1223 \clip (0,0) circle (1cm);
1224 \fill[red] (1,0) circle (1cm);
1225 \end{tikzpicture}
1226 \end{codeexample}
1227
1228 To keep clipping local, use |{scope}| environments as in the following
1229 example:
1230 %
1231 \begin{codeexample}[]
1232 \begin{tikzpicture}
1233 \draw (0,0) -- ( 0:1cm);
1234 \draw (0,0) -- (10:1cm);
1235 \draw (0,0) -- (20:1cm);
1236 \draw (0,0) -- (30:1cm);
1237 \begin{scope}[fill=red]
1238 \fill[clip] (0.2,0.2) rectangle (0.5,0.5);
1239
1240 \draw (0,0) -- (40:1cm);
1241 \draw (0,0) -- (50:1cm);
1242 \draw (0,0) -- (60:1cm);
1243 \end{scope}
1244 \draw (0,0) -- (70:1cm);
1245 \draw (0,0) -- (80:1cm);
1246 \draw (0,0) -- (90:1cm);
1247 \end{tikzpicture}
1248 \end{codeexample}
1249
1250 There is a slightly annoying catch: You cannot specify certain graphic
1251 options for the command used for clipping. For example, in the above code
1252 we could not have moved the |fill=red| to the |\fill| command. The reasons
1253 for this have to do with the internals of the \pdf\ specification. You do
1254 not want to know the details. It is best simply not to specify any options
1255 for these commands.
1256 \end{key}
1257
1258
1259 \subsection{Doing Multiple Actions on a Path}
1260
1261 If more than one of the basic actions like drawing, clipping and filling are
1262 requested, they are automatically applied in a sensible order: First, a path is
1263 filled, then drawn, and then clipped (although it took Apple two major
1264 revisions of their operating system to get this right\dots). Sometimes,
1265 however, you need finer control over what is done with a path. For instance,
1266 you might wish to first fill a path with a color, then repaint the path with a
1267 pattern and then repaint it with yet another pattern. In such cases you can use
1268 the following two options:
1269
1270 \begin{key}{/tikz/preaction=\meta{options}}
1271 This option can be given to a |\path| command (or to derived commands like
1272 |\draw| which internally call |\path|). Similarly to options like |draw|,
1273 this option only has an effect when given to a |\path| or as part of the
1274 options of a |node|; as an option to a |{scope}| it has no effect.
1275
1276 When this option is used on a |\path|, the effect is the following: When
1277 the path has been completely constructed and is about to be used, a scope
1278 is created. Inside this scope, the path is used but not with the original
1279 path options, but with \meta{options} instead. Then, the path is used in
1280 the usual manner. In other words, the path is used twice: Once with
1281 \meta{options} in force and then again with the normal path options in
1282 force.
1283
1284 Here is an example in which the path consists of a rectangle. The main
1285 action is to draw this path in red (which is why we see a red rectangle).
1286 However, the preaction is to draw the path in blue, which is why we see a
1287 blue rectangle behind the red rectangle.
1288 %
1289 \begin{codeexample}[]
1290 \begin{tikzpicture}
1291 \draw[help lines] (0,0) grid (3,2);
1292
1293 \draw
1294 [preaction={draw,line width=4mm,blue}]
1295 [line width=2mm,red] (0,0) rectangle (2,2);
1296 \end{tikzpicture}
1297 \end{codeexample}
1298
1299 Note that when the preactions are performed, then the path is already
1300 ``finished''. In particular, applying a coordinate transformation to the
1301 path has no effect. By comparison, applying a canvas transformation does
1302 have an effect. Let us use this to add a ``shadow'' to a path. For this, we
1303 use the preaction to fill the path in gray, shifted a bit to the right and
1304 down:
1305 %
1306 \begin{codeexample}[]
1307 \begin{tikzpicture}
1308 \draw[help lines] (0,0) grid (3,2);
1309 \draw
1310 [preaction={fill=black,opacity=.5,
1311 transform canvas={xshift=1mm,yshift=-1mm}}]
1312 [fill=red] (0,0) rectangle (1,2)
1313 (1,2) circle (5mm);
1314 \end{tikzpicture}
1315 \end{codeexample}
1316
1317 Naturally, you would normally create a style |shadow| that contains the
1318 above code. The |shadows| library, see Section~\ref{section-libs-shadows},
1319 contains predefined shadows of this kind.
1320
1321 It is possible to use the |preaction| option multiple times. In this case,
1322 for each use of the |preaction| option, the path is used again (thus, the
1323 \meta{options} do not accumulate in a single usage of the path). The path
1324 is used in the order of |preaction| options given.
1325
1326 In the following example, we use one |preaction| to add a shadow and
1327 another to provide a shading, while the main action is to use a pattern.
1328 %
1329 \begin{codeexample}[preamble={\usetikzlibrary{patterns}}]
1330 \begin{tikzpicture}
1331 \draw[help lines] (0,0) grid (3,2);
1332 \draw [pattern=fivepointed stars]
1333 [preaction={fill=black,opacity=.5,
1334 transform canvas={xshift=1mm,yshift=-1mm}}]
1335 [preaction={top color=blue,bottom color=white}]
1336 (0,0) rectangle (1,2)
1337 (1,2) circle (5mm);
1338 \end{tikzpicture}
1339 \end{codeexample}
1340
1341 A complicated application is shown in the following example, where the path
1342 is used several times with different fadings and shadings to create a
1343 special visual effect:
1344 %
1345 \begin{codeexample}[preamble={\usetikzlibrary{fadings,patterns}}]
1346 \begin{tikzpicture}
1347 [
1348 % Define an interesting style
1349 button/.style={
1350 % First preaction: Fuzzy shadow
1351 preaction={fill=black,path fading=circle with fuzzy edge 20 percent,
1352 opacity=.5,transform canvas={xshift=1mm,yshift=-1mm}},
1353 % Second preaction: Background pattern
1354 preaction={pattern=#1,
1355 path fading=circle with fuzzy edge 15 percent},
1356 % Third preaction: Make background shiny
1357 preaction={top color=white,
1358 bottom color=black!50,
1359 shading angle=45,
1360 path fading=circle with fuzzy edge 15 percent,
1361 opacity=0.2},
1362 % Fourth preaction: Make edge especially shiny
1363 preaction={path fading=fuzzy ring 15 percent,
1364 top color=black!5,
1365 bottom color=black!80,
1366 shading angle=45},
1367 inner sep=2ex
1368 },
1369 button/.default=horizontal lines light blue,
1370 circle
1371 ]
1372
1373 \draw [help lines] (0,0) grid (4,3);
1374
1375 \node [button] at (2.2,1) {\Huge Big};
1376 \node [button=crosshatch dots light steel blue,
1377 text=white] at (1,1.5) {Small};
1378 \end{tikzpicture}
1379 \end{codeexample}
1380 %
1381 \end{key}
1382
1383 \begin{key}{/tikz/postaction=\meta{options}}
1384 The postactions work in the same way as the preactions, only they are
1385 applied \emph{after} the main action has been taken. Like preactions,
1386 multiple |postaction| options may be given to a |\path| command, in which
1387 case the path is reused several times, each time with a different set of
1388 options in force.
1389
1390 If both pre- and postactions are specified, then the preactions are taken
1391 first, then the main action, and then the post actions.
1392
1393 In the first example, we use a postaction to draw the path, after it has
1394 already been drawn:
1395 %
1396 \begin{codeexample}[]
1397 \begin{tikzpicture}
1398 \draw[help lines] (0,0) grid (3,2);
1399
1400 \draw
1401 [postaction={draw,line width=2mm,blue}]
1402 [line width=4mm,red,fill=white] (0,0) rectangle (2,2);
1403 \end{tikzpicture}
1404 \end{codeexample}
1405
1406 In another example, we use a postaction to ``colorize'' a path:
1407 %
1408 \begin{codeexample}[preamble={\usetikzlibrary{fadings}}]
1409 \begin{tikzpicture}
1410 \draw[help lines] (0,0) grid (3,2);
1411 \draw
1412 [postaction={path fading=south,fill=white}]
1413 [postaction={path fading=south,fading angle=45,fill=blue,opacity=.5}]
1414 [left color=black,right color=red,draw=white,line width=2mm]
1415 (0,0) rectangle (1,2)
1416 (1,2) circle (5mm);
1417 \end{tikzpicture}
1418 \end{codeexample}
1419 %
1420 \end{key}
1421
1422
1423 \subsection{Decorating and Morphing a Path}
1424
1425 Before a path is used, it is possible to first ``decorate'' and/or ``morph''
1426 it. Morphing means that the path is replaced by another path that is slightly
1427 varied. Such morphings are a special case of the more general ``decorations''
1428 described in detail in Section~\ref{section-tikz-decorations}. For instance, in
1429 the following example the path is drawn twice: Once normally and then in a
1430 morphed (=decorated) manner.
1431 %
1432 \begin{codeexample}[preamble={\usetikzlibrary{decorations.pathmorphing}}]
1433 \begin{tikzpicture}
1434 \draw (0,0) rectangle (3,2);
1435 \draw [red, decorate, decoration=zigzag]
1436 (0,0) rectangle (3,2);
1437 \end{tikzpicture}
1438 \end{codeexample}
1439
1440 Naturally, we could have combined this into a single command using pre- or
1441 postaction. It is also possible to deform shapes:
1442 %
1443 \begin{codeexample}[preamble={\usetikzlibrary{decorations.pathmorphing,shadows}}]
1444 \begin{tikzpicture}
1445 \node [circular drop shadow={shadow scale=1.05},minimum size=3.13cm,
1446 decorate, decoration=zigzag,
1447 fill=blue!20,draw,thick,circle] {Hello!};
1448 \end{tikzpicture}
1449 \end{codeexample}