Debian Codegraph @

texmf-dist/doc/generic/pgf/pgfmanual-en-tikz-arrows.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 \section{Arrows}
11 \label{section-tikz-arrows}
12
13 \subsection{Overview}
14
15 \tikzname\ allows you to add (multiple) arrow tips to the end of lines as in
16 \tikz [baseline] \draw [->>] (0,.5ex) -- (3ex,.5ex); or in \tikz [baseline]
17 \draw [-{Latex[]}] (0,.5ex) -- (3ex,.5ex);. It is possible to change which
18 arrow tips are used ``on-the-fly'', you can have several arrow tips in a row,
19 and you can change the appearance of each of them individually using a special
20 syntax. The following example is a perhaps slightly ``excessive'' demonstration
21 of what you can do (you need to load the |arrows.meta| library for it to work):
22 %
23 \begin{codeexample}[preamble={\usetikzlibrary{arrows.meta,bending,positioning}}]
24 \tikz {
25 \node [circle,draw] (A) {A};
26 \node [circle,draw] (B) [right=of A] {B};
27
28 \draw [draw = blue, thick,
29 arrows={
30 Computer Modern Rightarrow [sep]
31 - Latex[blue!50,length=8pt,bend,line width=0pt]
32 Stealth[length=8pt,open,bend,sep]}]
33 (A) edge [bend left=45] (B)
34 (B) edge [in=-110, out=-70,looseness=8] (B);
35 }
36 \end{codeexample}
37
38 There are a number of predefined generic arrow tip kinds whose appearance you
39 can modify in many ways using various options. It is also possible to define
40 completely new arrow tip kinds, see Section~\ref{section-arrows}, but doing
41 this is somewhat harder than configuring an existing kind (it is like the
42 difference between using a font at different sizes or faces like italics,
43 compared to designing a new font yourself).
44
45 In the present section, we go over the various ways in which you can configure
46 which particular arrow tips are \emph{used}. The glorious details of how new
47 arrow tips can be defined are explained in Section~\ref{section-arrows}.
48
49 At the end of the present section, Section~\ref{section-arrows-meta}, you will
50 find a description of the different predefined arrow tips from the
51 |arrows.meta| library.
52
53 \emph{Remark:} Almost all of the features described in the following were
54 introduced in version 3.0 of \tikzname. For compatibility reasons, the old
55 arrow tips are still available. To differentiate between the old and new arrow
56 tips, the following rule is used: The new, more powerful arrow tips start with
57 an uppercase letter as in |Latex|, compared to the old arrow tip |latex|.
58
59 \emph{Remark:} The libraries |arrows| and |arrows.spaced| are deprecated. Use
60 |arrows.meta| instead/additionally, which allows you to do all that the old
61 libraries offered, plus much more. However, the old libraries still work and
62 you can even mix old and new arrow tips (only, the old arrow tips cannot be
63 configured in the ways described in the rest of this section; saying |scale=2|
64 for a |latex| arrow has no effect for instance, while for |Latex| arrows it
65 doubles their size as one would expect.)
66
67
68 \subsection{Where and When Arrow Tips Are Placed}
69 \label{section-arrow-tips-where}
70
71 In order to add arrow tips to the lines you draw, the following conditions must
72 be met:
73 %
74 \begin{enumerate}
75 \item You have specified that arrow tips should be added to lines, using
76 the |arrows| key or its short form.
77 \item You set the |tips| key to some value that causes tips to be drawn
78 (to be explained later).
79 \item You do not use the |clip| key (directly or indirectly) with the
80 current path.
81 \item The path actually has two ``end points'' (it is not ``closed'').
82 \end{enumerate}
83
84 Let us start with an introduction to the basics of the |arrows| key:
85
86 \begin{key}{/tikz/arrows=\meta{start arrow specification}|-|\meta{end arrow specification}}
87 This option sets the arrow tip(s) to be used at the start and end of lines.
88 An empty value as in |->| for the start indicates that no arrow tip should
89 be drawn at the start.%
90 \indexoption{arrows}
91
92 \emph{Note: Since the arrow option is so often used, you can leave out the
93 text |arrows=|.} What happens is that every (otherwise unknown) option that
94 contains a |-| is interpreted as an arrow specification.
95 %
96 \begin{codeexample}[preamble={\usetikzlibrary{arrows.meta}}]
97 \begin{tikzpicture}
98 \draw[->] (0,0) -- (1,0);
99 \draw[>-Stealth] (0,0.3) -- (1,0.3);
100 \end{tikzpicture}
101 \end{codeexample}
102
103 In the above example, the first start specification is empty and the second
104 is |>|. The end specifications are |>| for the first line and |Stealth| for
105 the second line. Note that it makes a difference whether |>| is used in a
106 start specification or in an end specification: In an end specification it
107 creates, as one would expect, a pointed tip at the end of the line. In the
108 start specification, however, it creates a ``reversed'' version if this
109 arrow -- which happens to be what one would expect here.
110
111 The above specifications are very simple and only select a single arrow tip
112 without any special configuration options, resulting in the ``natural''
113 versions of these arrow tips. It is also possible to ``configure'' arrow
114 tips in many different ways, as explained in detail in
115 Section~\ref{section-arrow-config} below by adding options in square
116 brackets following the arrow tip kind:
117 %
118 \begin{codeexample}[preamble={\usetikzlibrary{arrows.meta}}]
119 \begin{tikzpicture}
120 \draw[-{Stealth[red]}] (0,0) -- (1,0);
121 \end{tikzpicture}
122 \end{codeexample}
123
124 Note that in the example I had to surround the end specification by braces.
125 This is necessary so that \tikzname\ does not mistake the closing square
126 bracket of the |Stealth| arrow tip's options for the end of the options of
127 the |\draw| command. In general, you often need to add braces when
128 specifying arrow tips except for simple case like |->| or |<<->|, which are
129 pretty frequent, though. When in doubt, say
130 |arrows={|\meta{start spec}|-|\meta{end spec}|}|, that will always work.
131
132 It is also possible to specify multiple (different) arrow tips in a row
133 inside a specification, see Section~\ref{section-arrow-spec} below for
134 details.
135 \end{key}
136
137 As was pointed out earlier, to add arrow tips to a path, the path must have
138 ``end points'' and not be ``closed'' -- otherwise adding arrow tips makes
139 little sense, after all. However, a path can actually consist of several
140 subpath, which may be open or not and may even consist of only a single point
141 (a single move-to). In this case, it is not immediately obvious, where arrow
142 heads should be placed. The actual rules that \tikzname\ uses are governed by
143 the setting of the key |tips|:
144
145 \begin{key}{/pgf/tips=\meta{value} (default true, initially on draw)}
146 \keyalias{tikz}
147 This key governs in what situations arrow tips are added to a path. The
148 following \meta{values} are permissible:
149 %
150 \begin{itemize}
151 \item |true| (the value used when no \meta{value} is specified)
152 \item |proper|
153 \item |on draw| (the initial value, if the key has not yet been used
154 at all)
155 \item |on proper draw|
156 \item |never| or |false| (same effect)
157 \end{itemize}
158
159 Firstly, there are a whole bunch of situations where the setting of
160 these (or other) options causes no arrow tips to be shown:
161 %
162 \begin{itemize}
163 \item If no arrow tips have been specified (for instance, by having
164 said |arrows=-|), no arrow tips are drawn.
165 \item If the |clip| option is set, no arrow tips are drawn.
166 \item If |tips| has been set to |never| or |false|, no arrow tips are
167 drawn.
168 \item If |tips| has been set to |on draw| or |on proper draw|, but
169 the |draw| option is not set, no arrow tips are drawn.
170 \item If the path is empty (as in |\path ;|), no arrow tips are
171 drawn.
172 \item If at least one of the subpaths of a path is closed (|cycle| is
173 used somewhere or something like |circle| or |rectangle|), arrow
174 tips are never drawn anywhere -- even if there are open subpaths.
175 \end{itemize}
176
177 Now, if we pass all of the above tests, we must have a closer look at the
178 path. All its subpaths must now be open and there must be at least one
179 subpath. We consider the last one. Arrow tips will only be added to this
180 last subpath.
181
182 \begin{enumerate}
183 \item If this last subpath not degenerate (all coordinates on the
184 subpath are the same as in a single ``move-to'' |\path (0,0);| or
185 in a ``move-to'' followed by a ``line-to'' to the same position
186 as in |\path (1,2) -- (1,2)|), arrow tips are added to this last
187 subpath now.
188 \item If the last subpath is degenerate, we add arrow tips pointing
189 upward at the single coordinate mentioned in the path, but only
190 for |tips| begin set to |true| or to |on draw| -- and not for
191 |proper| nor for |on proper draw|. In other words, ``proper''
192 suppresses arrow tips on degenerate paths.
193 \end{enumerate}
194
195 \begin{codeexample}[]
196 % No path, no arrow tips:
197 \tikz [<->] \draw;
198 \end{codeexample}
199 \begin{codeexample}[]
200 % Degenerate path, draw arrow tips (but no path, it is degenerate...)
201 \tikz [<->] \draw (0,0);
202 \end{codeexample}
203 \begin{codeexample}[]
204 % Degenerate path, tips=proper suppresses arrows
205 \tikz [<->] \draw [tips=proper] (0,0);
206 \end{codeexample}
207 \begin{codeexample}[]
208 % Normal case:
209 \tikz [<->] \draw (0,0) -- (1,0);
210 \end{codeexample}
211 \begin{codeexample}[]
212 % Two subpaths, only second gets tips
213 \tikz [<->] \draw (0,0) -- (1,0) (2,0) -- (3,0);
214 \end{codeexample}
215 \begin{codeexample}[]
216 % Two subpaths, second degenerate, but still gets tips
217 \tikz [<->] \draw (0,0) -- (1,0) (2,0);
218 \end{codeexample}
219 \begin{codeexample}[]
220 % Two subpaths, second degenerate, proper suppresses them
221 \tikz [<->] \draw [tips=on proper draw] (0,0) -- (1,0) (2,0);
222 \end{codeexample}
223 \begin{codeexample}[]
224 % Two subpaths, but one is closed: No tips, even though last subpath is open
225 \tikz [<->] \draw (0,0) circle[radius=2pt] (2,0) -- (3,0);
226 \end{codeexample}
227 %
228 \end{key}
229
230 One common pitfall when arrow tips are added to a path should be addressed
231 right here at the beginning: When \tikzname\ positions an arrow tip at the
232 start, for all its computations it only takes into account the first segment of
233 the subpath to which the arrow tip is added. This ``first segment'' is the
234 first line-to or curve-to operation (or arc or parabola or a similar operation)
235 of the path; but note that decorations like |snake| will add many small line
236 segments to paths. The important point is that if this first segment is very
237 small, namely smaller that the arrow tip itself, strange things may result. As
238 will be explained in Section~\ref{section-arrow-flex}, \tikzname\ will modify
239 the path by shortening the first segment and shortening a segment below its
240 length may result in strange effects. Similarly, for tips at the end of a
241 subpath, only the last segment is considered.
242
243 The bottom line is that wherever an arrow tip is added to a path, the line
244 segment where it is added should be ``long enough''.
245
246
247 \subsection{Arrow Keys: Configuring the Appearance of a Single Arrow Tip}
248 \label{section-arrow-config}
249
250 For standard arrow tip kinds, like |Stealth| or |Latex| or |Bar|, you can
251 easily change their size, aspect ratio, color, and other parameters. This is
252 similar to selecting a font face from a font family: \emph{``This text''} is
253 not just typeset in the font ``Computer Modern'', but rather in ``Computer
254 Modern, italic face, 11pt size, medium weight, black color, no underline,
255 \dots'' Similarly, an arrow tip is not just a ``Stealth'' arrow tip, but rather
256 a ``Stealth arrow tip at its natural size, flexing, but not bending along the
257 path, miter line caps, draw and fill colors identical to the path draw color,
258 \dots''
259
260 Just as most programs make it easy to ``configure'' which font should be used
261 at a certain point in a text, \tikzname\ tries to make it easy to specify which
262 configuration of an arrow tip should be used. You use \emph{arrow keys}, where
263 a certain parameter like the |length| of an arrow is set to a given value using
264 the standard key--value syntax. You can provide several arrow keys following an
265 arrow tip kind in an arrow tip specification as in
266 |Stealth[length=4pt,width=2pt]|.
267
268 While selecting a font may be easy, \emph{designing} a new font is a highly
269 creative and difficult process and more often than not, not all faces of a font
270 are available on any given system. The difficulties involved in designing a new
271 arrow tip are somewhat similar to designing a new letter for a font and, thus,
272 it may also happen that not all configuration options are actually implemented
273 for a given arrow tip. Naturally, for the standard arrow tips, all
274 configuration options are available -- but for special-purpose arrow tips it
275 may well happen that an arrow tip kind simply ``ignores'' some of the
276 configurations given by you.
277
278 Some of the keys explained in the following are defined in the library
279 |arrows.meta|, others are always available. This has to do with the question of
280 whether the arrow key needs to be supported directly in the \pgfname\ core or
281 not. In general, the following explanations assume that |arrows.meta| has been
282 loaded.
283
284
285 \subsubsection{Size}
286
287 The most important configuration parameter of an arrow tip is undoubtedly its
288 size. The following two keys are the main keys that are important in this
289 context:
290
291 \begin{key}{/pgf/arrow keys/length=\meta{dimension}| |\opt{\meta{line width factor}}%
292 | |\opt{\meta{outer factor}}}
293 \label{length-arrow-key}%
294 This parameter is usually the most important parameter that governs the
295 size of an arrow tip: The \meta{dimension} that you provide dictates the
296 distance from the ``very tip'' of the arrow to its ``back end'' along the
297 line:
298 %
299 \begin{codeexample}[preamble={\usetikzlibrary{arrows.meta}}]
300 \tikz{
301 \draw [-{Stealth[length=5mm]}] (0,0) -- (2,0);
302 \draw [|<->|] (1.5,.4) -- node[above=1mm] {5mm} (2,.4);
303 }
304 \end{codeexample}
305 \begin{codeexample}[preamble={\usetikzlibrary{arrows.meta}}]
306 \tikz{
307 \draw [-{Latex[length=5mm]}] (0,0) -- (2,0);
308 \draw [|<->|] (1.5,.4) -- node[above=1mm] {5mm} (2,.4);
309 }
310 \end{codeexample}
311 \begin{codeexample}[preamble={\usetikzlibrary{arrows.meta}}]
312 \tikz{
313 \draw [-{Classical TikZ Rightarrow[length=5mm]}] (0,0) -- (2,0);
314 \draw [|<->|] (1.5,.6) -- node[above=1mm] {5mm} (2,.6);
315 }
316 \end{codeexample}
317
318 \medskip
319 \noindent \textbf{The Line Width Factors.}
320 Following the \meta{dimension}, you may put a space followed by a
321 \meta{line width factor}, which must be a plain number (no |pt| or |cm|
322 following). When you provide such a number, the size of the arrow tip is
323 not just \meta{dimension}, but rather $\meta{dimension} + \meta{line width
324 factor}\cdot w$ where $w$ is the width of the to-be-drawn path. This makes
325 it easy to vary the size of an arrow tip in accordance with the line width
326 -- usually a very good idea since thicker lines will need thicker arrow
327 tips.
328
329 As an example, when you write |length=0pt 5|, the length of the arrow will
330 be exactly five times the current line width. As another example, the
331 default length of a |Latex| arrow is |length=3pt 4.5 0.8|. Let us ignore
332 the 0.8 for a moment; the |3pt 4.5| then means that for the standard line
333 width of |0.4pt|, the length of a |Latex| arrow will be exactly 4.8pt (3pt
334 plus 4.5 times |0.4pt|).
335
336 Following the line width factor, you can additionally provide an
337 \meta{outer factor}, again preceded by a space (the |0.8| in the above
338 example). This factor is taken into consideration only when the |double|
339 option is used, that is, when a so-called ``inner line width''. For a
340 double line, we can identify three different ``line widths'', namely the
341 inner line width $w_i$, the line width $w_o$ of the two outer lines, and
342 the ``total line width'' $w_t = w_i + 2w_o$. In the below examples, we have
343 $w_i = 3\mathrm{pt}$, $w_o=1\mathrm{pt}$, and $w_t = 5\mathrm{pt}$. It is
344 not immediately clear which of these line widths should be considered as
345 $w$ in the above formula $\meta{dimension} + \meta{line width factor}\cdot
346 w$ for the computation of the length. One can argue both for $w_t$ and also
347 for $w_o$. Because of this, you use the \meta{outer factor} to decide on
348 one of them or even mix them: \tikzname\ sets $w = \meta{outer factor} w_o
349 + (1-\meta{outer factor})w_t$. Thus, when the outer factor is $0$, as in
350 the first of the following examples and as is the default when it is not
351 specified, the computed $w$ will be the total line width $w_t =
352 5\mathrm{pt}$. Since $w=5\mathrm{pt}$, we get a total length of $15pt$ in
353 the first example (because of the factor |3|). In contrast, in the last
354 example, the outer factor is 1 and, thus, $w = w_o = \mathrm{1pt}$ and the
355 resulting length is 3pt. Finally, for the middle case, the ``middle''
356 between 5pt and 1pt is 3pt, so the length is 9pt.
357 %
358 \begin{codeexample}[preamble={\usetikzlibrary{arrows.meta}}]
359 \tikz \draw [line width=1pt, double distance=3pt,
360 arrows = {-Latex[length=0pt 3 0]}] (0,0) -- (1,0);
361 \end{codeexample}
362 \begin{codeexample}[preamble={\usetikzlibrary{arrows.meta}}]
363 \tikz \draw [line width=1pt, double distance=3pt,
364 arrows = {-Latex[length=0pt 3 .5]}] (0,0) -- (1,0);
365 \end{codeexample}
366 \begin{codeexample}[preamble={\usetikzlibrary{arrows.meta}}]
367 \tikz \draw [line width=1pt, double distance=3pt,
368 arrows = {-Latex[length=0pt 3 1]} ] (0,0) -- (1,0);
369 \end{codeexample}
370
371 \medskip
372 \noindent \textbf{The Exact Length.}
373 For an arrow tip kind that is just an outline that is filled with a color,
374 the specified length should \emph{exactly} equal the distance from the tip
375 to the back end. However, when the arrow tip is drawn by stroking a line,
376 it is no longer obvious whether the |length| should refer to the extend of
377 the stroked lines' path or of the resulting pixels (which will be wider
378 because of the thickness of the stroking pen). The rules are as follows:
379 %
380 \begin{enumerate}
381 \item If the arrow tip consists of a closed path (like |Stealth| or
382 |Latex|), imagine the arrow tip drawn from left to right using a
383 miter line cap. Then the |length| should be the horizontal
384 distance from the first drawn ``pixel'' to the last drawn
385 ``pixel''. Thus, the thickness of the stroked line and also the
386 miter ends should be taken into account:
387 %
388 \begin{codeexample}[preamble={\usetikzlibrary{arrows.meta}}]
389 \tikz{
390 \draw [line width=1mm, -{Stealth[length=10mm, open]}]
391 (0,0) -- (2,0);
392 \draw [|<->|] (2,.6) -- node[above=1mm] {10mm} ++(-10mm,0);
393 }
394 \end{codeexample}
395 %
396 \item If, in the above case, the arrow is drawn using a round line
397 join (see Section~\ref{section-arrow-key-caps} for details on how
398 to select this), the size of the arrow should still be the same
399 as in the first case (that is, as if a miter join were used).
400 This creates some ``visual consistency'' if the two modes are
401 mixed or if you later want to change the mode.
402 %
403 \begin{codeexample}[preamble={\usetikzlibrary{arrows.meta}}]
404 \tikz{
405 \draw [line width=1mm, -{Stealth[length=10mm, open, round]}]
406 (0,0) -- (2,0);
407 \draw [|<->|] (2,.6) -- node[above=1mm] {10mm} ++(-10mm,0);
408 }
409 \end{codeexample}
410 %
411 As the above example shows, however, a rounded arrow will still
412 exactly ``tip'' the point where the line should end (the point
413 |(2,0)| in the above case). It is only the scaling of the arrow
414 that is not affected.
415 \end{enumerate}
416 \end{key}
417
418 \begin{key}{/pgf/arrow keys/width=\meta{dimension}| |\opt{\meta{line width factor}}%
419 | |\opt{\meta{outer factor}}}
420 This key works like the |length| key, only it specifies the ``width'' of
421 the arrow tip; so if width and length are identical, the arrow will just
422 touch the borders of a square. (An exception to this rule are ``halved''
423 arrow tips, see Section~\ref{section-arrow-key-harpoon}.) The meaning of
424 the two optional factor numbers following the \meta{dimension} is the same
425 as for the |length| key.
426 %
427 \begin{codeexample}[preamble={\usetikzlibrary{arrows.meta}}]
428 \tikz \draw [arrows = {-Latex[width=10pt, length=10pt]}] (0,0) -- (1,0);
429 \end{codeexample}
430 \begin{codeexample}[preamble={\usetikzlibrary{arrows.meta}}]
431 \tikz \draw [arrows = {-Latex[width=0pt 10, length=10pt]}] (0,0) -- (1,0);
432 \end{codeexample}
433 \end{key}
434
435 \begin{key}{/pgf/arrow keys/width'=\meta{dimension}| |\opt{\meta{length
436 factor}| |\opt{\meta{line width factor}}}}
437 The key (note the prime) has a similar effect as the |width| key. The
438 difference is that the second, still optional parameter \meta{length
439 factor} specifies the width of the key not as a multiple of the line width,
440 but as a multiple of the arrow length.
441
442 The idea is that if you write, say, |width'=0pt 0.5|, the width of the
443 arrow will be half its length. Indeed, for standard arrow tips like
444 |Stealth| the default width is specified in this way so that if you change
445 the length of an arrow tip, you also change the width in such a way that
446 the aspect ratio of the arrow tip is kept. The other way round, if you
447 modify the factor in |width'| without changing the length, you change the
448 aspect ratio of the arrow tip.
449
450 Note that later changes of the length are taken into account for the
451 computation. For instance, if you write
452 %
453 \begin{codeexample}[code only]
454 length = 10pt, width'=5pt 2, length=7pt
455 \end{codeexample}
456 %
457 the resulting width will be $19\mathrm{pt} = 5\mathrm{pt} + 2\cdot
458 7\mathrm{pt}$.
459 %
460 \begin{codeexample}[preamble={\usetikzlibrary{arrows.meta}}]
461 \tikz \draw [arrows = {-Latex[width'=0pt .5, length=10pt]}] (0,0) -- (1,0);
462 \end{codeexample}
463 \begin{codeexample}[preamble={\usetikzlibrary{arrows.meta}}]
464 \tikz \draw [arrows = {-Latex[width'=0pt .5, length=15pt]}] (0,0) -- (1,0);
465 \end{codeexample}
466 %
467 The third, also optional, parameter allows you to add a multiple of the
468 line width to the value computed in terms of the length.
469 \end{key}
470
471
472 \begin{key}{/pgf/arrow keys/inset=\meta{dimension}| |\opt{\meta{line width factor}}%
473 | |\opt{\meta{outer factor}}}
474 The key is relevant only for some arrow tips such as the |Stealth| arrow
475 tip. It specifies a distance by which something inside the arrow tip is set
476 inwards; for the |Stealth| arrow tip it is the distance by which the back
477 angle is moved inwards.
478
479 The computation of the distance works in the same way as for |length| and
480 |width|: To the \meta{dimension} we add \meta{line width factor} times that
481 line width, where the line width is computed based on the \meta{outer
482 factor} as described for the |length| key.
483 %
484 \begin{codeexample}[preamble={\usetikzlibrary{arrows.meta}}]
485 \tikz \draw [arrows = {-Stealth[length=10pt, inset=5pt]}] (0,0) -- (1,0);
486 \end{codeexample}
487 \begin{codeexample}[preamble={\usetikzlibrary{arrows.meta}}]
488 \tikz \draw [arrows = {-Stealth[length=10pt, inset=2pt]}] (0,0) -- (1,0);
489 \end{codeexample}
490
491 For most arrows for which there is no ``natural inset'' like, say, |Latex|,
492 this key has no effect.
493 \end{key}
494
495 \begin{key}{/pgf/arrow keys/inset'=\meta{dimension}| |\opt{\meta{length factor}}| |\opt{\meta{line width factor}}}
496 This key works like |inset|, only like |width'| the second parameter is a
497 factor of the arrow length rather than of the line width. For instance, the
498 |Stealth| arrow sets |inset'| to |0pt 0.325| to ensure that the inset is
499 always at $13/40$th of the arrow length if nothing else is specified.
500 \end{key}
501
502 \begin{key}{/pgf/arrow keys/angle=\meta{angle}|:|\meta{dimension}%
503 | |\opt{\meta{line width factor}}%
504 | |\opt{\meta{outer factor}}}
505 This key sets the |length| and the |width| of an arrow tip at the same
506 time. The length will be the cosine of \meta{angle}, while the width will
507 be twice the sine of half the \meta{angle} (this slightly awkward rule
508 ensures that a |Stealth| arrow will have an opening angle of \meta{angle}
509 at its tip if this option is used). As for the |length| key, if the
510 optional factors are given, they add a certain multiple of the line width
511 to the \meta{dimension} before the sine and cosines are computed.
512 %
513 \begin{codeexample}[preamble={\usetikzlibrary{arrows.meta}}]
514 \tikz \draw [arrows = {-Stealth[inset=0pt, angle=90:10pt]}] (0,0) -- (1,0);
515 \end{codeexample}
516 \begin{codeexample}[preamble={\usetikzlibrary{arrows.meta}}]
517 \tikz \draw [arrows = {-Stealth[inset=0pt, angle=30:10pt]}] (0,0) -- (1,0);
518 \end{codeexample}
519 %
520 \end{key}
521
522 \begin{key}{/pgf/arrow keys/angle'=\meta{angle}}
523 Sets the width of the arrow to twice the tangent of $\meta{angle}/2$ times
524 the arrow length. This results in an arrow tip with an opening angle of
525 \meta{angle} at its tip and with the specified |length| unchanged.
526 %
527 \begin{codeexample}[preamble={\usetikzlibrary{arrows.meta}}]
528 \tikz \draw [arrows = {-Stealth[inset=0pt, length=10pt, angle'=90]}]
529 (0,0) -- (1,0);
530 \end{codeexample}
531 \begin{codeexample}[preamble={\usetikzlibrary{arrows.meta}}]
532 \tikz \draw [arrows = {-Stealth[inset=0pt, length=10pt, angle'=30]}]
533 (0,0) -- (1,0);
534 \end{codeexample}
535 %
536 \end{key}
537
538
539 \subsubsection{Scaling}
540
541 In the previous section we saw that there are many options for getting ``fine
542 control'' overt the length and width of arrow tips. However, in some cases, you
543 do not really care whether the arrow tip is 4pt long or 4.2pt long, you ``just
544 want it to be a little bit larger than usual''. In such cases, the following
545 keys are useful:
546
547 \begin{key}{/pgf/arrow keys/scale=\meta{factor} (initially 1)}
548 After all the other options listed in the previous (and also the following
549 sections) have been processed, \tikzname\ applies a \emph{scaling} to the
550 computed length, inset, and width of the arrow tip (and, possibly, to other
551 size parameters defined by special-purpose arrow tip kinds). Everything is
552 simply scaled by the given \meta{factor}.
553 %
554 \begin{codeexample}[preamble={\usetikzlibrary{arrows.meta}}]
555 \tikz {
556 \draw [arrows = {-Stealth[]}] (0,1) -- (1,1);
557 \draw [arrows = {-Stealth[scale=1.5]}] (0,0.5) -- (1,0.5);
558 \draw [arrows = {-Stealth[scale=2]}] (0,0) -- (1,0);
559 }
560 \end{codeexample}
561 %
562 Note that scaling has \emph{no} effect on the line width (as usual) and
563 also not on the arrow padding (the |sep|).
564 \end{key}
565
566 You can get even more fine-grained control over scaling using the following
567 keys (the |scale| key is just a shorthand for setting both of the following
568 keys simultaneously):
569
570 \begin{key}{/pgf/arrow keys/scale length=\meta{factor} (initially 1)}
571 This factor works like |scale|, only it is applied only to dimensions
572 ``along the axis of the arrow'', that is, to the length and to the inset,
573 but not to the width.
574 %
575 \begin{codeexample}[preamble={\usetikzlibrary{arrows.meta}}]
576 \tikz {
577 \draw [arrows = {-Stealth[]}] (0,1) -- (1,1);
578 \draw [arrows = {-Stealth[scale length=1.5]}] (0,0.5) -- (1,0.5);
579 \draw [arrows = {-Stealth[scale length=2]}] (0,0) -- (1,0);
580 }
581 \end{codeexample}
582 %
583 \end{key}
584
585 \begin{key}{/pgf/arrow keys/scale width=\meta{factor} (initially 1)}
586 Like |scale length|, but for dimensions related to the width.
587 %
588 \begin{codeexample}[preamble={\usetikzlibrary{arrows.meta}}]
589 \tikz {
590 \draw [arrows = {-Stealth[]}] (0,1) -- (1,1);
591 \draw [arrows = {-Stealth[scale width=1.5]}] (0,0.5) -- (1,0.5);
592 \draw [arrows = {-Stealth[scale width=2]}] (0,0) -- (1,0);
593 }
594 \end{codeexample}
595 %
596 \end{key}
597
598
599 \subsubsection{Arc Angles}
600
601 A few arrow tips consist mainly of arcs, whose length can be specified. For
602 these arrow tips, you use the following key:
603
604 \begin{key}{/pgf/arrow keys/arc=\meta{degrees} (initially 180)}
605 Sets the angle of arcs in arrows to \meta{degrees}. Note that this key is
606 quite different from the |angle| key, which is ``just a fancy way of
607 setting the length and width''. In contrast, the |arc| key is used to set
608 the degrees of arcs that are part of an arrow tip:
609 %
610 \begin{codeexample}[preamble={\usetikzlibrary{arrows.meta}}]
611 \tikz [ultra thick] {
612 \draw [arrows = {-Hooks[]}] (0,1) -- (1,1);
613 \draw [arrows = {-Hooks[arc=90]}] (0,0.5) -- (1,0.5);
614 \draw [arrows = {-Hooks[arc=270]}] (0,0) -- (1,0);
615 }
616 \end{codeexample}
617 %
618 \end{key}
619
620
621 \subsubsection{Slanting}
622
623 You can ``slant'' arrow tips using the following key:
624
625 \begin{key}{/pgf/arrow keys/slant=\meta{factor} (initially 0)}
626 Slanting is used to create an ``italics'' effect for arrow tips: All arrow
627 tips get ``slanted'' a little bit relative to the axis of the arrow:
628 %
629 \begin{codeexample}[preamble={\usetikzlibrary{arrows.meta}}]
630 \tikz {
631 \draw [arrows = {->[]}] (0,1) -- (1,1);
632 \draw [arrows = {->[slant=.5]}] (0,0.5) -- (1,0.5);
633 \draw [arrows = {->[slant=1]}] (0,0) -- (1,0);
634 }
635 \end{codeexample}
636 %
637 There is one thing to note about slanting: Slanting is done using a
638 so-called ``canvas transformation'' and has no effect on positioning of
639 the arrow tip. In particular, if an arrow tip gets slanted so strongly that
640 it starts to protrude over the arrow tip end, this does not change the
641 positioning of the arrow tip.
642
643 Here is another example where slanting is used to match italic text:
644 %
645 \begin{codeexample}[preamble={\usetikzlibrary{arrows.meta,graphs}}]
646 \tikz [>={[slant=.3] To[] To[]}]
647 \graph [math nodes] { A -> B <-> C };
648 \end{codeexample}
649 %
650 \end{key}
651
652
653 \subsubsection{Reversing, Halving, Swapping}
654 \label{section-arrow-key-harpoon}
655
656 \begin{key}{/pgf/arrow keys/reversed}
657 Adding this key to an arrow tip will ``reverse its direction'' so that is
658 points in the opposite direction (but is still at that end of the line
659 where the non-reversed arrow tip would have been drawn; so only the tip is
660 reversed). For most arrow tips, this just results in an internal flip of a
661 coordinate system, but some arrow tips actually use a slightly different
662 version of the tip for reversed arrow tips (namely when the joining of the
663 tip with the line would look strange). All of this happens automatically,
664 so you do not need to worry about this.
665
666 If you apply this key twice, the effect cancels, which is useful for the
667 definition of shorthands (which will be discussed later).
668 %
669 \begin{codeexample}[width=3cm,preamble={\usetikzlibrary{arrows.meta}}]
670 \tikz [ultra thick] \draw [arrows = {-Stealth[reversed]}] (0,0) -- (1,0);
671 \end{codeexample}
672 \begin{codeexample}[width=3cm,preamble={\usetikzlibrary{arrows.meta}}]
673 \tikz [ultra thick] \draw [arrows = {-Stealth[reversed, reversed]}] (0,0) -- (1,0);
674 \end{codeexample}
675 \end{key}
676
677 \begin{key}{/pgf/arrow keys/harpoon}
678 The key requests that only the ``left half'' of the arrow tip should drawn:
679 %
680 \begin{codeexample}[width=3cm,preamble={\usetikzlibrary{arrows.meta}}]
681 \tikz [ultra thick] \draw [arrows = {-Stealth[harpoon]}] (0,0) -- (1,0);
682 \end{codeexample}
683 \begin{codeexample}[width=3cm,preamble={\usetikzlibrary{arrows.meta}}]
684 \tikz [ultra thick] \draw [arrows = {->[harpoon]}] (0,0) -- (1,0);
685 \end{codeexample}
686 %
687 Unlike the |reversed| key, which all arrows tip kinds support at least in a
688 basic way, designers of arrow tips really need to take this key into
689 account in their arrow tip code and often a lot of special attention needs
690 to do be paid to this key in the implementation. For this reason, only some
691 arrow tips will support it.
692 \end{key}
693
694 \begin{key}{/pgf/arrow keys/swap}
695 This key flips that arrow tip along the axis of the line. It makes sense
696 only for asymmetric arrow tips like the harpoons created using the
697 |harpoon| option.
698 %
699 \begin{codeexample}[width=3cm,preamble={\usetikzlibrary{arrows.meta}}]
700 \tikz [ultra thick] \draw [arrows = {-Stealth[harpoon]}] (0,0) -- (1,0);
701 \end{codeexample}
702 \begin{codeexample}[width=3cm,preamble={\usetikzlibrary{arrows.meta}}]
703 \tikz [ultra thick] \draw [arrows = {-Stealth[harpoon,swap]}] (0,0) -- (1,0);
704 \end{codeexample}
705 %
706 Swapping is always possible, no special code is needed on behalf of an
707 arrow tip implementer.
708 \end{key}
709
710 \begin{key}{/pgf/arrow keys/left}
711 A shorthand for |harpoon|.
712 \end{key}
713
714 \begin{key}{/pgf/arrow keys/right}
715 A shorthand for |harpoon, swap|.
716 %
717 \begin{codeexample}[width=3cm,preamble={\usetikzlibrary{arrows.meta}}]
718 \tikz [ultra thick] \draw [arrows = {-Stealth[left]}] (0,0) -- (1,0);
719 \end{codeexample}
720 \begin{codeexample}[width=3cm,preamble={\usetikzlibrary{arrows.meta}}]
721 \tikz [ultra thick] \draw [arrows = {-Stealth[right]}] (0,0) -- (1,0);
722 \end{codeexample}
723 %
724 \end{key}
725
726
727 \subsubsection{Coloring}
728
729 Arrow tips are drawn using the same basic mechanisms as normal paths, so arrow
730 tips can be stroked (drawn) and/or filled. However, we usually want the color
731 of arrow tips to be identical to the color used to draw the path, even if a
732 different color is used for filling the path. On the other hand, we may also
733 sometimes wish to use a special color for the arrow tips that is different from
734 both the line and fill colors of the main path.
735
736 The following options allow you to configure how arrow tips are colored:
737
738 \begin{key}{/pgf/arrow keys/color=\meta{color or empty} (initially \normalfont empty)}
739 Normally, an arrow tip gets the same color as the path to which it is
740 attached. More precisely, it will get the current ``draw color'', also
741 known as ``stroke color'', which you can set using |draw=|\meta{some
742 color}. By adding the option |color=| to an arrow tip (note that an
743 ``empty'' color is specified in this way), you ask that the arrow tip gets
744 this default draw color of the path. Since this is the default behavior,
745 you usually do not need to specify anything:
746 %
747 \begin{codeexample}[width=3cm,preamble={\usetikzlibrary{arrows.meta}}]
748 \tikz [ultra thick] \draw [red, arrows = {-Stealth}] (0,0) -- (1,0);
749 \end{codeexample}
750 \begin{codeexample}[width=3cm,preamble={\usetikzlibrary{arrows.meta}}]
751 \tikz [ultra thick] \draw [blue, arrows = {-Stealth}] (0,0) -- (1,0);
752 \end{codeexample}
753
754 Now, when you provide a \meta{color} with this option, you request that the
755 arrow tip should get this color \emph{instead} of the color of the main
756 path:
757 %
758 \begin{codeexample}[width=3cm,preamble={\usetikzlibrary{arrows.meta}}]
759 \tikz [ultra thick] \draw [red, arrows = {-Stealth[color=blue]}] (0,0) -- (1,0);
760 \end{codeexample}
761 \begin{codeexample}[width=3cm,preamble={\usetikzlibrary{arrows.meta}}]
762 \tikz [ultra thick] \draw [red, arrows = {-Stealth[color=black]}] (0,0) -- (1,0);
763 \end{codeexample}
764
765 Similar to the |color| option used in normal \tikzname\ options, you may
766 omit the |color=| part of the option. Whenever an \meta{arrow key} is
767 encountered that \tikzname\ does not recognize, it will test whether the
768 key is the name of a color and, if so, execute |color=|\meta{arrow key}.
769 So, the first of the above examples can be rewritten as follows:
770 %
771 \begin{codeexample}[width=3cm,preamble={\usetikzlibrary{arrows.meta}}]
772 \tikz [ultra thick] \draw [red, arrows = {-Stealth[blue]}] (0,0) -- (1,0);
773 \end{codeexample}
774
775 The \meta{color} will apply both to any drawing and filling operations used
776 to construct the path. For instance, even though the |Stealth| arrow tips
777 looks like a filled quadrilateral, it is actually constructed by drawing a
778 quadrilateral and then filling it in the same color as the drawing (see the
779 |fill| option below to see the difference).
780
781 When |color| is set to an empty text, the drawing color is always used to
782 fill the arrow tips, even if a different color is specified for filling the
783 path:
784 %
785 \begin{codeexample}[width=3cm,preamble={\usetikzlibrary{arrows.meta}}]
786 \tikz [ultra thick] \draw [draw=red, fill=red!50, arrows = {-Stealth[length=10pt]}]
787 (0,0) -- (1,1) -- (2,0);
788 \end{codeexample}
789 %
790 As you can see in the above example, the filled area is not quite what you
791 might have expected. The reason is that the path was actually internally
792 shortened a bit so that the end of the ``fat line'' as inside the arrow tip
793 and we get a ``clear'' arrow tip.
794
795 In general, it is a good idea not to add arrow tips to paths that are
796 filled.
797 \end{key}
798
799 \begin{key}{/pgf/arrow keys/fill=\meta{color} (default \normalfont is scope's color setting)}
800 Use this key to explicitly set the color used for filling the arrow tips.
801 This color can be different from the color used to draw (stroke) the arrow
802 tip:
803 %
804 \begin{codeexample}[width=3cm,preamble={\usetikzlibrary{arrows.meta}}]
805 \tikz {
806 \draw [help lines] (0,-.5) grid [step=1mm] (1,.5);
807 \draw [thick, red, arrows = {-Stealth[fill=white,length=15pt]}] (0,0) -- (1,0);
808 }
809 \end{codeexample}
810 %
811 You can also specify the special ``color'' |none|. In this case, the arrow
812 tip is not filled at all (not even with white):
813 %
814 \begin{codeexample}[width=3cm,preamble={\usetikzlibrary{arrows.meta}}]
815 \tikz {
816 \draw [help lines] (0,-.5) grid [step=1mm] (1,.5);
817 \draw [thick, red, arrows = {-Stealth[fill=none,length=15pt]}] (0,0) -- (1,0);
818 }
819 \end{codeexample}
820 %
821 If the argument is left empty or omitted altogether, no explicit fill color
822 will be set, meaning that the fill color will be determined by whatever was used
823 last as a fill color in the current scope.
824
825 Note that such ``open'' arrow tips are a bit difficult to draw in some
826 case: The problem is that the line must be shortened by just the right
827 amount so that it ends exactly on the back end of the arrow tip. In some
828 cases, especially when double lines are used, this will not be possible.
829
830 \begin{key}{/pgf/arrow keys/open}
831 A shorthand for |fill=none|.
832 \end{key}
833
834 When you use both the |color| and |fill| options, the |color| option must
835 come first since it will reset the filling to the color specified for
836 drawing.
837 %
838 \begin{codeexample}[width=3cm,preamble={\usetikzlibrary{arrows.meta}}]
839 \tikz {
840 \draw [help lines] (0,-.5) grid [step=1mm] (1,.5);
841 \draw [thick, red, arrows = {-Stealth[color=blue, fill=white, length=15pt]}]
842 (0,0) -- (1,0);
843 }
844 \end{codeexample}
845
846 Note that by setting |fill| to the special color |pgffillcolor|, you can
847 cause the arrow tips to be filled using the color used to fill the main
848 path. (This special color is always available and always set to the current
849 filling color of the graphic state.):
850 %
851 \begin{codeexample}[width=3cm,preamble={\usetikzlibrary{arrows.meta}}]
852 \tikz [ultra thick] \draw [draw=red, fill=red!50,
853 arrows = {-Stealth[length=15pt, fill=pgffillcolor]}]
854 (0,0) -- (1,1) -- (2,0);
855 \end{codeexample}
856 %
857 \end{key}
858
859
860 \subsubsection{Line Styling}
861 \label{section-arrow-key-caps}
862
863 Arrow tips are created by drawing and possibly filling a path that makes up the
864 arrow tip. When \tikzname\ draws a path, there are different ways in which such
865 a path can be drawn (such as dashing). Three particularly important parameters
866 are the line join, the line cap, see Section~\ref{section-line-cap} for an
867 introduction, and the line width (thickness).
868
869 \tikzname\ resets the line cap and line join each time it draws an arrow tip
870 since you usually do not want their settings to ``spill over'' to the way the
871 arrow tips are drawn. You can, however, change there values explicitly for an
872 arrow tip:
873
874 \begin{key}{/pgf/arrow keys/line cap=\meta{|round| or |butt|}}
875 Sets the line cap of all lines that are drawn in the arrow to a round cap
876 or a butt cap. (Unlike for normal lines, the |rect| cap is not allowed.)
877 Naturally, this key has no effect for arrows whose paths are closed.
878
879 Each arrow tip has a default value for the line cap, which can be overruled
880 using this option.
881
882 Changing the cap should have no effect on the size of the arrow. However,
883 it will have an effect on where the exact ``tip'' of the arrow is since
884 this will always be exactly at the end of the arrow:
885 %
886 \begin{codeexample}[width=3cm,preamble={\usetikzlibrary{arrows.meta}}]
887 \tikz [line width=2mm]
888 \draw [arrows = {-Computer Modern Rightarrow[line cap=butt]}]
889 (0,0) -- (1,0);
890 \end{codeexample}
891 \begin{codeexample}[width=3cm,preamble={\usetikzlibrary{arrows.meta}}]
892 \tikz [line width=2mm]
893 \draw [arrows = {-Computer Modern Rightarrow[line cap=round]}]
894 (0,0) -- (1,0);
895 \end{codeexample}
896 \begin{codeexample}[width=3cm,preamble={\usetikzlibrary{arrows.meta}}]
897 \tikz [line width=2mm]
898 \draw [arrows = {-Bracket[reversed,line cap=butt]}]
899 (0,0) -- (1,0);
900 \end{codeexample}
901 \begin{codeexample}[width=3cm,preamble={\usetikzlibrary{arrows.meta}}]
902 \tikz [line width=2mm]
903 \draw [arrows = {-Bracket[reversed,line cap=round]}]
904 (0,0) -- (1,0);
905 \end{codeexample}
906 %
907 \end{key}
908
909 \begin{key}{/pgf/arrow keys/line join=\meta{|round| or |miter|}}
910 Sets the line join to round or miter (|bevel| is not allowed). This time,
911 the key only has an effect on paths that have ``corners'' in them. The same
912 rules as for |line cap| apply: the size is not affects, but the tip end is:
913 %
914 \begin{codeexample}[width=3cm,preamble={\usetikzlibrary{arrows.meta}}]
915 \tikz [line width=2mm]
916 \draw [arrows = {-Computer Modern Rightarrow[line join=miter]}]
917 (0,0) -- (1,0);
918 \end{codeexample}
919 \begin{codeexample}[width=3cm,preamble={\usetikzlibrary{arrows.meta}}]
920 \tikz [line width=2mm]
921 \draw [arrows = {-Computer Modern Rightarrow[line join=round]}]
922 (0,0) -- (1,0);
923 \end{codeexample}
924 \begin{codeexample}[width=3cm,preamble={\usetikzlibrary{arrows.meta}}]
925 \tikz [line width=2mm]
926 \draw [arrows = {-Bracket[reversed,line join=miter]}]
927 (0,0) -- (1,0);
928 \end{codeexample}
929 \begin{codeexample}[width=3cm,preamble={\usetikzlibrary{arrows.meta}}]
930 \tikz [line width=2mm]
931 \draw [arrows = {-Bracket[reversed,line join=round]}]
932 (0,0) -- (1,0);
933 \end{codeexample}
934 %
935 \end{key}
936
937 The following keys set both of the above:
938
939 \begin{key}{/pgf/arrow keys/round}
940 A shorthand for |line cap=round, line join=round|, resulting in ``rounded''
941 arrow heads.
942 %
943 \begin{codeexample}[width=3cm,preamble={\usetikzlibrary{arrows.meta}}]
944 \tikz [line width=2mm]
945 \draw [arrows = {-Computer Modern Rightarrow[round]}] (0,0) -- (1,0);
946 \end{codeexample}
947 \begin{codeexample}[width=3cm,preamble={\usetikzlibrary{arrows.meta}}]
948 \tikz [line width=2mm]
949 \draw [arrows = {-Bracket[reversed,round]}] (0,0) -- (1,0);
950 \end{codeexample}
951 %
952 \end{key}
953
954 \begin{key}{/pgf/arrow keys/sharp}
955 A shorthand for |line cap=butt, line join=miter|, resulting in ``sharp'' or
956 ``pointed'' arrow heads.
957 %
958 \begin{codeexample}[width=3cm,preamble={\usetikzlibrary{arrows.meta}}]
959 \tikz [line width=2mm]
960 \draw [arrows = {-Computer Modern Rightarrow[sharp]}] (0,0) -- (1,0);
961 \end{codeexample}
962 \begin{codeexample}[width=3cm,preamble={\usetikzlibrary{arrows.meta}}]
963 \tikz [line width=2mm]
964 \draw [arrows = {-Bracket[reversed,sharp]}] (0,0) -- (1,0);
965 \end{codeexample}
966 %
967 \end{key}
968
969 You can also set the width of lines used inside arrow tips:
970
971 \begin{key}{/pgf/arrow keys/line width=\meta{dimension}| |\opt{\meta{line width factor}}%
972 | |\opt{\meta{outer factor}}}
973 This key sets the line width inside an arrow tip for drawing (out)lines of
974 the arrow tip. When you set this width to |0pt|, which makes sense only for
975 closed tips, the arrow tip is only filled. This can result in better
976 rendering of some small arrow tips and in case of bend arrow tips (because
977 the line joins will also be bend and not ``mitered''.)
978
979 The meaning of the factors is as usual the same as for |length| or |width|.
980 %
981 \begin{codeexample}[width=2cm,preamble={\usetikzlibrary{arrows.meta}}]
982 \tikz \draw [arrows = {-Latex[line width=0.1pt, fill=white, length=10pt]}] (0,0) -- (1,0);
983 \end{codeexample}
984 \begin{codeexample}[width=2cm,preamble={\usetikzlibrary{arrows.meta}}]
985 \tikz \draw [arrows = {-Latex[line width=1pt, fill=white, length=10pt]}] (0,0) -- (1,0);
986 \end{codeexample}
987 %
988 \end{key}
989
990 \begin{key}{/pgf/arrow keys/line width'=\meta{dimension}| |\opt{\meta{length factor}}}
991 Works like |line width| only the factor is with respect to the |length|.
992 \end{key}
993
994
995 \subsubsection{Bending and Flexing}
996 \label{section-arrow-flex}
997
998 Up to now, we have only added arrow tip to the end of straight lines, which is
999 in some sense ``easy''. Things get far more difficult, if the line to which we
1000 wish to end an arrow tip is curved. In the following, we have a look at the
1001 different actions that can be taken and how they can be configured.
1002
1003 To get a feeling for the difficulties involved, consider the following
1004 situation: We have a ``gray wall'' at the $x$-coordinate of and a red line that
1005 ends in its middle.
1006 %
1007 \begin{codeexample}[preamble={\usetikzlibrary{patterns}}]
1008 \def\wall{ \fill [fill=black!50] (1,-.5) rectangle (2,.5);
1009 \pattern [pattern=bricks] (1,-.5) rectangle (2,.5);
1010 \draw [line width=1pt] (1cm+.5pt,-.5) -- ++(0,1); }
1011 \begin{tikzpicture}
1012 \wall
1013 % The "line"
1014 \draw [red,line width=1mm] (-1,0) -- (1,0);
1015 \end{tikzpicture}
1016 \end{codeexample}
1017
1018 Now we wish to add a blue open arrow tip the red line like, say,
1019 |Stealth[length=1cm,open,blue]|:
1020 %
1021 \begin{codeexample}[setup code,hidden]
1022 \usetikzlibrary{patterns}
1023 \def\wall{ \fill [fill=black!50] (1,-.5) rectangle (2,.5);
1024 \pattern [pattern=bricks] (1,-.5) rectangle (2,.5);
1025 \draw [line width=1pt] (1cm+.5pt,-.5) -- ++(0,1); }
1026 \end{codeexample}
1027 \begin{codeexample}[preamble={\usetikzlibrary{arrows.meta}}]
1028 \begin{tikzpicture}
1029 \wall
1030 \draw [red,line width=1mm,-{Stealth[length=1cm,open,blue]}]
1031 (-1,0) -- (1,0);
1032 \end{tikzpicture}
1033 \end{codeexample}
1034
1035 There are several noteworthy things about the blue arrow tip:
1036 %
1037 \begin{enumerate}
1038 \item Notice that the red line no longer goes all the way to the wall.
1039 Indeed, the red line ends more or less exactly where it meets the
1040 blue line, leaving the arrow tip empty. Now, recall that the red line
1041 was supposed to be the path |(-2,0)--(1,0)|; however, this path has
1042 obviously become much shorter (by 6.25mm to be precise). This effect
1043 is called \emph{path shortening} in \tikzname.
1044 \item The very tip of the arrow just ``touches'' the wall, even we zoom
1045 out a lot. This point, where the original path ended and where the
1046 arrow tip should now lie, is called the \emph{tip end} in \tikzname.
1047 \item Finally, the point where the red line touches the blue line is the
1048 point where the original path ``visually ends''. Notice that this is
1049 not the same as the point that lies at a distance of the arrow's
1050 |length| from the wall -- rather it lies at a distance of |length|
1051 minus the |inset|. Let us call this point the \emph{visual
1052 end} of the arrow.
1053 \end{enumerate}
1054
1055 As pointed out earlier, for straight lines, shortening the path and rotating
1056 and shifting the arrow tip so that it ends precisely at the tip end and the
1057 visual end lies on a line from the tip end to the start of the line is
1058 relatively easy.
1059
1060 For curved lines, things are much more difficult and \tikzname\ copes with the
1061 difficulties in different ways, depending on which options you add to arrows.
1062 Here is now a curved red line to which we wish to add our arrow tip (the
1063 original straight red line is shown in light red):
1064 %
1065 \begin{codeexample}[]
1066 \begin{tikzpicture}
1067 \wall
1068 \draw [red!25,line width=1mm] (-1,0) -- (1,0);
1069 \draw [red,line width=1mm] (-1,-.5) .. controls (0,-.5) and (0,0) .. (1,0);
1070 \end{tikzpicture}
1071 \end{codeexample}
1072
1073 The first way of dealing with curved lines is dubbed the ``quick and dirty''
1074 way (although the option for selecting this option is politely just called
1075 ``|quick|'' \dots):
1076
1077 \begin{key}{/pgf/arrow keys/quick}
1078 Recall that curves in \tikzname\ are actually Bézier curves, which means
1079 that they start and end at certain points and we specify two vectors, one
1080 for the start and one for the end, that provide tangents to the curve at
1081 these points. In particular, for the end of the curve, there is a point
1082 called the \emph{second support point} of the curve such that a tangent to
1083 the curve at the end goes through this point. In our above example, the
1084 second support point is at the middle of the light red line and, indeed, a
1085 tangent to the red line at the point touching the wall is perfectly
1086 horizontal.
1087
1088 In order to add our arrow tip to the curved path, our first objective is to
1089 ``shorten'' the path by 6.25mm. Unfortunately, this is now much more
1090 difficult than for a straight path. When the |quick| option is added to an
1091 arrow tip (it is also the default if no special libraries are loaded), we
1092 cheat somewhat: Instead of really moving along 6.25mm along the path, we
1093 simply shift the end of the curve by 6.25mm \emph{along the tangent} (which
1094 is easy to compute). We also have to shift the second support point by the
1095 same amount to ensure that the line still has the same tangent at the end.
1096 This will result in the following:
1097 %
1098 \begin{codeexample}[preamble={\usetikzlibrary{arrows.meta}}]
1099 \begin{tikzpicture}
1100 \wall
1101 \draw [red!25,line width=1mm] (-1,0) -- (1,0);
1102 \draw [red,line width=1mm,-{Stealth[length=1cm,open,blue,quick]}]
1103 (-1,-.5) .. controls (0,-.5) and (0,0) .. (1,0);
1104 \end{tikzpicture}
1105 \end{codeexample}
1106
1107 They main problem with the above picture is that the red line is no longer
1108 equal to the original red line (notice much sharper curvature near its
1109 end). In our example this is not such a bad thing, but it certainly ``not a
1110 nice thing'' that adding arrow tips to a curve changes the overall shape of
1111 the curves. This is especially bothersome if there are several similar
1112 curves that have different arrow heads. In this case, the similar curves
1113 now suddenly look different.
1114
1115 Another big problem with the above approach is that it works only well if
1116 there is only a single arrow tip. When there are multiple ones, simply
1117 shifting them along the tangent as the |quick| option does produces
1118 less-than-satisfactory results:
1119 %
1120 \begin{codeexample}[]
1121 \begin{tikzpicture}
1122 \wall
1123 \draw [red!25,line width=1mm] (-1,0) -- (1,0);
1124 \draw [red,line width=1mm,-{[quick,sep]>>>}]
1125 (-1,-.5) .. controls (0,-.5) and (0,0) .. (1,0);
1126 \end{tikzpicture}
1127 \end{codeexample}
1128 %
1129 Note that the third arrow tip does not really lie on the curve any more.
1130 \end{key}
1131
1132 Because of the shortcomings of the |quick| key, more powerful mechanisms for
1133 shortening lines and rotating arrows tips have been implemented. To use them,
1134 you need to load the following library:
1135
1136 \begin{tikzlibrary}{bending}
1137 Load this library to use the |flex|, |flex'|, or |bending| arrow keys. When
1138 this library is loaded, |flex| becomes the default mode that is used with
1139 all paths, unless |quick| is explicitly selected for the arrow tip.
1140 \end{tikzlibrary}
1141
1142 \begin{key}{/pgf/arrow keys/flex=\opt{\meta{factor}} (default 1)}
1143 When the |bending| library is loaded, this key is applied to all arrow tips
1144 by default. It has the following effect:
1145 %
1146 \begin{enumerate}
1147 \item Instead of simply shifting the visual end of the arrow along
1148 the tangent of the curve's end, we really move it along the curve
1149 by the necessary distance. This operation is more expensive than
1150 the |quick| operation -- but not \emph{that} expensive, only
1151 expensive enough so that it is not selected by default for all
1152 arrow tips. Indeed, some compromises are made in the
1153 implementation where accuracy was traded for speed, so the
1154 distance by which the line end is shifted is not necessarily
1155 \emph{exactly} 6.25mm; only something reasonably close.
1156 \item The supports of the line are updated accordingly so that the
1157 shortened line will still follow \emph{exactly} the original
1158 line. This means that the curve deformation effect caused by the
1159 |quick| command does not happen here.
1160 \item Next, the arrow tip is rotated and shifted as follows: First,
1161 we shift it so that its tip is exactly at the tip end, where the
1162 original line ended. Then, the arrow is rotated so the \emph{the
1163 visual end lies on the line}:
1164 %
1165 \begin{codeexample}[preamble={\usetikzlibrary{arrows.meta,bending}}]
1166 \begin{tikzpicture}
1167 \wall
1168 \draw [red!25,line width=1mm] (-1,0) -- (1,0);
1169 \draw [red,line width=1mm,-{Stealth[length=1cm,open,blue,flex]}]
1170 (-1,-.5) .. controls (0,-.5) and (0,0) .. (1,0);
1171 \end{tikzpicture}
1172 \end{codeexample}
1173 \end{enumerate}
1174
1175 As can be seen in the example, the |flex| option gives a result that is
1176 visually pleasing and does not deform the path.
1177
1178 There is, however, one possible problem with the |flex| option: The arrow
1179 tip no longer points along the tangent of the end of the path. This may or
1180 may not be a problem, put especially for larger arrow tips readers will use
1181 the orientation of the arrow head to gauge the direction of the tangent of
1182 the line. If this tangent is important (for example, if it should be
1183 horizontal), then it may be necessary to enforce that the arrow tip
1184 ``really points in the direction of the tangent''.
1185
1186 To achieve this, the |flex| option takes an optional \meta{factor}
1187 parameter, which defaults to |1|. This factor specifies how much the arrow
1188 tip should be rotated: If set to |0|, the arrow points exactly along a
1189 tangent to curve at its tip. If set to |1|, the arrow point exactly along a
1190 line from the visual end point on the curve to the tip. For values in the
1191 middle, we interpolate the rotation between these two extremes; so
1192 |flex=.5| will rotate the arrow's visual end ``halfway away from the
1193 tangent towards the actual position on the line''.
1194 %
1195 \begin{codeexample}[preamble={\usetikzlibrary{arrows.meta,bending}}]
1196 \begin{tikzpicture}
1197 \wall
1198 \draw [red!25,line width=1mm] (-1,0) -- (1,0);
1199 \draw [red,line width=1mm,-{Stealth[length=1cm,open,blue,flex=0]}]
1200 (-1,-.5) .. controls (0,-.5) and (0,0) .. (1,0);
1201 \end{tikzpicture}
1202 \end{codeexample}
1203 \begin{codeexample}[preamble={\usetikzlibrary{arrows.meta,bending}}]
1204 \begin{tikzpicture}
1205 \wall
1206 \draw [red!25,line width=1mm] (-1,0) -- (1,0);
1207 \draw [red,line width=1mm,-{Stealth[length=1cm,open,blue,flex=.5]}]
1208 (-1,-.5) .. controls (0,-.5) and (0,0) .. (1,0);
1209 \end{tikzpicture}
1210 \end{codeexample}
1211 %
1212 Note how in the above examples the red line is visible inside the open
1213 arrow tip. Open arrow tips do not go well with a flex value other than~|1|.
1214 Here is a more realistic use of the |flex=0| key:
1215 %
1216 \begin{codeexample}[preamble={\usetikzlibrary{arrows.meta,bending}}]
1217 \begin{tikzpicture}
1218 \wall
1219 \draw [red!25,line width=1mm] (-1,0) -- (1,0);
1220 \draw [red,line width=1mm,-{Stealth[length=1cm,flex=0]}]
1221 (-1,-.5) .. controls (0,-.5) and (0,0) .. (1,0);
1222 \end{tikzpicture}
1223 \end{codeexample}
1224 %
1225 If there are several arrow tips on a path, the |flex| option positions them
1226 independently, so that each of them lies optimally on the path:
1227 %
1228 \begin{codeexample}[preamble={\usetikzlibrary{bending}}]
1229 \begin{tikzpicture}
1230 \wall
1231 \draw [red!25,line width=1mm] (-1,0) -- (1,0);
1232 \draw [red,line width=1mm,-{[flex,sep]>>>}]
1233 (-1,-.5) .. controls (0,-.5) and (0,0) .. (1,0);
1234 \end{tikzpicture}
1235 \end{codeexample}
1236 %
1237 \end{key}
1238
1239 \begin{key}{/pgf/arrow keys/flex'=\opt{\meta{factor}} (default 1)}
1240 The |flex'| key is almost identical to the |flex| key. The only difference
1241 is that a factor of |1| corresponds to rotating the arrow tip so that the
1242 instead of the visual end, the ``ultimate back end'' of the arrow tip lies
1243 on the red path. In the example instead of having the arrow tip at a
1244 distance of |6.25mm| from the tip lie on the path, we have the point at a
1245 distance of |1cm| from the tip lie on the path:
1246 %
1247 \begin{codeexample}[preamble={\usetikzlibrary{arrows.meta,bending}}]
1248 \begin{tikzpicture}
1249 \wall
1250 \draw [red!25,line width=1mm] (-1,0) -- (1,0);
1251 \draw [red,line width=1mm,-{Stealth[length=1cm,open,blue,flex']}]
1252 (-1,-.5) .. controls (0,-.5) and (0,0) .. (1,0);
1253 \end{tikzpicture}
1254 \end{codeexample}
1255 %
1256 Otherwise, the factor works as for |flex| and, indeed |flex=0| and
1257 |flex'=0| have the same effect.
1258
1259 The main use of this option is not so much with an arrow tip like |Stealth|
1260 but rather with tips like the standard |>| in the context of a strongly
1261 curved line:
1262 %
1263 \begin{codeexample}[preamble={\usetikzlibrary{arrows.meta,bending}}]
1264 \begin{tikzpicture}
1265 \wall
1266 \draw [red!25,line width=1mm] (-1,0) -- (1,0);
1267 \draw [red,line width=1mm,-{Computer Modern Rightarrow[flex]}]
1268 (0,-.5) .. controls (1,-.5) and (0.5,0) .. (1,0);
1269 \end{tikzpicture}
1270 \end{codeexample}
1271 %
1272 In the example, the |flex| option does not really flex the arrow since for
1273 a tip like the Computer Modern arrow, the visual end is the same as the
1274 arrow tip -- after all, the red line does, indeed, end almost exactly where
1275 it used to end.
1276
1277 Nevertheless, you may feel that the arrow tip looks ``wrong'' in the sense
1278 that it should be rotated. This is exactly what the |flex'| option does
1279 since it allows us to align the ``back end'' of the tip with the red line:
1280 %
1281 \begin{codeexample}[preamble={\usetikzlibrary{arrows.meta,bending}}]
1282 \begin{tikzpicture}
1283 \wall
1284 \draw [red!25,line width=1mm] (-1,0) -- (1,0);
1285 \draw [red,line width=1mm,-{Computer Modern Rightarrow[flex'=.75]}]
1286 (0,-.5) .. controls (1,-.5) and (0.5,0) .. (1,0);
1287 \end{tikzpicture}
1288 \end{codeexample}
1289 %
1290 In the example, I used |flex'=.75| so as not to overpronounce the effect.
1291 Usually, you will have to fiddle with it sometime to get the ``perfectly
1292 aligned arrow tip'', but a value of |.75| is usually a good start.
1293 \end{key}
1294
1295 \begin{key}{/pgf/arrow keys/bend}
1296 \emph{Bending} an arrow tip is a radical solution to the problem of
1297 positioning arrow tips on a curved line: The arrow tip is no longer
1298 ``rigid'' but the drawing itself will now bend along the curve. This has
1299 the advantage that all the problems of flexing with wrong tangents and
1300 overflexing disappear. The downsides are longer computation times (bending
1301 an arrow is \emph{much} more expensive that flexing it, let alone than
1302 quick mode) and also the fact that excessive bending can lead to ugly arrow
1303 tips. On the other hand, for most arrow tips their bend version are
1304 visually quite pleasing and create a sophisticated look:
1305 %
1306 \begin{codeexample}[preamble={\usetikzlibrary{arrows.meta,bending}}]
1307 \begin{tikzpicture}
1308 \wall
1309 \draw [red!25,line width=1mm] (-1,0) -- (1,0);
1310 \draw [red,line width=1mm,-{Stealth[length=20pt,bend]}]
1311 (-1,-.5) .. controls (0,-.5) and (0,0) .. (1,0);
1312 \end{tikzpicture}
1313 \end{codeexample}
1314 \begin{codeexample}[preamble={\usetikzlibrary{bending}}]
1315 \begin{tikzpicture}
1316 \wall
1317 \draw [red!25,line width=1mm] (-1,0) -- (1,0);
1318 \draw [red,line width=1mm,-{[bend,sep]>>>}]
1319 (-1,-.5) .. controls (0,-.5) and (0,0) .. (1,0);
1320 \end{tikzpicture}
1321 \end{codeexample}
1322 \begin{codeexample}[preamble={\usetikzlibrary{arrows.meta,bending}}]
1323 \begin{tikzpicture}
1324 \wall
1325 \draw [red!25,line width=1mm] (-1,0) -- (1,0);
1326 \draw [red,line width=1mm,-{Stealth[bend,round,length=20pt]}]
1327 (0,-.5) .. controls (1,-.5) and (0.25,0) .. (1,0);
1328 \end{tikzpicture}
1329 \end{codeexample}
1330 %
1331 \end{key}
1332 % TODOsp: codeexamples: `bending` library is needed up to here
1333 % TODOsp: codeexamples: `\def\wall` + `patterns` library are needed up to here
1334 % TODOsp: codeexamples: `arrows.meta` library needed up to here
1335
1336
1337 \subsection{Arrow Tip Specifications}
1338 \label{section-arrow-spec}
1339
1340 \subsubsection{Syntax}
1341
1342 When you select the arrow tips for the start and the end of a path, you can
1343 specify a whole sequence of arrow tips, each having its own local options. At
1344 the beginning of this section, it was pointed out that the syntax for selecting
1345 the start and end arrow tips is the following:
1346 %
1347 \begin{quote}
1348 \meta{start specification}|-|\meta{end specification}
1349 \end{quote}
1350
1351 We now have a closer look at what these specifications may look like. The
1352 general syntax of the \meta{start specification} is as follows:
1353 %
1354 \begin{quote}
1355 \opt{|[|\meta{options for all tips}|]|} \meta{first arrow tip spec}
1356 \meta{second arrow tip spec} \meta{third arrow tip spec} \dots
1357 \end{quote}
1358 %
1359 As can be seen, an arrow tip specification may start with some options in
1360 brackets. If this is the case, the \meta{options for all tips} will, indeed, be
1361 applied to all arrow tips that follow. (We will see, in a moment, that there
1362 are even more places where options may be specified and a list of the ordering
1363 in which the options are applied will be given later.)
1364
1365 The main part of a specification is taken up by a sequence of individual arrow
1366 tip specifications. Such a specification can be of three kinds:
1367 %
1368 \begin{enumerate}
1369 \item It can be of the form \meta{arrow tip kind
1370 name}|[|\meta{options}|]|.
1371 \item It can be of the form \meta{shorthand}|[|\meta{options}|]|.
1372 \item It can be of the form \meta{single char
1373 shorthand}\opt{|[|\meta{options}|]|}. Note that only for this form
1374 the brackets are optional.
1375 \end{enumerate}
1376
1377 The easiest kind is the first one: This adds an arrow tip of the kind
1378 \meta{arrow tip kind name} to the sequence of arrow tips with the
1379 \meta{options} applied to it at the start (for the \meta{start specification})
1380 or at the end (for the \meta{end specification}). Note that for the \meta{start
1381 specification} the first arrow tip specified in this way will be at the very
1382 start of the curve, while for the \meta{end specification} the ordering is
1383 reversed: The last arrow tip specified will be at the very end of the curve.
1384 This implies that a specification like
1385 %
1386 \begin{quote}
1387 |Stealth[] Latex[] - Latex[] Stealth[]|
1388 \end{quote}
1389 %
1390 will give perfectly symmetric arrow tips on a line (as one would expect).
1391
1392 It is important that even if there are no \meta{options} for an arrow tip, the
1393 square brackets still need to be written to indicate the end of the arrow tip's
1394 name. Indeed, the opening brackets are used to divide the arrow tip
1395 specification into names.
1396
1397 Instead of a \meta{arrow tip kind name}, you may also provide the name of a
1398 so-called \emph{shorthand}. Shorthands look like normal arrow tip kind names
1399 and, indeed, you will often be using shorthands without noticing that you do.
1400 The idea is that instead of, say, |Computer Modern Rightarrow| you might wish
1401 to just write |Rightarrow| or perhaps just |To| or even just |>|. For this, you
1402 can create a shorthand that tells \tikzname\ that whenever this shorthand is
1403 used, another arrow tip kind is meant. (Actually, shorthands are somewhat more
1404 powerful, we have a detailed look at them in
1405 Section~\ref{section-arrow-tip-macro}.) For shorthands, the same rules apply as
1406 for normal arrow tip kinds: You \emph{need} to provide brackets so that
1407 \tikzname\ can find the end of the name inside a longer specification.
1408
1409 The third kind of arrow tip specifications consist of just a single letter like
1410 |>| or |)| or |*| or even |o| or |x| (but you may not use |[|, |]|, or |-|
1411 since they will confuse the parser). These single letter arrow specifications
1412 will invariably be shorthands that select some ``real'' arrow tip instead. An
1413 important feature of single letter arrow tips is that they do \emph{not} need
1414 to be followed by options (but they may).
1415
1416 Now, since we can use any letter for single letter shorthands, how can
1417 \tikzname\ tell whether by |foo[]| we mean an arrow tip kind |foo| without any
1418 options or whether we mean an arrow tip called |f|, followed by two arrow tips
1419 called |o|? Or perhaps an arrow tip called |f| followed by an arrow tip called
1420 |oo|? To solve this problem, the following rule is used to determine which of
1421 the three possible specifications listed above applies: First, we check whether
1422 everything from the current position up to the next opening bracket (or up to
1423 the end) is the name of an arrow tip or of a shorthand. In our case, |foo|
1424 would first be tested under this rule. Only if |foo| is neither the name of an
1425 arrow tip kind nor of a shorthand does \tikzname\ consider the first letter of
1426 the specification, |f| in our case. If this is not the name of a shorthand, an
1427 error is raised. Otherwise the arrow tip corresponding to |f| is added to the
1428 list of arrow tips and the process restarts with the rest. Thus, we would next
1429 text whether |oo| is the name of an arrow tip or shorthand and, if not, whether
1430 |o| is such a name.
1431
1432 All of the above rules mean that you can rather easily specify arrow tip
1433 sequences if they either mostly consist of single letter names or of longer
1434 names. Here are some examples:
1435 %
1436 \begin{itemize}
1437 \item |->>>| is interpreted as three times the |>| shorthand since |>>>| is
1438 not the name of any arrow tip kind (and neither is |>>|).
1439 \item |->[]>>| has the same effect as the above.
1440 \item |-[]>>>| also has the same effect.
1441 \item |->[]>[]>[]| so does this.
1442 \item |->Stealth| yields an arrow tip |>| followed by a |Stealth| arrow
1443 at the end.
1444 \item |-Stealth>| is illegal since there is no arrow tip |Stealth>| and
1445 since |S| is also not the name of any arrow tip.
1446 \item |-Stealth[] >| is legal and does what was presumably meant in the
1447 previous item.
1448 \item |< Stealth-| is legal and is the counterpart to |-Stealth[] >|.
1449 \item |-Stealth[length=5pt] Stealth[length=6pt]| selects two stealth
1450 arrow tips, but at slightly different sizes for the end of lines.
1451 \end{itemize}
1452
1453 An interesting question concerns how flexing and bending interact with multiple
1454 arrow tips: After all, flexing and quick mode use different ways of shortening
1455 the path so we cannot really mix them. The following rule is used: We check,
1456 independently for the start and the end specifications, whether at least one
1457 arrow tip in them uses one of the options |flex|, |flex'|, or |bend|. If so,
1458 all |quick| settings in the other arrow tips are ignored and treated as if
1459 |flex| had been selected for them, too.
1460
1461
1462 \subsubsection{Specifying Paddings}
1463
1464 When you provide several arrow tips in a row, all of them are added to the
1465 start or end of the line:
1466 %
1467 \begin{codeexample}[]
1468 \tikz \draw [<<<->>>>] (0,0) -- (2,0);
1469 \end{codeexample}
1470 %
1471 The question now is what will be the distance between them? For this, the
1472 following arrow key is important:
1473
1474 \begin{key}{/pgf/arrow keys/sep=\meta{dimension}| |\opt{\meta{line
1475 width factor}}| |\opt{\meta{outer factor}} (default 0.88pt .3 1)%
1476 }
1477 When a sequence of arrow tips is specified in an arrow tip specification
1478 for the end of the line, the arrow tips are normally arranged in such a way
1479 that the tip of each arrow ends exactly at the ``back end'' of the next
1480 arrow tip (for start specifications, the ordering is inverted, of course).
1481 Now, when the |sep| option is set, instead of exactly touching the back end
1482 of the next arrow, the specified \meta{dimension} is added as additional
1483 space (the distance may also be negative, resulting in an overlap of the
1484 arrow tips). The optional factors have the same meaning as for the |length|
1485 key, see that key for details.
1486
1487 Let us now have a look at some examples. First, we use two arrow tips with
1488 different separations between them:
1489 %
1490 \begin{codeexample}[preamble={\usetikzlibrary{arrows.meta}}]
1491 \tikz {
1492 \draw [-{>[sep=1pt]>[sep= 2pt]>}] (0,1.0) -- (1,1.0);
1493 \draw [-{>[sep=1pt]>[sep=-2pt]>}] (0,0.5) -- (1,0.5);
1494 \draw [-{> >[sep] >}] (0,0.0) -- (1,0.0);
1495 }
1496 \end{codeexample}
1497
1498 You can also specify a |sep| for the last arrow tip in the sequence (for
1499 end specifications, otherwise for the first arrow tip). In this case, this
1500 first arrow tip will not exactly ``touch'' the point where the path ends,
1501 but will rather leave the specified amount of space. This is usually quite
1502 desirable.
1503 %
1504 \begin{codeexample}[preamble={\usetikzlibrary{arrows.meta,positioning}}]
1505 \tikz {
1506 \node [draw] (A) {A};
1507 \node [draw] (B) [right=of A] {B};
1508
1509 \draw [-{>>[sep=2pt]}] (A) to [bend left=45] (B);
1510 \draw [- >> ] (A) to [bend right=45] (B);
1511 }
1512 \end{codeexample}
1513 %
1514 Indeed, adding a |sep| to an arrow tip is \emph{very} desirable, so you
1515 will usually write something like |>={To[sep]}| somewhere near the start of
1516 your files.
1517
1518 One arrow tip kind can be quite useful in this context: The arrow tip kind
1519 |_|. It draws nothing and has zero length, \emph{but} it has |sep| set as a
1520 default option. Since it is a single letter shorthand, you can write short
1521 and clean ``code'' in this way:
1522 %
1523 \begin{codeexample}[]
1524 \tikz \draw [->_>] (0,0) -- (1,0);
1525 \end{codeexample}
1526 \begin{codeexample}[]
1527 \tikz \draw [->__>] (0,0) -- (1,0);
1528 \end{codeexample}
1529 %
1530 However, using the |sep| option will be faster than using the |_| arrow tip
1531 and it also allows you to specify the desired length directly.
1532 \end{key}
1533
1534
1535 \subsubsection{Specifying the Line End}
1536
1537 In the previous examples of sequences of arrow tips, the line of the path
1538 always ended at the last of the arrow tips (for end specifications) or at the
1539 first of the arrow tips (for start specifications). Often, this is what you may
1540 want, but not always. Fortunately, it is quite easy to specify the desired end
1541 of the line: The special single char shorthand |.| is reserved to indicate that
1542 last arrow that is still part of the line; in other words, the line will stop
1543 at the last arrow before |.| is encountered (for end specifications) are at the
1544 first arrow following |.| (for start specifications).
1545 %
1546 \begin{codeexample}[]
1547 \tikz [very thick] \draw [<<<->>>] (0,0) -- (2,0);
1548 \end{codeexample}
1549 \begin{codeexample}[]
1550 \tikz [very thick] \draw [<.<<->.>>] (0,0) -- (2,0);
1551 \end{codeexample}
1552 \begin{codeexample}[]
1553 \tikz [very thick] \draw [<<.<-.>>>] (0,0) -- (2,0);
1554 \end{codeexample}
1555 \begin{codeexample}[]
1556 \tikz [very thick] \draw [<<.<->.>>] (0,0) to [bend left] (2,0);
1557 \end{codeexample}
1558
1559 It is permissible that there are several dots in a specification, in this case
1560 the first one ``wins'' (for end specifications, otherwise the last one).
1561
1562 Note that |.| is parsed as any other shorthand. In particular, if you wish to
1563 add a dot after a normal arrow tip kind name, you need to add brackets:
1564 %
1565 \begin{codeexample}[preamble={\usetikzlibrary{arrows.meta}}]
1566 \tikz [very thick] \draw [-{Stealth[] . Stealth[] Stealth[]}] (0,0) -- (2,0);
1567 \end{codeexample}
1568 %
1569 Adding options to |.| is permissible, but they have no effect. In particular,
1570 |sep| has no effect since a dot is not an arrow.
1571
1572
1573 \subsubsection{Defining Shorthands}
1574 \label{section-arrow-tip-macro}
1575
1576 It is often desirable to create ``shorthands'' for the names of arrow tips that
1577 you are going to use very often. Indeed, in most documents you will only need a
1578 single arrow tip kind and it would be useful that you could refer to it just as
1579 |>| in your arrow tip specifications. As another example, you might constantly
1580 wish to switch between a filled and a non-filled circle as arrow tips and would
1581 like to use |*| and |o| are shorthands for these case. Finally, you might just
1582 like to shorten a long name like |Computer Modern Rightarrow| down to just, say
1583 |To| or something similar.
1584
1585 All of these case can be addressed by defining appropriate shorthands. This is
1586 done using the following handler:
1587
1588 \begin{handler}{{.tip}{=\meta{end specification}}}
1589 Defined the \meta{key} as a name that can be used inside arrow tip
1590 specifications. If the \meta{key} has a path before it, this path is
1591 ignored (so there is only one ``namespace'' for arrow tips). Whenever it is
1592 used, it will be replaced by the \meta{end specification}. Note that you
1593 must \emph{always} provide (only) an end specification; when the \meta{key}
1594 is used inside a start specification, the ordering and the meaning of the
1595 keys inside the \meta{end specification} are translated automatically.
1596 \todosp{remaining instance of bug \#473}
1597 %
1598 \begin{codeexample}[preamble={\usetikzlibrary{arrows.meta}}]
1599 \tikz [foo /.tip = {Stealth[sep]. >>}]
1600 \draw [-foo] (0,0) -- (2,0);
1601 \end{codeexample}
1602 \begin{codeexample}[preamble={\usetikzlibrary{arrows.meta}}]
1603 \tikz [foo /.tip = {Stealth[sep] Latex[sep]},
1604 bar /.tip = {Stealth[length=10pt,open]}]
1605 \draw [-{foo[red] . bar}] (0,0) -- (2,0);
1606 \end{codeexample}
1607
1608 In the last of the examples, we used |foo[red]| to make the arrows red. Any
1609 options given to a shorthand upon use will be passed on to the actual
1610 arrows tip for which the shorthand stands. Thus, we could also have written
1611 |Stealth[sep,red]| |Latex[sep,red]| instead of |foo[red]|. In other words,
1612 the ``replacement'' of a shorthand by its ``meaning'' is a semantic
1613 replacement rather than a syntactic replacement. In particular, the
1614 \meta{end specification} will be parsed immediately when the shorthand is
1615 being defined. However, this applies only to the options inside the
1616 specification, whose values are evaluated immediately. In contrast, which
1617 actual arrow tip kind is meant by a given shorthand used inside the
1618 \meta{end specification} is resolved only up each use of the shorthand.
1619 This means that when you write
1620 %
1621 \begin{quote}
1622 |dup /.tip = >>|
1623 \end{quote}
1624 %
1625 and then later write
1626 %
1627 \begin{quote}
1628 |> /.tip = whatever|
1629 \end{quote}
1630 %
1631 then |dup| will have the effect as if you had written
1632 |whatever[]whatever[]|. You will find that this behavior is what one would
1633 expect.
1634
1635 There is one problem we have not yet addressed: The asymmetry of single
1636 letter arrow tips like |>| or |)|. When someone writes
1637 %
1638 \begin{codeexample}[]
1639 \tikz \draw [<->] (0,0) -- (1,0);
1640 \end{codeexample}
1641 %
1642 we rightfully expect one arrow tip pointing left at the left end and an
1643 arrow tip pointing right at the right end. However, compare
1644 %
1645 \begin{codeexample}[]
1646 \tikz \draw [>->] (0,0) -- (1,0);
1647 \end{codeexample}
1648 \begin{codeexample}[preamble={\usetikzlibrary{arrows.meta}}]
1649 \tikz \draw [Stealth-Stealth] (0,0) -- (1,0);
1650 \end{codeexample}
1651 %
1652 In both cases, we have \emph{identical} text in the start and end
1653 specifications, but in the first case we rightfully expect the left arrow
1654 to be flipped.
1655
1656 The solution to this problem is that it is possible to define two names for
1657 the same arrow tip, namely one that is used inside start specifications and
1658 one for end specifications. Now, we can decree that the ``name of |>|''
1659 inside start specifications is simply |<| and the above problems disappear.
1660
1661 To specify different names for a shorthand in start and end specifications,
1662 use the following syntax: Instead of \meta{key}, you use \meta{name in
1663 start specifications}|-|\meta{name in end specifications}. Thus, to set the
1664 |>| key correctly, you actually need to write
1665 %
1666 \begin{codeexample}[preamble={\usetikzlibrary{arrows.meta}}]
1667 \tikz [<-> /.tip = Stealth] \draw [<->>] (0,0) -- (1,0);
1668 \end{codeexample}
1669 \begin{codeexample}[preamble={\usetikzlibrary{arrows.meta}}]
1670 \tikz [<-> /.tip = Latex] \draw [>-<] (0,0) -- (1,0);
1671 \end{codeexample}
1672
1673 Note that the above also works even though we have not set |<| as an arrow
1674 tip name for end specifications! The reason this works is that the
1675 \tikzname\ (more precisely, \pgfname) actually uses the following
1676 definition internally:
1677 %
1678 \begin{quote}
1679 |>-< /.tip = >[reversed]|
1680 \end{quote}
1681 %
1682 Translation: ``When |<| is used in an end specification, please replace it
1683 by |>|, but reversed. Also, when |>| is used in a start specification, we
1684 also mean this inverted |>|.''
1685
1686 By default, |>| is a shorthand for |To| and |To| is a shorthand for |to|
1687 (an arrow from the old libraries) when |arrows.meta| is not loaded library.
1688 When |arrows.meta| is loaded, |To| is redefined to mean the same as
1689 |Computer Modern Rightarrow|.
1690 \end{handler}
1691
1692 \begin{key}{/tikz/>=\meta{end arrow specification}}
1693 This is a short way of saying |<->/.tip=|\meta{end arrow specification}.
1694 %
1695 \begin{codeexample}[preamble={\usetikzlibrary{arrows.meta}}]
1696 \begin{tikzpicture}[scale=2,ultra thick]
1697 \begin{scope}[>=Latex]
1698 \draw[>->] (0pt,3ex) -- (1cm,3ex);
1699 \draw[|<->>|] (0pt,2ex) -- (1cm,2ex);
1700 \end{scope}
1701 \begin{scope}[>=Stealth]
1702 \draw[>->] (0pt,1ex) -- (1cm,1ex);
1703 \draw[|<<.<->|] (0pt,0ex) -- (1cm,0ex);
1704 \end{scope}
1705 \end{tikzpicture}
1706 \end{codeexample}
1707 %
1708 \end{key}
1709
1710 \begin{key}{/tikz/shorten <=\meta{length}}
1711 Shorten the path by \meta{length} in the direction of the starting point.
1712 \end{key}
1713
1714 \begin{key}{/tikz/shorten >=\meta{length}}
1715 Shorten the path by \meta{length} in the direction of the end point.
1716 \end{key}
1717
1718
1719 \subsubsection{Scoping of Arrow Keys}
1720 \label{section-arrow-scopes}
1721
1722 There are numerous places where you can specify keys for an arrow tip. There
1723 is, however, one final place that we have not yet mentioned:
1724
1725 \begin{key}{/tikz/arrows=|[|\meta{arrow keys}|]|}
1726 The |arrows| key, which is normally used to set the arrow tips for the
1727 current scope, can also be used to set some arrow keys for the current
1728 scope. When the argument to |arrows| starts with an opening bracket and
1729 only otherwise contains one further closing bracket at the very end, this
1730 semantic of the |arrow| key is assumed.
1731
1732 The \meta{arrow keys} will be set for the rest of current scope. This is
1733 useful for generally setting some design parameters or for generally
1734 switching on, say, bending as in:
1735 %
1736 \begin{codeexample}[code only]
1737 \tikz [arrows={[bend]}] ... % Bend all arrows
1738 \end{codeexample}
1739 %
1740 \end{key}
1741
1742 We can now summarize which arrow keys are applied in what order when an arrow
1743 tip is used:
1744 %
1745 \begin{enumerate}
1746 \item First, the so-called \emph{defaults} are applied, which are values
1747 for the different parameters of a key. They are fixed in the
1748 definition of the key and cannot be changed. Since they are executed
1749 first, they are only the ultimate fallback.
1750 \item The \meta{keys} from the use of |arrows=[|\meta{keys}|]| in all
1751 enclosing scopes.
1752 \item Recursively, the \meta{keys} provided with the arrow tip inside
1753 shorthands.
1754 \item The keys provided at the beginning of an arrow tip specification in
1755 brackets.
1756 \item The keys provided directly next to the arrow tip inside the
1757 specification.
1758 \end{enumerate}
1759
1760
1761 \subsection{Reference: Arrow Tips}
1762 \label{section-arrows-meta}
1763
1764 \begin{pgflibrary}{arrows.meta}
1765 This library defines a large number of standard ``meta'' arrow tips.
1766 ``Meta'' means that you can configure these arrow tips in many different
1767 ways like changing their size or their line caps and joins and many other
1768 details.
1769
1770 The only reason this library is not loaded by default is for compatibility
1771 with older versions of \tikzname. You can, however, safely load and use
1772 this library alongside the older libraries |arrows| and |arrows.spaced|.
1773 \end{pgflibrary}
1774
1775 The different arrow tip kinds defined in the |arrows.meta| library can be
1776 classified in different groups:
1777 %
1778 \begin{itemize}
1779 \item \emph{Barbed} arrow tips consist mainly of lines that ``point
1780 backward'' from the tip of the arrow and which are not filled. For
1781 them, filling has no effect. A typical example is \tikz [baseline]
1782 \draw (0,.5ex) -- (1.5em,.5ex) [-Straight Barb];. Here is the list of
1783 defined arrow tips:
1784 %
1785 \begin{arrowexamples}
1786 \arrowexample Arc Barb[]
1787 \arrowexample Bar[]
1788 \arrowexample Bracket[]
1789 \arrowexample Hooks[]
1790 \arrowexample Parenthesis[]
1791 \arrowexample Straight Barb[]
1792 \arrowexample Tee Barb[]
1793 \end{arrowexamples}
1794
1795 All of these arrow tips can be configured and resized in many different
1796 ways as described in the following. Above, they are shown at their
1797 ``natural'' sizes, which are chosen in such a way that for a line width
1798 of 0.4pt their width matches the height of a letter ``x'' in Computer
1799 Modern at 11pt (with some ``overshooting'' to create visual
1800 consistency).
1801 \item \emph{Mathematical} arrow tips are actually a subclass of the
1802 barbed arrow tips, but we list them separately. They contain arrow
1803 tips that look exactly like the tips of arrows used in mathematical
1804 fonts such as the |\to|-symbol $\to$ from standard \TeX.
1805 %
1806 \begin{arrowexamples}
1807 \arrowexample Classical TikZ Rightarrow[]
1808 \arrowexample Computer Modern Rightarrow[]
1809 \arrowexampledouble Implies[]
1810 \arrowexample To[]
1811 \end{arrowexamples}
1812 %
1813 The |To| arrow tip is a shorthand for |Computer Modern Rightarrow| when
1814 |arrows.meta| is loaded.
1815 \item \emph{Geometric} arrow tips consist of a filled shape like a kite
1816 or a circle or a ``stealth-fighter-like'' shape. A typical example is
1817 \tikz [baseline] \draw (0,.5ex) -- (1.5em,.5ex) [-Stealth];. These
1818 arrow tips can also be used in an ``open'' variant as in \tikz
1819 [baseline] \draw (0,.5ex) -- (1.5em,.5ex) [-{Stealth[open]}];.
1820 %
1821 \begin{arrowexamples}
1822 \arrowexample Circle[]
1823 \arrowexample Diamond[]
1824 \arrowexample Ellipse[]
1825 \arrowexample Kite[]
1826 \arrowexample Latex[]
1827 \arrowexample Latex[round]
1828 \arrowexample Rectangle[]
1829 \arrowexample Square[]
1830 \arrowexample Stealth[]
1831 \arrowexample Stealth[round]
1832 \arrowexample Triangle[]
1833 \arrowexample Turned Square[]
1834 \end{arrowexamples}
1835
1836 Here are the ``open'' variants:
1837 %
1838 \begin{arrowexamples}
1839 \arrowexample Circle[open]
1840 \arrowexample Diamond[open]
1841 \arrowexample Ellipse[open]
1842 \arrowexample Kite[open]
1843 \arrowexample Latex[open]
1844 \arrowexample Latex[round,open]
1845 \arrowexample Rectangle[open]
1846 \arrowexample Square[open]
1847 \arrowexample Stealth[open]
1848 \arrowexample Stealth[round,open]
1849 \arrowexample Triangle[open]
1850 \arrowexample Turned Square[open]
1851 \end{arrowexamples}
1852
1853 Note that ``open'' arrow tips are not the same as ``filled with
1854 white'', which is also available (just say |fill=white|). The
1855 difference is that the background will ``shine through'' an open
1856 arrow, while a filled arrow always obscures the background:
1857 %
1858 \begin{codeexample}[preamble={\usetikzlibrary{arrows.meta}}]
1859 \tikz {
1860 \shade [left color=white, right color=red!50] (0,0) rectangle (4,1);
1861
1862 \draw [ultra thick,-{Triangle[open]}] (0,2/3) -- ++ (3,0);
1863 \draw [ultra thick,-{Triangle[fill=white]}] (0,1/3) -- ++ (3,0);
1864 }
1865 \end{codeexample}
1866
1867 \item \emph{Cap} arrow tips are used to add a ``cap'' to the end of a
1868 line. The graphic languages underlying \tikzname\ (\textsc{pdf},
1869 \textsc{postscript} or \textsc{svg}) all support three basic types of
1870 line caps on a very low level: round, rectangular, and ``butt''.
1871 Using cap arrow tips, you can add new caps to lines and use different
1872 caps for the end and the start. An example is the line \tikz
1873 [baseline] \draw [line width=1ex, {Round Cap[reversed]}-{Triangle
1874 Cap[] . Fast Triangle[] Fast Triangle[]}] (0,0.5ex) -- (2em,0.5ex);.
1875 %
1876 \begin{arrowcapexamples}
1877 \arrowcapexample Butt Cap[]
1878 \arrowcapexample Fast Round[]
1879 \arrowcapexample Fast Triangle[]
1880 \arrowcapexample Round Cap[]
1881 \arrowcapexample Triangle Cap[]
1882 \end{arrowcapexamples}
1883 \item \emph{Special} arrow tips are used for some specific purpose and do
1884 not fit into the above categories.
1885 %
1886 \begin{arrowexamples}
1887 \arrowexample Rays[]
1888 \arrowexample Rays[n=8]
1889 \end{arrowexamples}
1890 \end{itemize}
1891
1892
1893 \subsubsection{Barbed Arrow Tips}
1894
1895 \begin{arrowtip}{Arc Barb}{
1896 This arrow tip attaches an arc to the end of the line whose angle is given
1897 by the |arc| option. The |length| and |width| parameters refer to the size
1898 of the arrow tip for |arc| set to 180 degrees, which is why in the example
1899 for |arc=210| the actual length is larger than the specified |length|. The
1900 line width is taken into account for the computation of the length and
1901 width. Use the |round| option to add round caps to the end of the arcs.
1902 }%
1903 {length=1.5cm,arc=210}%
1904 {length=1.5cm,width=3cm}
1905
1906 \begin{arrowexamples}
1907 \arrowexample[]
1908 \arrowexampledup[sep]
1909 \arrowexampledupdot[sep]
1910 \arrowexample[arc=120]
1911 \arrowexample[arc=270]
1912 \arrowexample[length=2pt]
1913 \arrowexample[length=2pt,width=5pt]
1914 \arrowexample[line width=2pt]
1915 \arrowexample[reversed]
1916 \arrowexample[round]
1917 \arrowexample[slant=.3]
1918 \arrowexample[left]
1919 \arrowexample[right]
1920 \arrowexample[harpoon,reversed]
1921 \arrowexample[red]
1922 \end{arrowexamples}
1923 %
1924 The following options have no effect: |open|, |fill|.
1925
1926 On |double| lines, the arrow tip will not look correct.
1927 \end{arrowtip}
1928
1929 \begin{arrowtipsimple}{Bar}
1930 A simple bar. This is a simple instance of |Tee Barb| for length zero.
1931 \end{arrowtipsimple}
1932
1933 \begin{arrowtip}{Bracket}{
1934 This is an instance of the |Tee Barb| \todosp{no space shown here} arrow tip that results in something
1935 resembling a bracket. Just like the |Parenthesis| arrow tip, a |Bracket| is
1936 not modelled from a text square bracket, but rather its size has been
1937 chosen so that it fits with the other arrow tips.
1938 }%
1939 {}%
1940 {}
1941
1942 \begin{arrowexamples}
1943 \arrowexample[]
1944 \arrowexampledup[sep]
1945 \arrowexampledupdot[sep]
1946 \arrowexample[reversed]
1947 \arrowexample[round]
1948 \arrowexample[slant=.3]
1949 \arrowexample[left]
1950 \arrowexample[right]
1951 \arrowexample[harpoon,reversed]
1952 \arrowexample[red]
1953 \end{arrowexamples}
1954 %
1955 The following options have no effect: |open|, |fill|.
1956
1957 On |double| lines, the arrow tip will not look correct.
1958 \end{arrowtip}
1959
1960 \begin{arrowtip}{Hooks}{
1961 This arrow tip attaches two ``hooks'' to the end of the line. The |length|
1962 and |width| parameters refer to the size of the arrow tip if both arcs are
1963 180 degrees; in the example the arc is 210 degrees and, thus, the arrow is
1964 actually longer that the |length| dictates. The line width is taken into
1965 account for the computation of the length and width. The |arc| option is
1966 used to specify the angle of the arcs. Use the |round| option to add round
1967 caps to the end of the arcs.
1968 }%
1969 {length=1cm,width=3.5cm,arc=210}%
1970 {length=1cm,width=3.5cm}
1971
1972 \begin{arrowexamples}
1973 \arrowexample[]
1974 \arrowexampledup[sep]
1975 \arrowexampledupdot[sep]
1976 \arrowexample[arc=120]
1977 \arrowexample[arc=270]
1978 \arrowexample[length=2pt]
1979 \arrowexample[length=2pt,width=5pt]
1980 \arrowexample[line width=2pt]
1981 \arrowexample[reversed]
1982 \arrowexample[round]
1983 \arrowexample[slant=.3]
1984 \arrowexample[left]
1985 \arrowexample[right]
1986 \arrowexample[harpoon,reversed]
1987 \arrowexample[red]
1988 \end{arrowexamples}
1989 %
1990 The following options have no effect: |open|, |fill|.
1991
1992 On |double| lines, the arrow tip will not look correct.
1993 \end{arrowtip}
1994
1995 \begin{arrowtip}{Parenthesis}{
1996 This arrow tip is an instantiation of the |Arc Barb| \todosp{no space shown here} so that it resembles a
1997 parenthesis. However, the idea is not to recreate a ``real'' parenthesis as
1998 it is used in text, but rather a ``bow'' at a size that harmonizes with the
1999 other arrow tips at their default sizes.
2000 }%
2001 {}%
2002 {}
2003
2004 \begin{arrowexamples}
2005 \arrowexample[]
2006 \arrowexampledup[sep]
2007 \arrowexampledupdot[sep]
2008 \arrowexample[reversed]
2009 \arrowexample[round]
2010 \arrowexample[slant=.3]
2011 \arrowexample[left]
2012 \arrowexample[right]
2013 \arrowexample[harpoon,reversed]
2014 \arrowexample[red]
2015 \end{arrowexamples}
2016 %
2017 The following options have no effect: |open|, |fill|.
2018
2019 On |double| lines, the arrow tip will not look correct.
2020 \end{arrowtip}
2021
2022 \begin{arrowtip}{Straight Barb}{
2023 This is the ``archetypal'' arrow head, consisting of just two straight
2024 lines. The |length| and |width| parameters refer to the horizontal and
2025 vertical distances between the points on the path making up the arrow tip.
2026 As can be seen, the line width of the arrow tip's path is not taken into
2027 account. The |angle| option is particularly useful to set the opening angle
2028 at the tip of the arrow head. The |round| option gives a ``softer'' or
2029 ``rounder'' version of the arrow tip.
2030 }%
2031 {length=2cm,width=3cm}%
2032 {length=2cm/-4mm,width=3cm}
2033
2034 \begin{arrowexamples}
2035 \arrowexample[]
2036 % \arrowexampledouble[]
2037 \arrowexampledup[]
2038 \arrowexampledupdot[]
2039 \arrowexample[length=5pt]
2040 \arrowexample[length=5pt,width=5pt]
2041 \arrowexample[line width=2pt]
2042 \arrowexample[reversed]
2043 \arrowexample[angle=60:2pt 3]
2044 \arrowexample[round]
2045 \arrowexample[slant=.3]
2046 \arrowexample[left]
2047 \arrowexample[right]
2048 \arrowexample[harpoon,reversed]
2049 \arrowexample[red]
2050 \end{arrowexamples}
2051 %
2052 The following options have no effect: |open|, |fill|.
2053
2054 On |double| lines, the arrow tip will not look correct.
2055 \end{arrowtip}
2056
2057 \begin{arrowtip}{Tee Barb}{
2058 This arrow tip attaches a little ``T'' on both sides of the tip. The arrow
2059 |inset| dictates the distance from the back end to the middle of the stem
2060 of the T. When the inset is equal to the length, the arrow tip is drawn as
2061 a single line, not as three lines (this is important for the ``round''
2062 version since, then, the corners get rounded).
2063 }%
2064 {length=1.5cm,width=3cm,inset=1cm}%
2065 {length=1.5cm,width=3cm,inset=1cm}
2066
2067 \begin{arrowexamples}
2068 \arrowexample[]
2069 \arrowexampledup[sep]
2070 \arrowexampledupdot[sep]
2071 \arrowexample[inset=0pt]
2072 \arrowexample[inset'=0pt 1]
2073 \arrowexample[line width=2pt]
2074 \arrowexample[round]
2075 \arrowexample[round,inset'=0pt 1]
2076 \arrowexample[slant=.3]
2077 \arrowexample[left]
2078 \arrowexample[right]
2079 \arrowexample[harpoon,reversed]
2080 \arrowexample[red]
2081 \end{arrowexamples}
2082 %
2083 The following options have no effect: |open|, |fill|.
2084
2085 On |double| lines, the arrow tip will not look correct.
2086 \end{arrowtip}
2087
2088
2089 \subsubsection{Mathematical Barbed Arrow Tips}
2090
2091 \begin{arrowtip}{Classical TikZ Rightarrow}{
2092 This arrow tip is the ``old'' or ``classical'' arrow tip that used to be
2093 the standard in \tikzname\ in earlier versions. It was modelled on an old
2094 version of the tip of \texttt{\string\rightarrow} ($\rightarrow$) of the
2095 Computer Modern fonts. However, this ``old version'' was really old, Donald
2096 Knuth (the designer of both \TeX\ and of the Computer Modern fonts)
2097 replaced the arrow tip of the mathematical fonts in~1992.
2098 }%
2099 {length=1cm,width=2cm}%
2100 {length=1cm,width=2cm}
2101
2102 The main problem with this arrow tip is that it is ``too small'' at its
2103 natural size. I recommend using the new \texttt{Computer Modern Rightarrow}
2104 arrow tip instead, which matches the current $\to$. This new version is
2105 also the default used as |>| and as |To|, now.
2106 %
2107 \begin{arrowexamples}
2108 \arrowexample[]
2109 \arrowexampledup[sep]
2110 \arrowexampledupdot[sep]
2111 \arrowexample[length=3pt]
2112 \arrowexample[sharp]
2113 \arrowexample[slant=.3]
2114 \arrowexample[left]
2115 \arrowexample[right]
2116 \arrowexample[harpoon,reversed]
2117 \arrowexample[red]
2118 \end{arrowexamples}
2119 %
2120 The following options have no effect: |open|, |fill|.
2121
2122 On |double| lines, the arrow tip will not look correct.
2123 \end{arrowtip}
2124
2125 \begin{arrowtip}{Computer Modern Rightarrow}{
2126 For a line width of 0.4pt (the default), this arrow tip looks very much
2127 like \texttt{\string\rightarrow} ($\to$) of the Computer Modern math fonts.
2128 However, it is not a ``perfect'' match: the line caps and joins of the
2129 ``real'' $\to$ are rounded differently from this arrow tip; but it takes a
2130 keen eye to notice the difference. When the |arrows.meta| library is loaded,
2131 this arrow tip becomes the default of |To| and, thus, is used whenever |>|
2132 is used (unless, of course, you redefined |>|).
2133 }%
2134 {length=1cm,width=2cm}%
2135 {length=1cm,width=2cm}
2136
2137 \begin{arrowexamples}
2138 \arrowexample[]
2139 \arrowexampledup[sep]
2140 \arrowexampledupdot[sep]
2141 \arrowexample[length=3pt]
2142 \arrowexample[sharp]
2143 \arrowexample[slant=.3]
2144 \arrowexample[left]
2145 \arrowexample[right]
2146 \arrowexample[harpoon,reversed]
2147 \arrowexample[red]
2148 \end{arrowexamples}
2149 %
2150 The following options have no effect: |open|, |fill|.
2151
2152 On |double| lines, the arrow tip will not look correct.
2153 \end{arrowtip}
2154
2155 \begin{arrowtipsimple}{Implies}
2156 This arrow tip makes only sense in conjunction with the |double| option.
2157 The idea is that you attach it to a double line to get something that looks
2158 like \TeX's \texttt{\string\implies} arrow ($\implies$). A typical use of
2159 this arrow tip is
2160 %
2161 \begin{codeexample}[preamble={\usetikzlibrary{arrows.meta,graphs}}]
2162 \tikz \graph [clockwise=3, math nodes,
2163 edges = {double equal sign distance, -Implies}] {
2164 "\alpha", "\beta", "\gamma";
2165 "\alpha" -> "\beta" -> "\gamma" -> "\alpha"
2166 };
2167 \end{codeexample}
2168 %
2169 \begin{arrowexamples}
2170 \arrowexampledouble[]
2171 \arrowexampledouble[red]
2172 \end{arrowexamples}
2173 \end{arrowtipsimple}
2174
2175 \begin{arrowtipsimple}{To}
2176 This is a shorthand for |Computer Modern Rightarrow| when the |arrows.meta|
2177 library is loaded. Otherwise, it is a shorthand for the classical
2178 \tikzname\ rightarrow.
2179 \end{arrowtipsimple}
2180
2181
2182 \subsubsection{Geometric Arrow Tips}
2183
2184 \begin{arrowtip}{Circle}{
2185 Although this tip is called ``circle'', you can also use it to draw
2186 ellipses if you set the length and width to different values. Neither
2187 |round| nor |reversed| has any effect on this arrow tip.
2188 }%
2189 {length=2cm,width=2cm}%
2190 {length=2cm,width=2cm}
2191
2192 \begin{arrowexamples}
2193 \arrowexample[]
2194 \arrowexampledup[sep]
2195 \arrowexampledupdot[sep]
2196 \arrowexample[open]
2197 \arrowexample[length=3pt]
2198 \arrowexample[slant=.3]
2199 \arrowexample[left]
2200 \arrowexample[right]
2201 \arrowexample[red]
2202 \end{arrowexamples}
2203 \end{arrowtip}
2204
2205 \begin{arrowtipsimple}{Diamond}
2206 This is an instance of |Kite| where the length is larger than the width.
2207 %
2208 \begin{arrowexamples}
2209 \arrowexample[]
2210 \arrowexampledup[]
2211 \arrowexampledupdot[]
2212 \arrowexample[open]
2213 \arrowexample[length=10pt]
2214 \arrowexample[round]
2215 \arrowexample[slant=.3]
2216 \arrowexample[left]
2217 \arrowexample[right]
2218 \arrowexample[red]
2219 \arrowexample[fill=red!50]
2220 \end{arrowexamples}
2221 \end{arrowtipsimple}
2222
2223 \begin{arrowtipsimple}{Ellipse}
2224 This is a shorthand for a ``circle'' that is twice as wide as high.
2225
2226 \begin{arrowexamples}
2227 \arrowexample[]
2228 \arrowexampledup[sep]
2229 \arrowexampledupdot[sep]
2230 \arrowexample[open]
2231 \arrowexample[length=10pt]
2232 \arrowexample[round]
2233 \arrowexample[slant=.3]
2234 \arrowexample[left]
2235 \arrowexample[right]
2236 \arrowexample[red]
2237 \arrowexample[fill=red!50]
2238 \end{arrowexamples}
2239 \end{arrowtipsimple}
2240
2241 \begin{arrowtip}{Kite}{
2242 This arrow tip consists of four lines that form a ``kite''. The |inset|
2243 prescribed how far the width-axis of the kite is removed from the back end.
2244 Note that the inset cannot be negative, use a |Stealth| arrow tip for this.
2245 }%
2246 {length=3cm,width=2cm,inset=1cm}%
2247 {length=3cm,width=2cm,inset=1cm}
2248
2249 \begin{arrowexamples}
2250 \arrowexample[]
2251 \arrowexampledup[sep]
2252 \arrowexampledupdot[sep]
2253 \arrowexample[open]
2254 \arrowexample[length=6pt,width=4pt]
2255 \arrowexample[length=6pt,width=4pt,inset=1.5pt]
2256 \arrowexample[round]
2257 \arrowexample[slant=.3]
2258 \arrowexample[left]
2259 \arrowexample[right]
2260 \arrowexample[red]
2261 \end{arrowexamples}
2262 \end{arrowtip}
2263
2264 \begin{arrowtip}{Latex}{
2265 This arrow tip is the same as the arrow tip used in \LaTeX's standard
2266 pictures (via the \texttt{\string\vec} command), if you set the length to
2267 4pt. The default size for this arrow tip was set slightly larger so that it
2268 fits better with the other geometric arrow tips.
2269 }%
2270 {length=3cm,width=2cm}%
2271 {length=3cm,width=2cm}
2272
2273 \begin{arrowexamples}
2274 \arrowexample[]
2275 \arrowexampledup[sep]
2276 \arrowexampledupdot[sep]
2277 \arrowexample[open]
2278 \arrowexample[length=4pt]
2279 \arrowexample[round]
2280 \arrowexample[slant=.3]
2281 \arrowexample[left]
2282 \arrowexample[right]
2283 \arrowexample[red]
2284 \end{arrowexamples}
2285 \end{arrowtip}
2286
2287 \begin{arrowtipsimple}{LaTeX}
2288 Another spelling for the |Latex| arrow tip.
2289 \end{arrowtipsimple}
2290
2291 \begin{arrowtip}{Rectangle}{
2292 A rectangular arrow tip. By default, it is twice as long as high.
2293 }%
2294 {length=3cm,width=2cm}%
2295 {length=3cm,width=2cm}
2296
2297 \begin{arrowexamples}
2298 \arrowexample[]
2299 \arrowexampledup[sep]
2300 \arrowexampledupdot[sep]
2301 \arrowexample[open]
2302 \arrowexample[length=4pt]
2303 \arrowexample[round]
2304 \arrowexample[slant=.3]
2305 \arrowexample[left]
2306 \arrowexample[right]
2307 \arrowexample[red]
2308 \end{arrowexamples}
2309 \end{arrowtip}
2310
2311 \begin{arrowtipsimple}{Square}
2312 An instance of the |Rectangle| whose width is identical to the length.
2313 %
2314 \begin{arrowexamples}
2315 \arrowexample[]
2316 \arrowexampledup[sep]
2317 \arrowexampledupdot[sep]
2318 \arrowexample[open]
2319 \arrowexample[length=4pt]
2320 \arrowexample[round]
2321 \arrowexample[slant=.3]
2322 \arrowexample[left]
2323 \arrowexample[right]
2324 \arrowexample[red]
2325 \end{arrowexamples}
2326 \end{arrowtipsimple}
2327
2328 \begin{arrowtip}{Stealth}{
2329 This arrow tip is similar to a |Kite|, only the |inset| now counts
2330 ``inwards''. Because of that sharp angles, for this arrow tip is makes
2331 quite a difference, visually, if use the |round| option. Also, using the
2332 |harpoon| option (or |left| or |right|) will \emph{lengthen} the arrow tip
2333 because of the even sharper corner at the tip.
2334 }%
2335 {length=3cm,width=2cm,inset=1cm}%
2336 {length=3cm,width=2cm,inset=1cm}
2337
2338 \begin{arrowexamples}
2339 \arrowexample[]
2340 \arrowexampledup[sep]
2341 \arrowexampledupdot[sep]
2342 \arrowexample[open]
2343 \arrowexample[length=6pt,width=4pt]
2344 \arrowexample[length=6pt,width=4pt,inset=1.5pt]
2345 \arrowexample[round]
2346 \arrowexample[slant=.3]
2347 \arrowexample[left]
2348 \arrowexample[right]
2349 \arrowexample[red]
2350 \end{arrowexamples}
2351 \end{arrowtip}
2352
2353 \begin{arrowtipsimple}{Triangle}
2354 An instance of a |Kite| with zero inset.
2355 %
2356 \begin{arrowexamples}
2357 \arrowexample[]
2358 \arrowexampledup[sep]
2359 \arrowexampledupdot[sep]
2360 \arrowexample[open]
2361 \arrowexample[length=4pt]
2362 \arrowexample[angle=45:1pt 3]
2363 \arrowexample[angle=60:1pt 3]
2364 \arrowexample[angle=90:1pt 3]
2365 \arrowexample[round]
2366 \arrowexample[slant=.3]
2367 \arrowexample[left]
2368 \arrowexample[right]
2369 \arrowexample[red]
2370 \end{arrowexamples}
2371 \end{arrowtipsimple}
2372
2373 \begin{arrowtipsimple}{Turned Square}
2374 An instance of a |Kite| with identical width and height and mid-inset.
2375 %
2376 \begin{arrowexamples}
2377 \arrowexample[]
2378 \arrowexampledup[sep]
2379 \arrowexampledupdot[sep]
2380 \arrowexample[open]
2381 \arrowexample[length=4pt]
2382 \arrowexample[round]
2383 \arrowexample[slant=.3]
2384 \arrowexample[left]
2385 \arrowexample[right]
2386 \arrowexample[red]
2387 \end{arrowexamples}
2388 \end{arrowtipsimple}
2389
2390
2391 \subsubsection{Caps}
2392
2393 Recall that a \emph{cap} is a way of ending a line. The graphic languages
2394 underlying \tikzname\ (\textsc{pdf}, \textsc{postscript} or \textsc{svg}) all
2395 support three basic types of line caps on a very low level: round, rectangular,
2396 and ``butt''. Using cap arrow tips, you can add new caps to lines and use
2397 different caps for the end and the start.
2398
2399 \begin{arrowtipsimple}{Butt Cap}
2400 This arrow tip ends the line ``in the normal way'' with a straight end.
2401 This arrow tip is only need to ``cover up'' the actual line cap, if this
2402 happens to differ from the normal cap. In the following example, the line
2403 cap is ``round'', but, nevertheless, the right end is a ``butt'' cap:
2404 %
2405 \begin{codeexample}[preamble={\usetikzlibrary{arrows.meta}}]
2406 \tikz \draw [line width=1ex, line cap=round, -Butt Cap] (0,0) -- (1,0);
2407 \end{codeexample}
2408 %
2409 \end{arrowtipsimple}
2410
2411 \begin{arrowcap}{Fast Round}{
2412 This arrow tip is not really a cap, you use it in conjunction with
2413 (typically) the |Round Cap|. The idea is that you end your line using the
2414 round cap and then add several \texttt{Fast Round}s. As for |Round Cap|,
2415 the |length| parameter dictates the length is the length of the ``main
2416 part'', the inset sets the length of a line that comes before this tip.
2417 }%
2418 {length=5mm,inset=1cm}%
2419 {length=5mm,inset=-1cm}%
2420 {-15mm}
2421
2422 \begin{codeexample}[preamble={\usetikzlibrary{arrows.meta}}]
2423 \tikz \draw [line width=1ex,
2424 -{Round Cap []. Fast Round[] Fast Round[]}]
2425 (0,0) -- (1,0);
2426 \end{codeexample}
2427 %
2428 Note that in conjunction with the |bend| option, this works even quite well
2429 for curves:
2430 %
2431 \begin{codeexample}[preamble={\usetikzlibrary{arrows.meta,bending}}]
2432 \tikz [f/.tip = Fast Round] % shorthand
2433 \draw [line width=1ex, -{[bend] Round Cap[] . f f f}]
2434 (0,0) to [bend left] (1,0);
2435 \end{codeexample}
2436
2437 \begin{arrowcapexamples}
2438 \arrowcapexample[]
2439 \arrowcapexample[reversed]
2440 \arrowcapexample[cap angle=60]
2441 \arrowcapexample[cap angle=60,inset=5pt]
2442 \arrowcapexample[length=.5ex]
2443 \arrowcapexample[slant=.3]
2444 \end{arrowcapexamples}
2445 \end{arrowcap}
2446
2447 \begin{arrowcap}{Fast Triangle}{
2448 This arrow tip works like |Fast Round|, only for triangular caps.
2449 }%
2450 {length=5mm,inset=1cm}%
2451 {length=5mm,inset=-1cm}%
2452 {-15mm}
2453
2454 \begin{codeexample}[preamble={\usetikzlibrary{arrows.meta}}]
2455 \tikz \draw [line width=1ex,
2456 -{Triangle Cap []. Fast Triangle[] Fast Triangle[]}]
2457 (0,0) -- (1,0);
2458 \end{codeexample}
2459 %
2460 Again, this tip works well for curves:
2461 %
2462 \begin{codeexample}[preamble={\usetikzlibrary{arrows.meta,bending}}]
2463 \tikz [f/.tip = Fast Triangle] % shorthand
2464 \draw [line width=1ex, -{[bend] Triangle Cap[] . f f f}]
2465 (0,0) to [bend left] (1,0);
2466 \end{codeexample}
2467
2468 \begin{arrowcapexamples}
2469 \arrowcapexample[]
2470 \arrowcapexample[reversed]
2471 \arrowcapexample[cap angle=60]
2472 \arrowcapexample[cap angle=60,inset=5pt]
2473 \arrowcapexample[length=.5ex]
2474 \arrowcapexample[slant=.3]
2475 \end{arrowcapexamples}
2476 \end{arrowcap}
2477
2478
2479 \begin{arrowcap}{Round Cap}{
2480 This arrow tip ends the line using a half circle or, if the length has been
2481 modified, a half-ellipse.
2482 }%
2483 {length=5mm}%
2484 {length=5mm}%
2485 {-5mm}
2486
2487 \begin{arrowcapexamples}
2488 \arrowcapexample[]
2489 \arrowcapexample[reversed]
2490 \arrowcapexample[length=.5ex]
2491 \arrowcapexample[slant=.3]
2492 \end{arrowcapexamples}
2493 \end{arrowcap}
2494
2495 \begin{arrowcap}{Triangle Cap}{
2496 This arrow tip ends the line using a triangle whose length is given by the
2497 |length| option.
2498 }%
2499 {length=5mm}%
2500 {length=5mm}%
2501 {-5mm}
2502
2503 You can get any angle you want at the tip by specifying a length that is an
2504 appropriate multiple of the line width. The following options does this
2505 computation for you:
2506 %
2507 \begin{key}{/pgf/arrow keys/cap angle=\meta{angle}}
2508 Sets |length| to an appropriate multiple of the line width so that the
2509 angle of a |Triangle Cap| is exactly \meta{angle} at the tip.
2510 \end{key}
2511
2512 \begin{arrowcapexamples}
2513 \arrowcapexample[]
2514 \arrowcapexample[reversed]
2515 \arrowcapexample[cap angle=60]
2516 \arrowcapexample[cap angle=60,reversed]
2517 \arrowcapexample[length=.5ex]
2518 \arrowcapexample[slant=.3]
2519 \end{arrowcapexamples}
2520 \end{arrowcap}
2521
2522
2523 \subsubsection{Special Arrow Tips}
2524
2525 \begin{arrowtip}{Rays}{
2526 This arrow tip attaches a ``bundle of rays'' to the tip. The number of
2527 evenly spaced rays is given by the |n| arrow key (see below). When the
2528 number is even, the rays will lie to the left and to the right of the
2529 direction of the arrow; when the number is odd, the rays are rotated in
2530 such a way that one of them points perpendicular to the direction of the
2531 arrow (this is to ensure that no ray points in the direction of the line,
2532 which would look strange). The |length| and |width| describe the length and
2533 width of an ellipse into which the rays fit.
2534 }%
2535 {length=3cm,width=3cm,n=6}%
2536 {length=3cm,width=3cm}
2537
2538 \begin{arrowexamples}
2539 \arrowexample[]
2540 \arrowexampledup[sep]
2541 \arrowexampledupdot[sep]
2542 \arrowexample[width'=0pt 2]
2543 \arrowexample[round]
2544 \arrowexample[n=2]
2545 \arrowexample[n=3]
2546 \arrowexample[n=4]
2547 \arrowexample[n=5]
2548 \arrowexample[n=6]
2549 \arrowexample[n=7]
2550 \arrowexample[n=8]
2551 \arrowexample[n=9]
2552 \arrowexample[slant=.3]
2553 \arrowexample[left]
2554 \arrowexample[right]
2555 \arrowexample[left,n=5]
2556 \arrowexample[right,n=5]
2557 \arrowexample[red]
2558 \end{arrowexamples}
2559 \end{arrowtip}
2560
2561 \begin{key}{/pgf/arrow keys/n=\meta{number} (initially 4)}
2562 Sets the number of rays in a |Rays| arrow tip.
2563 \end{key}