Debian Codegraph @

texmf-dist/doc/generic/pgf/pgfmanual-en-base-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
11 \section{Defining New Arrow Tip Kinds}
12 \label{section-arrows}
13
14 \subsection{Overview}
15
16 In present section we have a look at how you can define new arrow tips for use
17 in \pgfname. The low-level commands for selecting which arrow tips are to be
18 used have already been described in Section~\ref{section-tips}, the general
19 syntax rules for using arrows are detailed in
20 Section~\ref{section-tikz-arrows}. Although Section~\ref{section-tikz-arrows}
21 describes the use of arrows in \tikzname, in reality, \tikzname\ itself does
22 not actually do anything about arrow tips; all of the functionality is
23 implemented on the \pgfname\ level in the commands described in
24 Section~\ref{section-tikz-arrows}. Indeed, even the |/.tip| key handler
25 described in Section~\ref{section-tikz-arrows} is actually implemented on the
26 \pgfname\ layer.
27
28 What has \emph{not} yet been covered is how you can actually define a complete
29 new arrow tip. In \pgfname, arrows are ``meta-arrows'' in the same way that
30 fonts in \TeX\ are ``meta-fonts''. When a meta-arrow is resized, it is not
31 simply scaled, but a possibly complicated transformation is applied to the
32 size.
33
34 A meta-font is not one particular font at a specific size with a specific
35 stroke width (and with a large number of other parameters being fixed). Rather,
36 it is a ``blueprint'' (actually, more like a program) for generating such a
37 font at a particular size and width. This allows the designer of a meta-font to
38 make sure that, say, the font is somewhat thicker and wider at very small
39 sizes. To appreciate the difference: Compare the following texts: ``Berlin''
40 and ``\tikz{\node [scale=2,inner sep=0pt,outer sep=0pt]{\tiny Berlin};}''. The
41 first is a ``normal'' text, the second is the tiny version scaled by a factor
42 of two. Obviously, the first look better. Now, compare ``\tikz{\node
43 [scale=.5,inner sep=0pt,outer sep=0pt]{Berlin};}'' and ``{\tiny Berlin}''. This
44 time, the normal text was scaled down, while the second text is a ``normal''
45 tiny text. The second text is easier to read.
46
47 \pgfname's meta-arrows work in a similar fashion: The shape of an arrow tip can
48 vary according to a great number of parameters, the line width of the arrow tip
49 being one of them. Thus, an arrow tip drawn at a line width of 5pt will
50 typically \emph{not} be five times as large as an arrow tip of line width 1pt.
51 Instead, the size of the arrow will get bigger only slowly as the line width
52 increases.
53
54 To appreciate the difference, here are the |Latex| and
55 |Classical TikZ Rightarrow| arrows, as drawn by \pgfname\ at four different
56 sizes:
57
58 \medskip
59 \begin{tikzpicture}[1/.tip=Latex, 2/.tip=Classical TikZ Rightarrow]
60 \draw[-1, line width=0.1pt] (0pt,0ex) -- +(3,0) node[thin,right] {line width is 0.1pt};
61 \draw[-1, line width=0.4pt] (0pt,-2em) -- +(3,0) node[thin,right] {line width is 0.4pt};
62 \draw[-1, line width=1.2pt] (0pt,-4em) -- +(3,0) node[thin,right] {line width is 1.2pt};
63 \draw[-1, line width=5pt] (0pt,-6em) -- +(3,0) node[thin,right] {line width is 5pt};
64
65 \draw[-2, line width=0.1pt] (6cm,0ex) -- +(3,0) node[thin,right] {line width is 0.1pt};
66 \draw[-2, line width=0.4pt] (6cm,-2em) -- +(3,0) node[thin,right] {line width is 0.4pt};
67 \draw[-2, line width=1.2pt] (6cm,-4em) -- +(3,0) node[thin,right] {line width is 1.2pt};
68 \draw[-2, line width=5pt] (6cm,-6em) -- +(3,0) node[thin,right] {line width is 5pt};
69 \end{tikzpicture}
70
71 \medskip
72 Here, by comparison, are the same arrows when they are simply ``resized'':
73
74 \medskip
75 \begin{tikzpicture}[1/.tip=Latex, 2/.tip=Classical TikZ Rightarrow]
76 \draw[-{1[length=1pt]}, line width=0.1pt] (0pt,0ex) -- +(3,0) node[thin,right] {line width is 0.1pt};
77 \draw[-{1[length=4pt]}, line width=0.4pt] (0pt,-2em) -- +(3,0) node[thin,right] {line width is 0.4pt};
78 \draw[-{1[length=12pt]}, line width=1.2pt] (0pt,-4em) -- +(3,0) node[thin,right] {line width is 1.2pt};
79 \draw[-{1[length=32pt]}, line width=5pt] (0pt,-6em) -- +(3,0) node[thin,right] {line width is 5pt};
80
81 \draw[-{2[length=0.455pt]}, line width=0.1pt] (6cm,0ex) -- +(3,0) node[thin,right] {line width is 0.1pt};
82 \draw[-{2[length=1.82pt]}, line width=0.4pt] (6cm,-2em) -- +(3,0) node[thin,right] {line width is 0.4pt};
83 \draw[-{2[length=5.46pt]}, line width=1.2pt] (6cm,-4em) -- +(3,0) node[thin,right] {line width is 1.2pt};
84 \draw[-{2[length=14.56pt]}, line width=5pt] (6cm,-6em) -- +(3,0) node[thin,right] {line width is 5pt};
85 \end{tikzpicture}
86
87 \bigskip
88 As can be seen, simple scaling produces arrow tips that are way too large at
89 larger sizes and way too small at smaller sizes.
90
91 In addition to the line width, other options may also influence the appearance
92 of an arrow tip. In particular, the width of the inner line (the line used to
93 create the effect of a double line) influences arrow tips as well as other
94 options that are specific to the arrow tip.
95
96
97 \subsection{Terminology}
98 \label{section-arrow-terminology}
99
100 Before we have a look at the exact commands used for defining arrow tips, we
101 need to fix some terminology. Consider the following drawing of an arrow tip
102 where the arrow tip is drawn transparently so that we can see what is
103 ``happening behind it'':
104 %
105 \begin{tikzpicture}
106 \draw [red!50, ,line width=1cm] (0,0) -- (4,0);
107 \path [tips, opacity=.25,line width=1cm, -{Stealth[black,line width=0pt,length=4cm, width=4cm, inset=1cm]}] (0,0) -- (6,0);
108
109 \draw [->,thick] (1,0) -- (8,0) node [right] {$x$-axis};
110 \draw [->,thick] (5,-2.25) -- (5,2.25) node [above] {$y$-axis};
111
112 \foreach \i in {-3,-2,-1,1,2} \draw (\i+5,-1mm) -- (\i+5,1mm) node [above] {\small$\i$};
113 \foreach \i in {-2,-1,1,2} \draw (49mm,\i) -- (51mm,\i) node [right] {\small$\i$};
114 \end{tikzpicture}
115
116 I have also added a coordinate system. The code for drawing an arrow tip always
117 draws it in the way shown above: Pointing right along the $x$-axis.
118
119 We will use the following terminology:
120 %
121 \begin{itemize}
122 \item The point where tip of the arrow ends is called the \emph{tip end}.
123 It is at $(1,0)$ in our example and we always assume it to lie on the
124 $x$-axis, so we just treat it as a distance, 1 in this case. This is
125 the position where the original path was supposed to end (so if the
126 arrow tip had not been added to the red path, it would have ended
127 here).
128 \item The \emph{back end} of the arrow is where a vertical line just to the
129 left of the arrow intersects the $x$-axis. In our case, this is the
130 point $(-3,0)$ and again we treat it as a distance, $-3$ in this case.
131 \item The \emph{line end} is the position where the path now ends. This
132 should be a position inside the arrow head that gets ``covered'' by the
133 path. Note that a path may have a round or a rect head and should still
134 be covered. Clearly, necessary shortening of the path will be the
135 difference between the tip end and the line end.
136 \item The \emph{visual back end} is the position where the path and the the
137 arrow head ``meet last'' on the path. In our case, because of the
138 inset, the visual back end is not the same as the back end: The arrow
139 ends ``visually'' at $(-2,0)$. The difference between the back end and
140 the visual back end is important when the arrow tip is flexed, see
141 Section~\ref{section-arrow-flex} for an explanation of flexing.
142 \item There is also a \emph{visual tip end}, the counterpart of the visual
143 back end for the front. In our case, the visual tip end and the tip end
144 obviously coincide, but if we were to reverse the arrow tip, the visual
145 tip end would be different from the tip end (while the visual back end
146 would then coincide with the new back end).
147 \item There are four points that make up the \emph{convex hull} of the
148 arrow tip: $(1,0)$, $(-3,2)$, and $(-3,-2)$.
149
150 Normally, \pgfname\ automatically keeps track of a bounding box of
151 everything you draw. However, since arrow tips are drawn so often,
152 \pgfname\ caches the code needing for drawing arrow tips internally and
153 because of this cache it cannot determine the size of the arrow tip
154 just based on the drawing commands used for drawing the tip. Instead, a
155 convex hull of the arrow tip must be explicitly provided in the
156 definition.
157 \end{itemize}
158
159 When you design a new arrow tip, all of the above parameters must be defined.
160
161
162 \subsection{Caching and Rendering of Arrows}
163
164 As a last preparation for the description of the commands for declaring arrows,
165 it is important to understand the exact process by which \pgfname\ draws
166 arrows.
167 %
168 \begin{enumerate}
169 \item First, you have to define an arrow tip kind using
170 |\pgfdeclarearrow{name=foo,...|. This will tell \pgfname\ that |foo| is %}
171 now the name of an arrow tip. In particular, the parser for arrow tip
172 specifications will now treat |foo| as the name of an arrow tip and
173 will not try to consider |f|, |o|, and |o| as the names of single-char
174 shorthands.
175
176 Other than storing the definitions in the declaration internally, this
177 command has little other effect. In particular, no drawing or other
178 processing takes place.
179 \item Now assume that at some point the arrow tip |foo| is actually used.
180 In this case, certain options may have been set, for instance the user
181 may have requested the arrow tip |foo[length=5pt,open]|. What happens
182 next depends on whether it is the first time the arrow tip |foo| is
183 used with \emph{these exact options} or not.
184 \item Assume that is the first time |foo| is requested at a length of 5pt
185 and in an ``open'' version. \pgfname\ now retrieves the definition of
186 the arrow tip kind that it stored in the first step and executes the
187 so-called \emph{setup} code. When this code is executed, all the
188 options will be in force (for instance, |\pgfarrowlength| will equal
189 |5pt| in our case). The job of the setup code is two-fold: First, it
190 needs to compute all of the parameters listed in
191 Section~\ref{section-arrow-terminology}, that is, it has to compute
192 where the tip end will lie in the arrow tip's coordinate system
193 \emph{at the particular size of 5pt}, where the back end will be, where
194 the convex hull points lie, and so on. Second, the setup code should
195 precompute values that will be important for constructing the path of
196 the arrow. In our example, there is little to do in this regard, but
197 for more complicated arrows, all time-consuming preparations are done
198 now.
199
200 It is \emph{not} the job of the setup to actually draw the arrow tip,
201 only to ``prepare'' this as much as possible.
202
203 The setup code will always be executed only once for each arrow tip
204 kind for a given set of options. Thus, when a user uses
205 |foo[length=5pt,open]| once more later anywhere in the document, the
206 setup code will not be executed again.
207 \item The next thing that happens is that we have a look at the
208 \emph{drawing code} stored in the |code| field of the arrow. In our
209 example, the drawing code would consist of creating a filled path with
210 four straight segments.
211
212 In most cases, what happens now is that the drawing code is executed in
213 a special sandbox in which the low-level driver commands that do the
214 actual drawing are intercepted and stored away in a so-called
215 \emph{cache}. Once such a cache has been created, its contents will be
216 reused whenever |foo[length=5pt,open]| is requested by a user and just
217 like the setup code, the drawing code will not be executed again.
218
219 There are, however, two cases in which the drawing code gets executed
220 each time the arrow is used: First, an arrow tip kind can specify that
221 this should always happen by saying |cache=false| in its definition.
222 This is necessary if the drawing code contains low-level drawing
223 commands that cannot be intercepted such as a use of |\pgftext| for
224 arrow tips that ``contain text''. Second, when the |bend| option is
225 used, the same arrow tip will look different each time it is used,
226 namely in dependence on the exact curvature of the path to which it is
227 added.
228
229 Because the drawing code may be executed several times, while the setup
230 code may not, we must find a way to ``communicate'' the values computed
231 by the setup code to the drawing code. This is done by explicitly
232 calling |\pgfarrowssave| inside the setup code. Whatever is ``saved''
233 in this way is restored each time before the drawing code is executed.
234 \end{enumerate}
235
236 As can be seen, the process is a bit involved, but it leads to a reasonably
237 fast arrow tip management.
238
239
240 \subsection{Declaring an Arrow Tip Kind}
241
242 \begin{command}{\pgfdeclarearrow\marg{config}}
243 This command is both used to define a new arrow tip kind and to to declare
244 a so-called shorthand. We have a look at the case that a complete new arrow
245 tip kind is created and then have a look how the command can be used to
246 create shorthands.
247
248
249 \medskip
250 \noindent\textbf{Defining a Complete New Arrow Tip Kind.}
251 The \meta{config} is a key--value list in which different keys are used to
252 setup the to-be defined arrow. The following keys can be given:
253 %
254 \begin{itemize}
255 \item \declare{|name|}|=|\meta{name} or |name=|\meta{start
256 name}|-|\meta{end name}
257
258 This defines the name of the arrow tip. It is legal to define an
259 arrow tip a second time, in this case the previous definition will
260 be overwritten in the current \TeX\ scope. It is customary to use a
261 name with an uppercase first letter for a ``complete'' arrow tip
262 kind. Short names and lower case names should be used for
263 shorthands that change their meaning inside a document, while arrow
264 tips with uppercase first letters should not be redefined.
265
266 If the name contains a hyphen, the second syntax is assumed and
267 everything before the hyphen will be the name used in start arrow
268 specifications, while the text after the hyphen is the name used in
269 end specifications.
270 \item \declare{|parameters|}|=|\marg{list of macros}
271
272 As explained earlier, an arrow tip typically needs to be redrawn
273 each time an option like |length| or |inset| is changed. However,
274 for some arrow tips, the |inset| has no influence, while for other
275 it is important whether the arrow is reversed or not. (How keys
276 like |length| actually set \TeX\ dimensions like |\pgfarrowlength|
277 is explained in Section~\ref{section-arrow-options}.)
278
279 The job of the |parameters| key is to specify which dependencies
280 the arrow tip has. Everything that will influence any of the
281 parameters computed in the setup code or used in the drawing code
282 should be listed here.
283
284 The \meta{list of macros} will be used inside a
285 |\csname|-|\endcsname| pair and should expand to the current values
286 of the relevant parameters have. For example, if the arrow tip
287 depends on the current value of |\pgfarrowlength| and
288 |\pgfarrowwidth| only, then \meta{list of macros} should be set to
289 |\the\pgfarrowlength,\the\pgfarrowwidth|. (Actually, the comma is
290 optional, the \meta{list of macros} does not really have to be a
291 list, just something that can be expanded unambiguously.)
292
293 Note that the line width (|\pgflinewidth|) and the inner line width
294 (|\pgfinnerlinewidth|) are always parameters and need not be
295 specified in the |parameters|.
296
297 It is important to get this parameter right. Otherwise, arrow tips
298 may look wrong because \pgfname\ thinks that it can reuse some code
299 when, in reality, this code actually depends on a parameter not
300 listed here.
301 \item \declare{|setup code|}|=|\marg{code}
302
303 When an arrow tip is used, the value stored in |parameters| is
304 expanded and it is tested whether the result was encountered
305 before. If not, the \meta{code} gets executed (only this once). The
306 code can now do arbitrarily complicated computations the prepare
307 the later drawing of the arrow tip. Also the \meta{code} must
308 specify the different tip and back ends and the convex hull points.
309 This is done by calling the following macros inside the
310 \meta{code}:
311 %
312 \begin{command}{\pgfarrowssettipend\marg{dimension}}
313 When this command is called inside the setup code of an arrow
314 tip, it specifies that the tip of the drawn arrow will end
315 exactly at \meta{dimension}. For example, for our earlier
316 example of the large arrow tip, where the tip end was at 1cm,
317 we would call
318 %
319 \begin{codeexample}[code only]
320 \pgfarrowssettipend{1cm}
321 \end{codeexample}
322 %
323 Note that for efficiency reasons, the \meta{dimension} is not
324 passed through |\pgfmathsetlength|; rather what happens is that
325 |\pgf@x=|\meta{dimension} gets executed. In particular, you can
326 pack further computations into the \meta{dimension} by simply
327 starting it with a number and then appending some code that
328 modifies |\pgf@x|. Here is an example where instead of 1cm we
329 use $1\mathrm{cm} - \frac12\mathrm{linewidth}$ as the tip end:
330 %
331 \begin{codeexample}[code only]
332 \pgfarrowssettipend{1cm\advance\pgf@x by-.5\pgflinewidth}
333 \end{codeexample}
334 %
335 If the command is not called at all inside the setup code, the
336 tip end is set to |0pt|.
337 \end{command}
338
339 \begin{command}{\pgfarrowssetbackend\marg{dimension}}
340 Works like the command for the tip end, only it sets the back
341 end. In our example we would call
342 %
343 \begin{codeexample}[code only]
344 \pgfarrowssettipend{-3cm}
345 \end{codeexample}
346 %
347 Defaults to |0pt|.
348 \end{command}
349
350 \begin{command}{\pgfarrowssetlineend\marg{dimension}}
351 Sets the line end, so in the example we have
352 |\pgfarrowssettipend{-1cm}|. Default to |0pt|.
353 \end{command}
354
355 \begin{command}{\pgfarrowssetvisualbackend\marg{dimension}}
356 Sets the visual back end, |\pgfarrowssetvisualbackend{-2cm}| in
357 our example. Default to the value of the normal back end.
358 \end{command}
359
360 \begin{command}{\pgfarrowssetvisualtipend\marg{dimension}}
361 Sets the visual tip end. Default to the value of the normal tip
362 end and, thus, we need not set it in our example.
363 \end{command}
364
365 \begin{command}{\pgfarrowshullpoint\marg{x dimension}\marg{y dimension}}
366 Adds a point to the convex hull of the arrow tip. As for the
367 previous commands, no math parsing is done; instead \pgfname\
368 says |\pgf@x=|\meta{x dimension} and then |\pgf@y=|\meta{y
369 dimension}. Thus, both ``dimensions'' can contain code for
370 advancing and thus modifying |\pgf@x| and |\pgf@y|.
371
372 In our example we would write
373 %
374 \begin{codeexample}[code only]
375 \pgfarrowshullpoint{1cm}{0pt}
376 \pgfarrowshullpoint{-3cm}{2cm}
377 \pgfarrowshullpoint{-3cm}{-2cm}
378 \end{codeexample}
379 \end{command}
380
381 \begin{command}{\pgfarrowsupperhullpoint\marg{x dimension}\marg{y dimension}}
382 This command works like the previous command, only it normally
383 adds \emph{two} points to the convex hull: First, the point
384 $(\meta{x dimension},\meta{y dimension})$ and, secondly, the
385 point $(\meta{x dimension},-\meta{y dimension})$. However, the
386 second point is only added if the arrow is not a harpoon.
387
388 Thus, in our example we could simplify the convex hull to
389 %
390 \begin{codeexample}[code only]
391 \pgfarrowshullpoint{1cm}{0pt}
392 \pgfarrowsupperhullpoint{-3cm}{2cm}
393 \end{codeexample}
394 %
395 If the \meta{y dimension} is zero or less, only one point,
396 namely $(\meta{x dimension},\meta{y dimension})$, is added to
397 the hull. Thus, we could also have used the upper convex hull
398 command in the first of the two of the above commands.
399 \end{command}
400
401 \begin{command}{\pgfarrowssave\marg{macro}}
402 As explained earlier, the setup code needs to ``communicate''
403 with the drawing code via ``saved values''. This command get
404 the name of a macro and will store the value this macro had
405 internally. Then, each time drawing code is executed, the value
406 of this macro will be restored.
407 \end{command}
408
409 \begin{command}{\pgfarrowssavethe\marg{register}}
410 Works like |\pgfarrowssave|, only the parameter must be a
411 register and |\the|\meta{register} will be saved. Typically,
412 you will write something like
413 %
414 \begin{codeexample}[code only]
415 \pgfarrowssavethe{\pgfarrowlength}
416 \pgfarrowssavethe{\pgfarrowwidth}
417 \end{codeexample}
418 %
419 To ensure that inside the drawing code the the dimension
420 registers |\pgfarrowlength| and |\pgfarrowwidth| are setup with
421 the values they had during the setup.
422 \end{command}
423 \item \declare{|drawing code|}|=|\marg{code}
424
425 This code will be executed at least once for each setting of the
426 parameters when the time arrow tip is actually drawn. Usually, this
427 one execution will be all and the low-level commands generated
428 inside the \meta{code} will we stored in a special cache; but in
429 some cases the \meta{code} gets executed each time the arrow tip is
430 used, so do not assume anything about it. Inside the \meta{code},
431 you have access to all values that were saved in the setup code as
432 well as to the line width.
433
434 The \meta{code} should draw the arrow tip ``going right along the
435 $x$-axis''. \pgfname\ will take care of setting up a canvas
436 transformation beforehand to a rotation such that when the drawing
437 is rendered, the arrow tip that is actually drawn points in the
438 direction of the line. Alternatively, when bending is switched on,
439 even more complicated low-level transformations will be done
440 automatically.
441
442 The are some special considerations concerning the \meta{code}:
443 %
444 \begin{itemize}
445 \item In the \meta{code} you may \emph{not} use |\pgfusepath|
446 since this would try to add arrow tips to the arrow tip and
447 lead to a recursion. Use the ``quick'' versions
448 |\pgfusepathqstroke| and so on instead, which never try to
449 add arrow tips.
450 \item If you stroke the path that you construct, you should
451 first set the dashing to solid and set up fixed joins and
452 caps, as needed. This will ensure that the arrow tip will
453 always look the same.
454 \item When the arrow tip code is executed, it is automatically
455 put inside a low-level scope, so nothing will ``leak out''
456 from the scope.
457 \item The high-level coordinate transformation matrix will be
458 set to the identity matrix when the code is executed for
459 the first time.
460 \end{itemize}
461 \item \declare{|cache|}|=|\meta{true or false}
462
463 When set to |true|, which is the default, the \meta{code} will be
464 executed only once for a particular value of parameters and the
465 low-level commands created by the drawing code (using the system
466 layer protocol subsystem, see Section~\ref{section-protocols}) will
467 be cached and reused later on. However, when the drawing code
468 contains ``uncacheable'' code like a call to |\pgftext|, caching
469 must be switched off by saying |cache=false|.
470 \item \declare{|bending mode|}|=|\meta{mode}
471
472 This key is important only when the |bend| option is used with an
473 arrow, see Section~\ref{section-arrow-flex} for an introduction to
474 this option. The |bend| option asks us to, well, bend the arrow
475 head. For some arrow head this is not possible or leads to very
476 strange drawings (for instance, when the |\pgftext| command is
477 used) and then it is better to switch bending off for the arrow
478 head (|flex| will then be used instead). To achieve this, set
479 \meta{mode} to |none|.
480
481 For most arrow tips it does, however, make sense to bend them.
482 There are (at least) two different mathematical ways of doing so,
483 see Section~\ref{section-library-curvilinear} for details. Which of
484 these ways is use can be configured by setting \meta{mode} to
485 either |orthogonal| or to |polar|. It is best to try simply try out
486 both when designing an arrow tip to see which works better. Since
487 |orthogonal| is quicker and often gives good or even better
488 results, it is the default. Some arrow tips, however, profit from
489 saying |bending mode=polar|.
490 \item \declare{|defaults|}|=|\meta{arrow keys}
491
492 The \meta{arrow keys} allow you to configure the default values for
493 the parameters on which an arrow tip depends. The \meta{arrow keys}
494 will be executed first before any other arrow tip options are
495 executed, see Section~\ref{section-arrow-scopes} for the exact
496 sequence. Also see Section~\ref{section-arrow-options} below for
497 more details on arrow options.
498 \end{itemize}
499
500 This concludes the description of the keys you provide for the declaration
501 of an arrow. Let us now have a look at a simple example that uses these
502 features: We want to define an arrow tip kind |foo| that produces the arrow
503 tip we used as our running example. However, to make things a bit more
504 interesting, let us make it ``configurable'' insofar as the length of the
505 arrow tip can be configured using the |length| option, which sets the
506 |\pgfarrowlength|. By default, this length should be the gigantic 4cm we
507 say in the example, but uses should be able to set it to anything they
508 like. We will not worry about the arrow width or insets, of arrow line
509 width, or harpoons, or anything else in this example to keep it simple.
510
511 Here is the code:
512 %
513 \begin{codeexample}[code only]
514 \pgfdeclarearrow{
515 name = foo,
516 parameters = { \the\pgfarrowlength },
517 setup code = {
518 % The different end values:
519 \pgfarrowssettipend{.25\pgfarrowlength}
520 \pgfarrowssetlineend{-.25\pgfarrowlength}
521 \pgfarrowssetvisualbackend{-.5\pgfarrowlength}
522 \pgfarrowssetbackend{-.75\pgfarrowlength}
523 % The hull
524 \pgfarrowshullpoint{.25\pgfarrowlength}{0pt}
525 \pgfarrowshullpoint{-.75\pgfarrowlength}{.5\pgfarrowlength}
526 \pgfarrowshullpoint{-.75\pgfarrowlength}{-.5\pgfarrowlength}
527 % Saves: Only the length:
528 \pgfarrowssavethe\pgfarrowlength
529 },
530 drawing code = {
531 \pgfpathmoveto{\pgfqpoint{.25\pgfarrowlength}{0pt}}
532 \pgfpathlineto{\pgfqpoint{-.75\pgfarrowlength}{.5\pgfarrowlength}}
533 \pgfpathlineto{\pgfqpoint{-.5\pgfarrowlength}{0pt}}
534 \pgfpathlineto{\pgfqpoint{-.75\pgfarrowlength}{-.5\pgfarrowlength}}
535 \pgfpathclose
536 \pgfusepathqfill
537 },
538 defaults = { length = 4cm }
539 }
540 \end{codeexample}
541 %
542 We can now use it:
543 %
544 \pgfdeclarearrow{
545 name = foo,
546 parameters = { \the\pgfarrowlength },
547 setup code = {
548 % The different end values:
549 \pgfarrowssettipend{.25\pgfarrowlength}
550 \pgfarrowssetlineend{-.25\pgfarrowlength}
551 \pgfarrowssetvisualbackend{-.5\pgfarrowlength}
552 \pgfarrowssetbackend{-.75\pgfarrowlength}
553 % The hull
554 \pgfarrowshullpoint{.25\pgfarrowlength}{0pt}
555 \pgfarrowshullpoint{-.75\pgfarrowlength}{.5\pgfarrowlength}
556 \pgfarrowshullpoint{-.75\pgfarrowlength}{-.5\pgfarrowlength}
557 % Saves: Only the length:
558 \pgfarrowssavethe\pgfarrowlength
559 },
560 drawing code = {
561 \pgfpathmoveto{\pgfqpoint{.25\pgfarrowlength}{0pt}}
562 \pgfpathlineto{\pgfqpoint{-.75\pgfarrowlength}{.5\pgfarrowlength}}
563 \pgfpathlineto{\pgfqpoint{-.5\pgfarrowlength}{0pt}}
564 \pgfpathlineto{\pgfqpoint{-.75\pgfarrowlength}{-.5\pgfarrowlength}}
565 \pgfpathclose
566 \pgfusepathqfill
567 },
568 defaults = { length = 4cm }
569 }
570 \begin{codeexample}[
571 preamble={\usetikzlibrary{arrows.meta}},
572 pre={\pgfdeclarearrow{
573 name = foo,
574 parameters = { \the\pgfarrowlength },
575 setup code = {
576 % The different end values:
577 \pgfarrowssettipend{.25\pgfarrowlength}
578 \pgfarrowssetlineend{-.25\pgfarrowlength}
579 \pgfarrowssetvisualbackend{-.5\pgfarrowlength}
580 \pgfarrowssetbackend{-.75\pgfarrowlength}
581 % The hull
582 \pgfarrowshullpoint{.25\pgfarrowlength}{0pt}
583 \pgfarrowshullpoint{-.75\pgfarrowlength}{.5\pgfarrowlength}
584 \pgfarrowshullpoint{-.75\pgfarrowlength}{-.5\pgfarrowlength}
585 % Saves: Only the length:
586 \pgfarrowssavethe\pgfarrowlength
587 },
588 drawing code = {
589 \pgfpathmoveto{\pgfqpoint{.25\pgfarrowlength}{0pt}}
590 \pgfpathlineto{\pgfqpoint{-.75\pgfarrowlength}{.5\pgfarrowlength}}
591 \pgfpathlineto{\pgfqpoint{-.5\pgfarrowlength}{0pt}}
592 \pgfpathlineto{\pgfqpoint{-.75\pgfarrowlength}{-.5\pgfarrowlength}}
593 \pgfpathclose
594 \pgfusepathqfill
595 },
596 defaults = { length = 4cm }
597 }},
598 ]
599 \tikz \draw [-foo] (0,0) -- (8,0);
600 \end{codeexample}
601 \begin{codeexample}[
602 preamble={\usetikzlibrary{arrows.meta,bending}},
603 pre={\pgfdeclarearrow{
604 name = foo,
605 parameters = { \the\pgfarrowlength },
606 setup code = {
607 % The different end values:
608 \pgfarrowssettipend{.25\pgfarrowlength}
609 \pgfarrowssetlineend{-.25\pgfarrowlength}
610 \pgfarrowssetvisualbackend{-.5\pgfarrowlength}
611 \pgfarrowssetbackend{-.75\pgfarrowlength}
612 % The hull
613 \pgfarrowshullpoint{.25\pgfarrowlength}{0pt}
614 \pgfarrowshullpoint{-.75\pgfarrowlength}{.5\pgfarrowlength}
615 \pgfarrowshullpoint{-.75\pgfarrowlength}{-.5\pgfarrowlength}
616 % Saves: Only the length:
617 \pgfarrowssavethe\pgfarrowlength
618 },
619 drawing code = {
620 \pgfpathmoveto{\pgfqpoint{.25\pgfarrowlength}{0pt}}
621 \pgfpathlineto{\pgfqpoint{-.75\pgfarrowlength}{.5\pgfarrowlength}}
622 \pgfpathlineto{\pgfqpoint{-.5\pgfarrowlength}{0pt}}
623 \pgfpathlineto{\pgfqpoint{-.75\pgfarrowlength}{-.5\pgfarrowlength}}
624 \pgfpathclose
625 \pgfusepathqfill
626 },
627 defaults = { length = 4cm }
628 }},
629 ]
630 \tikz \draw [-{foo[length=2cm,bend]}] (0,0) to [bend left] (3,0);
631 \end{codeexample}
632
633
634 \medskip
635 \noindent\textbf{Defining a Shorthand.}
636 The |\pgfdeclarearrow| command can also used to define
637 \emph{shorthands}. This works as follows:
638 \begin{itemize}
639 \item First, you must provide a |name| just in the same way as when you
640 define a full-flung new arrow tip kind.
641 \item Second, instead of all of the other options listed above, you
642 just use one more option:
643
644 \smallskip
645 \declare{|means|}|=|\meta{end arrow specification}
646
647 This sets up things so that whenever \meta{name} is now used in an
648 arrow specification, it will be replaced by the \meta{end arrow
649 specification} (the problems resulting form the \meta{name} begin
650 used in a start arrow specification are taken care of
651 automatically). See also Section~\ref{section-arrow-tip-macro} for
652 details on the order in which options get executed in such cases.
653
654 Note that the \meta{end arrow specification} will be executed
655 immediately to build the so-called arrow option caches, a concept
656 explored in more detail in
657 Section~\ref{section-arrow-option-cache}. In practice, this has
658 mainly two effects: First, all arrow tips referred to in the
659 specification must already exist (at least as ``dummy'' versions).
660 Second, all dimensions mentioned in options of the \meta{end arrow
661 specification} will be evaluated immediately. For instance, when
662 you write
663 %
664 \begin{codeexample}[code only]
665 \pgfdeclarearrow{ name=foo, means = bar[length=2cm+\mydimen] }
666 \end{codeexample}
667 %
668 The value |2cm+\mydimen| is evaluated immediately. When |foo| is
669 used later on and |\mydimen| has changed, this has no effect.
670 \end{itemize}
671 \end{command}
672
673
674 \subsection{Handling Arrow Options}
675 \label{section-arrow-options}
676
677 When you declare an arrow tip, your drawing code should take into account the
678 different arrow keys set for it (like the arrow tip length, width, or
679 harpooning). The different arrow keys that are available have been described in
680 detail in Section~\ref{section-arrow-config}; but how do we access the values
681 set by an option like |length| or |harpoon| or |bend| in the drawing code? In
682 the present section we have a look at how this works.
683
684
685 \subsubsection{Dimension Options}
686
687 Most arrow keys, like |length| or |width'|, simple set a \TeX\ dimension
688 register to a certain value. For example, |length| sets the value of the \TeX\
689 dimension register |\pgfarrowlength|. Note that |length| takes several values
690 as input with a complicated semantics as explained for the |length| key on
691 page~\pageref{length-arrow-key}. All of these settings are not important for
692 the setup code: When it gets executed, the code behind the |length| key will
693 have computed a simple number that is stored in |\pgfarrowlength|. Indeed,
694 inside the setup code you do not have access to the exact value given to the
695 |length| key; just to the final computed value.
696
697 The following \TeX\ dimensions are available to the setup code:
698 %
699 \begin{itemize}
700 \item |\pgfarrowslength|. It gets set by the arrow keys |length| and
701 |angle|.
702 \item |\pgfarrowswidth|. It gets set by |width|, |width'|, and |angle|.
703 \item |\pgfarrowsinset|. It gets set by |inset| and |inset'|.
704 \item |\pgfarrowslinewidth|. It gets set by |line width| and |line width'|.
705 \end{itemize}
706
707 If your setup code depends on any of them, add them to the |parameters| key of
708 the arrow tip.
709
710
711 \subsubsection{True--False Options}
712
713 A number of arrow keys just do a yes/no switch, like |reversed|. All of them
714 setup a \TeX-if that you can access in the setup code:
715 %
716 \begin{itemize}
717 \item |\ifpgfarrowreversed| is setup by |reversed|.
718 \item |\ifpgfarrowswap| is setup by |swap| and also |right|.
719 \item |\ifpgfarrowharpoon| is setup by |harpoon| and also |left| and
720 |right|.
721 \item |\ifpgfarrowroundcap| is set to true by |line cap=round| and set to
722 false by |line cap=butt|. It also gets (re)set by |round| and |sharp|.
723 \item |\ifpgfarrowroundjoin| is set to true by |line join=round| and set to
724 false by |line join=miter|. It also gets (re)set by |round| and
725 |sharp|.
726 \item |\ifpgfarrowopen| is set to true by |fill=none| and by |open| (which
727 is a shorthand for |fill=none|) and set to false by |color| and all
728 other |fill=|\meta{color}.
729 \end{itemize}
730
731 If you code depends on any of these, you must add them to the |parameters| in
732 such a way that the parameters are different when the \TeX-if is set from when
733 it is not set. An easy way to achieve this is to write something like
734 %
735 \begin{codeexample}[code only]
736 parameters = { \the\pgfarrowlength,...,
737 \ifpgfarrowharpoon h\fi\
738 \ifpgfarrowroundjoin j\fi}
739 \end{codeexample}
740 %
741 In other words, for each set parameter on which the arrow tip depends, a
742 specific letter is added to the parameters, making them unique.
743
744 The first two of the above keys are a bit special: Reversing and swapping an
745 arrow tip can be done just by fiddling with the transformation matrix: a
746 reverse is a ``flip'' along the $y$-axis and a swap is a flip along the
747 $x$-axis. This is done automatically by \pgfname.
748
749 Nevertheless, you may wish to modify you code in dependence especially of the
750 |reverse| key: When |\ifpgfarrowreverse| is true, \pgfname\ will flip the
751 coordinate system along the $y$-axis, will negate all end values (like line
752 end, tip end, and so on) and will exchange the meaning of back end and tip end
753 as well as of visual back end and visual back end. Usually, this is exactly
754 what one need; \emph{except} that the line end may no longer be appropriate.
755 After all, the line end should be chosen so that it is completely covered by
756 the arrow. Now, when the arrow tip is open, a reversed arrow should no longer
757 have the line end near the old visual back end, but near to the old visual tip
758 end.
759
760 For these reasons, you may need to make the computation of the line end
761 dependent on whether the arrow is reversed or not. Note that when you specify a
762 different line end for a reversed arrow tip, the transformation and inverting
763 of the coordinate system will still be done, meaning that if |reverse| is true,
764 you need to specify a line end in the ``old'' coordinate system that is at the
765 position where, after everything is inverted, it will be at the correct
766 position. Usually that means that if the |reverse| option is set, you need to
767 \emph{increase} the line end.
768
769
770 \subsubsection{Inaccessible Options}
771
772 There are some options that influence the way an arrow tip looks, but that you
773 cannot access inside the setup code. Handling these options lies entirely with
774 \pgfname. If you wish your setup code to handle these options, you have to
775 setup your own ``parallel'' options.
776 %
777 \begin{itemize}
778 \item |quick|, |flex|, |flex'|, and |bend| are all handled automatically.
779 You can, however, set the |bending mode| to avoid bending of your arrow
780 tip.
781 \item The colors set by |color| and |fill|. You can, however, access them
782 indirectly, namely through the current stroke and fill colors.
783 \item |sep|
784 \end{itemize}
785
786
787 \subsubsection{Defining New Arrow Keys}
788 \label{section-arrow-option-cache}
789
790 The set of predefined options is already quite long and most arrow tips will
791 not need more than the predefined options. However, sometimes an arrow tip may
792 need to introduce a new special-purpose option. For instance, suppose we wish
793 to introduce a new fictive arrow key |depth|. In such cases, you must do two
794 things:
795 %
796 \begin{enumerate}
797 \item Introduce a new dimension register or macro that will hold the
798 configuration value and which will be accessed by the setup code. The
799 could be achieved by saying
800 %
801 \begin{codeexample}[code only]
802 \newdimen\pgfarrowdepth
803 \end{codeexample}
804 %
805 \item Introduce a new arrow key option |/pgf/arrow keys/depth| that allows
806 users to configure the new macro or register.
807 \end{enumerate}
808
809 When an arrow is selected via for instance |foo[depth=5pt]|, the key--value
810 pairs between the square brackets are executed with the path prefix
811 |/pgf/arrow keys|. Thus, in the example, our depth key would get executed.
812 Thus, it is tempting to write something like
813 %
814 \begin{codeexample}[code only]
815 \pgfkeys{/pgf/arrow keys/depth/.code = \pgfmathsetlength{\pgfarrowdepth}{#1}}
816 \end{codeexample}
817
818 Sadly, this will not work. The reason is that there is yet another level of
819 caching involved when \pgfname\ processes arrow tips: The option cache! The
820 problem is each time an arrow tip is used, even when the drawing code of the
821 arrow tip is nicely cached, we still need to process the options in
822 |foo[length=5pt]| to find out which version in the cache we would like to
823 access. To make matters worse, |foo| might be a shorthand that calls other
824 arrow tips, which add more options, and so on. Unfortunately, executing keys is
825 quite an expensive operation (\pgfname's key--value parser is powerful, but
826 that power comes at a price). So, whenever possible, we do \emph{not} want the
827 key--value parser to be started.
828
829 For these reasons, when something like |foo[|\meta{options}|]| is encountered
830 inside a shorthand, the \meta{options} are executed only once. They should now
831 setup the \emph{arrow option cache}, which is some code that, when executed,
832 should setup the values that the \meta{options} configure. In our example, the
833 |depth| key should add something to the arrow option cache that sets
834 |\pgfarrowdepth| to the given value.
835
836 Adding something to the arrow option cache is done using the following command:
837
838 \begin{command}{\pgfarrowsaddtooptions\marg{code}}
839 This command should be called by keys with the prefix |/pgf/arrow keys| to
840 add code to the arrow option cache. For our |depth| key example, we could
841 use this key as follows:
842 %
843 \begin{codeexample}[code only]
844 \pgfkeys{/pgf/arrow keys/depth/.code=
845 \pgfarrowsaddtooptions{\pgfmathsetlength{\pgfarrowdepth}{#1}}
846 \end{codeexample}
847 %
848 Actually, this is still not optimal since the expensive |\pgfmathsetlength|
849 command is now called each time an arrow tip is used with the |depth|
850 option set. The trick is to do the expensive operation only once and then
851 store only very quick code in the arrow option cache:
852 %
853 \begin{codeexample}[code only]
854 \pgfkeys{/pgf/arrow keys/depth/.code=
855 \pgfmathsetlength{\somedimen}{#1}
856 \pgfarrowsaddtooptions{\pgfarrowdepth=\somedimen} % buggy
857 \end{codeexample}
858 %
859 The above code will not (yet) work since |\somedimen| will surely have a
860 different value when the cache is executed. The trick is to use some
861 |\expandafter|s:
862 %
863 \begin{codeexample}[code only]
864 \pgfkeys{/pgf/arrow keys/depth/.code=
865 \pgfmathsetlength{\somedimen}{#1}
866 \expandafter\pgfarrowsaddtooptions\expandafter{\expandafter\pgfarrowdepth\expandafter=\the\somedimen}
867 \end{codeexample}
868 %
869 \end{command}
870
871 \begin{command}{\pgfarrowsaddtolateoptions\marg{code}}
872 This command works like |\pgfarrowsaddtooptions|, only the \meta{code} will
873 be executed ``later'' than the code added by the normal version of the
874 command. This is useful for keys that depend on the length of an arrow:
875 Keys like |width'| want to define the arrow width as a multiple of the
876 arrow length, but when the |width'| key is given, the length may not yet
877 have been specified. By making the computation of the width a ``late''
878 option, we ensure that |\pgfarrowlength| will have been setup correctly.
879 \end{command}
880
881 If you define a new option that sets a dimensions and if that dimension should
882 change in accordance to the setting of either |scale length| or |scale width|,
883 you need to make \pgfname\ ``aware'' of this using the following key:
884
885 \begin{command}{\pgfarrowsaddtolengthscalelist\marg{dimension register}}
886 Each time an arrow tip is used, the given \meta{dimension register} will be
887 multiplied by the |scale length| factor prior to the actual drawing. You
888 call this command only once in the preamble somewhere.
889 \end{command}
890
891 \begin{command}{\pgfarrowsaddtowidthscalelist\marg{dimension register}}
892 Works like |\pgfarrowsaddtolengthscalelist|, only for width parameters.
893 \end{command}
894
895
896 \begin{command}{\pgfarrowsthreeparameters\marg{line-width dependent size specification}}
897 This command is useful for parsing the values given to keys like |length|
898 or |width| the expect a dimension followed optionally for some numbers.
899 This command converts the \meta{line-width dependent size specification},
900 which may consist of one, two, or three numbers, into a triple of three
901 numbers in curly braces, which gets stored in the macro
902 |\pgfarrowstheparameters|. Here is an example, where |\showvalueofmacro| is
903 used in this example to show the value stored in a macro:
904 %
905 \begin{codeexample}[setup code,hidden]
906 \makeatletter
907 \def\showvalueofmacro#1{%
908 \texttt{\expandafter\expandafter\expandafter\expandafter\expandafter\expandafter\expandafter\pgfutil@gobble\expandafter\expandafter\expandafter\string\expandafter\csname#1\endcsname}
909 }%
910 \end{codeexample}
911 %
912 \begin{codeexample}[]
913 \pgfarrowsthreeparameters{2pt 1}
914 \showvalueofmacro\pgfarrowstheparameters
915 \end{codeexample}
916 %
917 \end{command}
918
919 \begin{command}{\pgfarrowslinewidthdependent\marg{dimension}\marg{line width factor}\marg{outer factor}}
920 This command takes three parameters and does the ``line width dependent
921 computation'' described on page~\pageref{length-arrow-key} for the |length|
922 key. The result is returned in |\pgf@x|.
923
924 The idea is that you can setup line-width dependent keys like |length| or
925 |width| using code like the following:
926 %
927 \begin{codeexample}[code only]
928 \pgfkeys{/pgf/arrow keys/depth/.code={%
929 \pgfarrowsthreeparameters{#1}%
930 \expandafter\pgfarrowsaddtolateoptions\expandafter{%
931 \expandafter\pgfarrowslinewidthdependent\pgfarrowstheparameters% compute...
932 \pgfarrowdepth\pgf@x% ... and store.
933 }%
934 }
935 \end{codeexample}
936 %
937 \end{command}
938
939 \begin{command}{\pgfarrowslengthdependent\marg{dimension}\marg{length factor}\marg{dummy}}
940 This command takes three parameters, of which the last one is ignored, and
941 does the ``length dependent computation'' described for the |width'| and
942 |inset'| keys. The result is returned in |\pgf@x|.
943
944 You can setup length dependent keys using code like the following:
945 %
946 \begin{codeexample}[code only]
947 \pgfkeys{/pgf/arrow keys/depth'/.code={%
948 \pgfarrowsthreeparameters{#1}%
949 \expandafter\pgfarrowsaddtolateoptions\expandafter{%
950 \expandafter\pgfarrowslengthdependent\pgfarrowstheparameters% compute...
951 \pgfarrowdepth\pgf@x% ... and store.
952 }%
953 }
954 \end{codeexample}
955 %
956 \end{command}
957
958
959 %%% Local Variables:
960 %%% mode: latex
961 %%% TeX-master: "pgfmanual"
962 %%% End: