summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-arrows.tex
blob: 15926efe5674941dc5728fa39513da056429ca65 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
% Copyright 2013 by Till Tantau
%
% This file may be distributed and/or modified
%
% 1. under the LaTeX Project Public License and/or
% 2. under the GNU Free Documentation License.
%
% See the file doc/generic/pgf/licenses/LICENSE for more details.


\section{Defining New Arrow Tip Kinds}
\label{section-arrows}


\subsection{Overview}

In present section we have a look at how you can define new arrow tips
for use in \pgfname. The low-level commands for selecting which arrow
tips are to be used have already been described in
Section~\ref{section-tips}, the general syntax rules for using arrows
are detailed in Section~\ref{section-tikz-arrows}. Although
Section~\ref{section-tikz-arrows} describes the use of arrows in
\tikzname, in reality, \tikzname\ itself does not actually do anything
about arrow tips; all of the functionality is implemented on the
\pgfname\ level in the commands described in
Section~\ref{section-tikz-arrows}. Indeed, even the |/.tip| key
handler described in Section~\ref{section-tikz-arrows} is actually
implemented on the \pgfname\ layer.

What has \emph{not} yet been covered is how you can actually define a
complete new arrow tip. In \pgfname, arrows are ``meta-arrows'' in the
same way that fonts in \TeX\ are ``meta-fonts.'' When a meta-arrow is
resized, it is not simply scaled, but a possibly complicated
transformation is applied to the size.

A meta-font is not one particular font at a specific size with a
specific stroke width (and with a large number of other parameters
being fixed). Rather, it is a ``blueprint'' (actually, more like a
program) for generating such a font at a particular size and
width. This allows the designer of a meta-font to make sure that, say,
the font is somewhat thicker and wider at very small sizes. To
appreciate the difference: Compare the following texts: ``Berlin'' and
``\tikz{\node [scale=2,inner sep=0pt,outer sep=0pt]{\tiny
    Berlin};}''. The first is a ``normal'' text, the second is the tiny
version scaled by a factor of two. Obviously, the first look
better. Now, compare  ``\tikz{\node [scale=.5,inner sep=0pt,outer
  sep=0pt]{Berlin};}'' and ``{\tiny Berlin}''. This time, the normal
text was scaled down, while the second text is a ``normal'' tiny
text. The second text is easier to read.

\pgfname's meta-arrows work in a similar fashion: The shape of an
arrow tip can vary according to a great number of parameters, the line
width of the arrow tip being one of them. Thus, an arrow tip drawn at
a line width of 5pt will typically \emph{not} be five times as large
as an arrow tip of line width 1pt. Instead, the size of the arrow will
get bigger only slowly as the line width increases. 

To appreciate the difference, here are the |Latex| and
|Classical TikZ Rightarrow| arrows, as drawn by \pgfname\ at four different sizes:

\medskip
\begin{tikzpicture}[1/.tip=Latex, 2/.tip=Classical TikZ Rightarrow]
  \draw[-1, line width=0.1pt] (0pt,0ex) -- +(3,0)  node[thin,right] {line width is 0.1pt};
  \draw[-1, line width=0.4pt] (0pt,-2em) -- +(3,0) node[thin,right] {line width is 0.4pt};
  \draw[-1, line width=1.2pt] (0pt,-4em) -- +(3,0) node[thin,right] {line width is 1.2pt};
  \draw[-1, line width=5pt]   (0pt,-6em) -- +(3,0) node[thin,right] {line width is 5pt};

  \draw[-2, line width=0.1pt] (6cm,0ex) -- +(3,0)  node[thin,right] {line width is 0.1pt};
  \draw[-2, line width=0.4pt] (6cm,-2em) -- +(3,0) node[thin,right] {line width is 0.4pt};
  \draw[-2, line width=1.2pt] (6cm,-4em) -- +(3,0) node[thin,right] {line width is 1.2pt};
  \draw[-2, line width=5pt]   (6cm,-6em) -- +(3,0) node[thin,right] {line width is 5pt};
\end{tikzpicture}

\medskip
Here, by comparison, are the same arrows when they are simply ``resized'':

\medskip
\begin{tikzpicture}[1/.tip=Latex, 2/.tip=Classical TikZ Rightarrow]
  \draw[-{1[length=1pt]}, line width=0.1pt] (0pt,0ex) -- +(3,0)  node[thin,right] {line width is 0.1pt};
  \draw[-{1[length=4pt]}, line width=0.4pt] (0pt,-2em) -- +(3,0) node[thin,right] {line width is 0.4pt};
  \draw[-{1[length=12pt]}, line width=1.2pt] (0pt,-4em) -- +(3,0) node[thin,right] {line width is 1.2pt};
  \draw[-{1[length=32pt]}, line width=5pt]   (0pt,-6em) -- +(3,0) node[thin,right] {line width is 5pt};

  \draw[-{2[length=0.455pt]}, line width=0.1pt] (6cm,0ex) -- +(3,0)  node[thin,right] {line width is 0.1pt};
  \draw[-{2[length=1.82pt]}, line width=0.4pt] (6cm,-2em) -- +(3,0) node[thin,right] {line width is 0.4pt};
  \draw[-{2[length=5.46pt]}, line width=1.2pt] (6cm,-4em) -- +(3,0) node[thin,right] {line width is 1.2pt};
  \draw[-{2[length=14.56pt]}, line width=5pt]   (6cm,-6em) -- +(3,0) node[thin,right] {line width is 5pt};
\end{tikzpicture}

\bigskip
As can be seen, simple scaling produces arrow tips that are way too
large at larger sizes and way too small at smaller sizes.

In addition to the line width, other options may also influence the
appearance of an arrow tip. In particular, the width of the inner line
(the line used to create the effect of a double line) influences arrow
tips as well as other options that are specific to the arrow tip.


\subsection{Terminology}
\label{section-arrow-terminology}

Before we have a look at the exact commands used for defining arrow
tips, we need to fix some terminology. Consider the following drawing
of an arrow tip where the arrow tip is drawn transparently so that we
can see what is ``happening behind it'':

\begin{tikzpicture}
  \draw [red!50, ,line width=1cm] (0,0) -- (4,0);
  \path [tips, opacity=.25,line width=1cm, -{Stealth[black,line width=0pt,length=4cm, width=4cm, inset=1cm]}] (0,0) -- (6,0);
  
  \draw [->,thick] (1,0) -- (8,0) node [right] {$x$-axis};
  \draw [->,thick] (5,-2.25) -- (5,2.25) node [above] {$y$-axis};

  \foreach \i in {-3,-2,-1,1,2} \draw (\i+5,-1mm) -- (\i+5,1mm) node [above] {\small$\i$};
  \foreach \i in {-2,-1,1,2} \draw (49mm,\i) -- (51mm,\i) node [right] {\small$\i$};;
\end{tikzpicture}

I have also added a coordinate system. The code for drawing an arrow
tip always draws it in the way shown above: Pointing right along the
$x$-axis.

We will use the following terminology:
\begin{itemize}
\item The point where tip of the arrow ends is called the
  \emph{tip end}. It is at $(1,0)$ in our example and we always
  assume it to lie on the $x$-axis, so we just treat it as a distance,
  1 in this case. This is the position where the original path was
  supposed to end (so if the arrow tip had not been added to the red
  path, it would have ended here).
\item The \emph{back end} of the arrow is where a vertical line just
  to the left of the arrow intersects the $x$-axis. In our case, this
  is the point $(-3,0)$ and again we treat it as a distance, $-3$ in
  this case.
\item The \emph{line end} is the position where the path now
  ends. This should be a position inside the arrow head that gets
  ``covered'' by the path. Note that a path may have a round or a rect
  head and should still be covered. Clearly, necessary shortening of
  the path will be the difference between the tip end and the line
  end.
\item The \emph{visual back end} is the position where the path and
  the the arrow head ``meet last'' on the path. In our case, because
  of the inset, the visual back end is not the same as the back end:
  The arrow ends ``visually'' at $(-2,0)$. The difference between the
  back end and the visual back end is important when the arrow tip is
  flexed, see Section~\ref{section-arrow-flex} for an explanation of
  flexing.
\item There is also a \emph{visual tip end}, the counterpart of the
  visual back end for the front. In our case, the visual tip end and
  the tip end obviously coincide, but if we were to reverse the arrow
  tip, the visual tip end would be different form the tip end (while
  the visual back end would then coincide with the new back end).
\item There are four points that make up the \emph{convex hull} of the
  arrow tip: $(1,0)$, $(-3,2)$, and $(-3,-2)$.

  Normally, \pgfname\ automatically keeps track of a bounding box of
  everything you draw. However, since arrow tips are drawn so often,
  \pgfname\ caches the code needing for drawing arrow tips internally
  and because of this cache it cannot determine the size of the arrow
  tip just based on the drawing commands used for drawing the
  tip. Instead, a convex hull of the arrow tip must be explicitly
  provided in the definition.
\end{itemize}

When you design a new arrow tip, all of the above parameters must be
defined.

\subsection{Caching and Rendering of Arrows}

As a last preparation for the description of the commands for
declaring arrows, it is important to understand the exact process by
which \pgfname\ draws arrows.

\begin{enumerate}
\item First, you have to define an arrow tip kind using
  |\pgfdeclarearrow{name=foo,...|. This will tell \pgfname\ that  %}
  |foo| is now the name of an arrow tip. In particular, the 
  parser for arrow tip specifications will now treat |foo| as the name
  of an arrow tip and will not try to consider |f|, |o|, and |o| as
  the names of single-char shorthands.

  Other than storing the definitions in the declaration internally,
  this command has little other effect. In particular, no drawing or
  other processing takes place.
\item Now assume that at some point the arrow tip |foo| is actually
  used. In this case, certain options may have been set, for instance
  the user may have requested the arrow tip
  |foo[length=5pt,open]|. What happens next depends on whether it is
  the first time the arrow tip |foo| is used with \emph{these exact
    options} ornot.
\item Assume that is the first time |foo| is requested at a length of
  5pt and in an ``open'' version. \pgfname\ now retrieves the
  definition of the arrow tip kind that it stored in the first step
  and executes the so-called \emph{setup} code. When this code is
  executed, all the options will be in force (for
  instance, |\pgfarrowlength| will equal |5pt| in our case). The job
  of the setup code is two-fold: First, it needs to compute all of the
  parameters listed in Section~\ref{section-arrow-terminology}, that
  is, it has to compute where the tip end will lie in the arrow tip's
  coordinate system \emph{at the particular size of 5pt}, where the
  back end will be, where the convex hull points lie, and so
  on. Second, the setup code should precompute values that will be
  important for constructing the path of the arrow. In our example,
  there is little to do in this regard, but for more complicated
  arrows, all time-consuming preparations are done now.

  It is \emph{not} the job of the setup to actually draw the arrow
  tip, only to ``prepare'' this as much as possible.

  The setup code will always be executed only once for each arrow tip
  kind for a given set of options. Thus, when a user uses
  |foo[length=5pt,open]| once more later anywhere in the document, the
  setup code will not be executed again.
\item The next thing that happens is that we have a look at the
  \emph{drawin code} stored in the |code| field of the arrow. In our 
  example, the drawing code would consist of creating a filled path
  with four   straight segments.

  In most cases, what happens now is that the drawing code is executed in a
  special sandbox in which the low-level driver commands that do the
  actual drawing are intercepted and stored away in a so-called
  \emph{cache}. Once such a cache has been created, its contents will
  be reused whenever |foo[length=5pt,open]| is requested by a user and
  just like the setup code, the drawing code will not be executed
  again.

  There are, however, two cases in which the drawing code gets executed
  each time the arrow is used: First, an arrow tip kind can specify
  that this should always happen by saying |cachable=false| in its
  definition. This is necessary if the drawing code contains
  low-level drawing commands that cannot be intercepted such as a use
  of |\pgftext| for arrow tips that ``contain text.'' Second, when the
  |bend| option is used, the same arrow tip will look different each
  time it is used, namely in dependence on the exact curvature of the
  path to which it is added.

  Because the drawing code may be executed several times, while the
  setup code may not, we must find a way to ``communicate'' the
  values computed by the setup code to the drawing code. This is done
  by explicitly calling |\pgfarrowssave| inside the setup
  code. Whatever is ``saved'' in this way is restored each time before
  the drawing code is executed.
\end{enumerate}

As can be seen, the process is a bit involved, but it leads to
a reasonably fast arrow tip management.


\subsection{Declaring an Arrow Tip Kind}

\begin{command}{\pgfdeclarearrow\marg{config}}
  This command is both used to define a new arrow tip kind and to to
  declare a so-called shorthand. We have a look at the case that a
  complete new arrow tip kind is created and then have a look how the
  command can be used to create shorthands.
  
  \medskip
  \noindent\textbf{Defining a Complete New Arrow Tip Kind.}  
  The \meta{config} is a key--value list in which different keys are
  used to setup the to-be defined arrow. The following keys can be given:

  \begin{itemize}
  \item \declare{|name|}|=|\meta{name} or |name=|\meta{start name}|-|\meta{end
      name}

    This defines the name of the arrow tip. It is legal to define an
    arrow tip a second time, in this case the previous definition will
    be overwritten in the current \TeX\ scope. It is customary to use
    a name with an uppercase fist letter for a ``complete'' arrow tip
    kind. Short names and lower case names should be used for
    shorthands that change their meaning inside a document, while
    arrow tips with uppercase first letters should not be redefined.

    If the name contains a hyphen, the second syntax is assumed and
    everything before the hyphen will be the name used in start arrow
    specifications, while the text after the hyphen is the name used
    in end specifications.
  \item \declare{|parameters|}|=|\marg{list of macros}
    
    As explained earlier, an arrow tip typically needs to be redrawn
    each time an option like |length| or |inset| is changed. However,
    for some arrow tips, the |inset| has no influence, while for other
    it is important whether the arrow is reversed or not. (How keys
    like |length| actually set \TeX\ dimensions like |\pgfarrowlength|
    is explained in Section~\ref{section-arrow-options}.)

    The job of the |parameters| key is to specify which dependencies
    the arrow tip has. Everything that will influence any of the
    parameters computed in the setup code or used in the drawing code
    should be listed here.

    The \meta{list of macros} will be used inside a
    |\csname|-|\endcsname| pair and should expand to the current
    values of the relevant parameters have. For example, if the arrow
    tip depends on the current value of |\pgfarrowlength| and
    |\pgfarrowwidth| only, then \meta{list of macros} should be set to
    |\the\pgfarrowlength,\the\pgfarrowwidth|. (Actually, the comma is
    optional, the \meta{list of macros} does not really have to be a
    list, just something that can be expanded unambiuously.)
    
    Note that the line width (|\pgflinewidth|) and the inner line
    width (|\pgfinnerlinewidth|) are always parameters and need not be
    specified in the |parameters|.

    It is important to get this parameter right. Otherwise, arrow tips
    may look wrong because \pgfname\ thinks that it can reuse some
    code when, in reality, this code actually depends on a parameter
    not listed here.
    
  \item \declare{|setup code|}|=|\marg{code}

    When an arrow tip is used, the value stored in |parameters| is
    expanded and it is tested whether the result was encountered
    before. If not, the \meta{code} gets executed (only this
    once). The code can now do aribtrarily complicated computations
    the prepare the later drawing of the arrow tip. Also the
    \meta{code} must specify the different tip and back ends and the
    convex hull points. This is done by calling the following macros
    inside the \meta{code}:

    \begin{command}{\pgfarrowssettipend\marg{dimension}}
      When this command is called inside the setup code of an arrow
      tip, it specifies that the tip of the drawn arrow will end
      exactly at \meta{dimension}. For example, for our earlier
      example of the large arrow tip, where the tip end was at 1cm, we
      would call
\begin{codeexample}[code only]
\pgfarrowssettipend{1cm}        
\end{codeexample}
      Note that for efficience reasons, the \meta{dimension} is not
      passed through |\pgfmathsetlength|; rather what happens is that
      |\pgf@x=|\meta{dimension} gets executed. In particular, you can
      pack further computations into the \meta{dimension} by simply
      starting it with a number and then appending some code that
      modifies |\pgf@x|. Here is an example where instead of 1cm we
      use $1\mathrm{cm} - \frac12\mathrm{linewidth}$ as the tip end:
\begin{codeexample}[code only]
\pgfarrowssettipend{1cm\advance\pgf@x by-.5\pgflinewidth}        
\end{codeexample}
      If the command is not called at all inside the setup code, the
      tip end is set to |0pt|.
    \end{command}

    \begin{command}{\pgfarrowssetbackend\marg{dimension}}
      Works like the command for the tip end, only it sets the back
      end. In our example we would call
\begin{codeexample}[code only]
\pgfarrowssettipend{-3cm}        
\end{codeexample}
      Defaults to |0pt|.
    \end{command}

    \begin{command}{\pgfarrowssetlineend\marg{dimension}}
      Sets the line end, so in the example we have
      |\pgfarrowssettipend{-1cm}|. Default to |0pt|.
    \end{command}

    \begin{command}{\pgfarrowssetvisualbackend\marg{dimension}}
      Sets the visual back end, |\pgfarrowssetvisualbackend{-2cm}| in
      our example. Default to the value of the normal back end.
    \end{command}

    \begin{command}{\pgfarrowssetvisualtipend\marg{dimension}}
      Sets the visual tip end. Default to the value of the normal tip
      end and, thus, we need not set it in our example.
    \end{command}

    \begin{command}{\pgfarrowshullpoint\marg{x dimension}\marg{y dimension}}
      Adds a point to the convex hull of the arrow tip. As for the
      previous commands, no math parsing is done; instead \pgfname\
      says |\pgf@x=|\meta{x dimension} and then |\pgf@y=|\meta{y
        dimension}. Thus, both ``dimensions'' can contain code for
      advancing and thus modifying |\pgf@x| and |\pgf@y|.

      In our example we would write
\begin{codeexample}[code only]
\pgfarrowshullpoint{1cm}{0pt}
\pgfarrowshullpoint{-3cm}{2cm}
\pgfarrowshullpoint{-3cm}{-2cm}
\end{codeexample}
    \end{command}


    \begin{command}{\pgfarrowsupperhullpoint\marg{x dimension}\marg{y dimension}}
      This command works like the previous command, only it normally
      adds \emph{two} points to the convex hull: First, the point $(\meta{x
        dimension},\meta{y dimension})$ and, secondly, the point $(\meta{x
        dimension},-\meta{y dimension})$. However, the second point is
      only added if the arrow is not a harpoon. 

      Thus, in our example we could simplify the convex hull to
\begin{codeexample}[code only]
\pgfarrowshullpoint{1cm}{0pt}
\pgfarrowsupperhullpoint{-3cm}{2cm}
\end{codeexample}
      If the \meta{y dimension} is zero or less, only one point,
      namely $(\meta{x dimension},\meta{y dimension})$, is added to
      the hull. Thus, we could also have used the upper convex hull
      command in the first of the two of the above commands.
    \end{command}

    \begin{command}{\pgfarrowssave\marg{macro}}
      As explained earlier, the setup code needs to ``communicate''
      with the drawing code via ``saved values.'' This command get the
      name of a macro and will store the value this macro had
      internally. Then, each time drawing code is executed, the value
      of this macro will be restored.
    \end{command}

    \begin{command}{\pgfarrowssavethe\marg{register}}
      Works like |\pgfarrowssave|, only the parameter must be a
      register and |\the|\meta{register} will be saved.
      Typically, you will write something like
\begin{codeexample}[code only]
\pgfarrowssavethe{\pgfarrowlength}
\pgfarrowssavethe{\pgfarrowwidth}
\end{codeexample}
      To ensure that inside the drawing code the the dimension
      registers |\pgfarrowlength| and |\pgfarrowwidth| are setup with
      the values they had during the setup.
    \end{command}
    
  \item \declare{|drawing code|}|=|\marg{code}

    This code will be executed at least once for each setting of the
    parameters when the time arrow tip is actually drawn. Usually,
    this one execution will be all and the 
    low-level commands generated inside the \meta{code} will we stored
    in a special cache; but in some cases the \meta{code} gets
    executed each time the arrow tip is used, so do not assume
    anything about it. Inside the \meta{code}, you have access to all
    values that were saved in the setup code as well as to the line
    width.
    
    The \meta{code} should draw the arrow tip ``going right along the
    $x$-axis.'' \pgfname\ will take care of setting up a  canvas
    transformation beforehand to a rotation such that when the
    drawing is rendered, the arrow tip that is  actually drawn points
    in the direction of the line. Alternatively, when bending is
    switched on, even more complicated low-level transformations will
    be done automatically.
    
    The are some special considerations concerning the \meta{code}:
    \begin{itemize}
    \item
      In the \meta{code} you may \emph{not} use |\pgfusepath|
      since this would try to add arrow tips to the arrow tip and lead
      to a recursion. Use the ``quick'' versions |\pgfusepathqstroke|
      and so on instead, which never try to add arrow tips.
    \item
      If you stroke the path that you construct, you should first set
      the dashing to solid and set up fixed joins and caps, as
      needed. This will ensure that the arrow tip will always look the
      same.
    \item
      When the arrow tip code is executed, it is automatically put
      inside a low-level scope, so nothing will ``leak out'' from the
      scope.
    \item
      The high-level coordinate transformation matrix will be set to the
      identity matrix when the code is executed for the first time.
    \end{itemize}
    
  \item \declare{|cache|}|=|\meta{true or false}

    When set to |true|, which is the default, the \meta{code} will be
    executed only once for a partiular value of parameters and the
    low-level commands created by the drawing code (using the system
    layer protocol subsystem, see Section~\ref{section-protocols})
    will be cached and reused later on. However, when the drawing code
    contains ``uncachable'' code like a call to |\pgftext|, caching
    must be switched off by saying |cache=false|.

  \item \declare{|bending mode|}|=|\meta{mode}

    This key is important only when the |bend| option is used with an
    arrow, see Section~\ref{section-arrow-flex} for an introduction to
    this option. The |bend| option asks us to, well, bend the arrow
    head. For some arrow head this is not possible or leads to very
    strange drawings (for instance, when the |\pgftext| command is
    used) and then it is better to switch bending off for the arrow
    head (|flex| will then be used instead). To achieve this, set
    \meta{mode} to |none|.

    For most arrow tips it does, however, make sense to bend
    them. There are (at least) two different mathematical ways of
    doing so, see Section~\ref{section-library-curvilinear} for details. Which of
    these ways is use can be configured by setting \meta{mode} to
    either |orthogonal| or to |polar|. It is best to try simply try
    out both when designing an arrow tip to see which works
    better. Since |orthogonal| is quicker and often gives good oder
    even better results, it is the default. Some arrow tips, however,
    profit from saying |bending mode=polar|.

  \item \declare{|defaults|}|=|\meta{arrow keys}

    The \meta{arrow keys} allow you to configure the default values
    for the parameters on which an arrow tip depends. The \meta{arrow
      keys} will be executed first before any other arrow tip options
    are executed, see Section~\ref{section-arrow-scopes} for the exact
    sequence. Also see Section~\ref{section-arrow-options} below for
    more details on arrow options.
  \end{itemize}

  This concludes the description of the keys you provide for the
  declaration of an arrow. Let us now have a look at a simple example
  that uses these features: We want to define an arrow tip kind |foo|
  that produces the arrow tip we used as our running examlpe. However,
  to make things a bit more interesting, let us make it
  ``configurable'' insofar as the length of the arrow tip can be
  configured using the |length| option, which sets the
  |\pgfarrowlength|. By default, this length should be the gigantic
  4cm we say in the example, but uses should be able to set it to
  anything they like. We will not worry about the arrow width or
  insets, of arrow line width, or harpoons, or anything else in this
  example to keep it simple.

  Here is the code:
\begin{codeexample}[code only]
\pgfdeclarearrow{
  name = foo,
  parameters = { \the\pgfarrowlength },
  setup code = {
    % The different end values:
    \pgfarrowssettipend{.25\pgfarrowlength}
    \pgfarrowssetlineend{-.25\pgfarrowlength}
    \pgfarrowssetvisualbackend{-.5\pgfarrowlength}
    \pgfarrowssetbackend{-.75\pgfarrowlength}
    % The hull
    \pgfarrowshullpoint{.25\pgfarrowlength}{0pt}
    \pgfarrowshullpoint{-.75\pgfarrowlength}{.5\pgfarrowlength}
    \pgfarrowshullpoint{-.75\pgfarrowlength}{-.5\pgfarrowlength}
    % Saves: Only the length:
    \pgfarrowssavethe\pgfarrowlength
  },
  drawing code = {
    \pgfpathmoveto{.25\pgfarrowlength}{0pt}
    \pgfpathlineto{-.75\pgfarrowlength}{.5\pgfarrowlength}
    \pgfpathlineto{-.5\pgfarrowlength}{0pt}
    \pgfpathlineto{-.75\pgfarrowlength}{-.5\pgfarrowlength}
    \pgfpathclose
    \pgfusepathqfill
  },
  defaults = { length = 4cm }
}   
\end{codeexample}
  We can now use it:
\pgfdeclarearrow{
  name = foo,
  parameters = { \the\pgfarrowlength },
  setup code = {
    % The different end values:
    \pgfarrowssettipend{.25\pgfarrowlength}
    \pgfarrowssetlineend{-.25\pgfarrowlength}
    \pgfarrowssetvisualbackend{-.5\pgfarrowlength}
    \pgfarrowssetbackend{-.75\pgfarrowlength}
    % The hull
    \pgfarrowshullpoint{.25\pgfarrowlength}{0pt}
    \pgfarrowshullpoint{-.75\pgfarrowlength}{.5\pgfarrowlength}
    \pgfarrowshullpoint{-.75\pgfarrowlength}{-.5\pgfarrowlength}
    % Saves: Only the length:
    \pgfarrowssavethe\pgfarrowlength
  },
  drawing code = {
    \pgfpathmoveto{\pgfqpoint{.25\pgfarrowlength}{0pt}}
    \pgfpathlineto{\pgfqpoint{-.75\pgfarrowlength}{.5\pgfarrowlength}}
    \pgfpathlineto{\pgfqpoint{-.5\pgfarrowlength}{0pt}}
    \pgfpathlineto{\pgfqpoint{-.75\pgfarrowlength}{-.5\pgfarrowlength}}
    \pgfpathclose
    \pgfusepathqfill
  },
  defaults = { length = 4cm }
}    
\begin{codeexample}[]
\tikz \draw [-foo] (0,0) -- (8,0);    
\end{codeexample}
\begin{codeexample}[]
\tikz \draw [-{foo[length=2cm,bend]}] (0,0) to [bend left] (3,0);    
\end{codeexample}

  \medskip
  \noindent\textbf{Defining a Shorthand.}  
  The |\pgfdeclarearrow| command can also used to define
  \emph{shorthands}. This works as follows:
  \begin{itemize}
  \item First, you must provide a |name| just in the same way as when
    you define a full-flung new arrow tip kind.
  \item Second, instead of all of the other options listed above, you
    just use one more option:
    
    \smallskip
    \declare{|means|}|=|\meta{end arrow specification}
    
    This sets up things so that whenever \meta{name} is now used in an
    arrow specification, it will be replaced by the \meta{end arrow
      specification} (the problems resulting form the \meta{name}
    begin used in a start arrow  specification are taken care of
    automatically). See also Section~\ref{section-arrow-tip-macro} for
    details on the order in which options get executed in such cases.

    Note that the \meta{end arrow specification} will be executed
    immediately to build the so-called arrow option caches, a concept
    explored in more detail in
    Section~\ref{section-arrow-option-cache}. In practice, this has
    mainly two effects: First, all arrow tips referred to in the
    specification must already exist (at least as ``dummy''
    versions). Second, all dimensions mentioned in options of the
    \meta{end arrow specification} will be evaluated immediately. For
    instance, when you write
\begin{codeexample}[code only]
\pgfdeclarearrow{ name=foo, means = bar[length=2cm+\mydimen] }      
\end{codeexample}
    The value |2cm+\mydimen| is evaluated immediately. When |foo| is
    used later on and |\mydimen| has changed, this has no effect. 
  \end{itemize}
\end{command}



\subsection{Handling Arrow Options}

\label{section-arrow-options}

When you declare an arrow tip, your drawing code should take into
account the different arrow keys set for it (like the arrow tip length, 
width, or harpooning). The different arrow keys that are available
have been described in detail in Section~\ref{section-arrow-config}; but
how do we access the values set by an option like |length| or
|harpoon| or |bend| in the drawing code? In the present section we
have a look at how this works.


\subsubsection{Dimension Options}

Most arrow keys, like |length| or |width'|, simple set a \TeX\
dimension register to a certain value. For example, |length| sets the
value of the \TeX\ dimension register |\pgfarrowlength|. Note that
|length| takes several values as input with a complicated semantics as
explained for the |length| key on
page~\pageref{length-arrow-key}. All of these settings are not
important for the setup code: When it gets executed, the code behind
the |length| key will have computed a simple number that is stored
in |\pgfarrowlength|. Indeed, inside the setup code you do not have
access to the exact value given to the |length| key; just to the
final computed value.

The following \TeX\ dimensions are available to the setup code:

\begin{itemize}
\item |\pgfarrowslength|. It gets set by the arrow keys |length| and |angle|.
\item |\pgfarrowswidth|. It gets set by |width|, |width'|, and |angle|.
\item |\pgfarrowsinset|. It gets set by |inset| and |inset'|.
\item |\pgfarrowslinewidth|. It gets set by |line width| and |line width'|.
\end{itemize}

If your setup code depends on any of them, add them to the
|parameters| key of the arrow tip.


\subsubsection{True--False Options}

A number of arrow keys just do a yes/no switch, like |reversed|. All
of them setup a \TeX-if that you can access in the setup code:

\begin{itemize}
\item |\ifpgfarrowreversed| is setup by |reversed|.
\item |\ifpgfarrowswap| is setup by |swap| and also |right|.
\item |\ifpgfarrowharpoon| is setup by |harpoon| and also |left| and |right|.
\item |\ifpgfarrowroundcap| is set to true by |line cap=round| and set
  to false by |line cap=butt|. It also gets (re)set by  |round| and |sharp|.
\item |\ifpgfarrowroundjoin| is set to true by |line join=round| and set
  to false by |line join=miter|. It also gets (re)set by  |round| and |sharp|.
\item |\ifpgfarrowopen| is set to true by |fill=none| and by |open|
  (which is a shorthand for |fill=none|) and set to false by |color|
  and all other |fill=|\meta{color}.  
\end{itemize}

If you code depends on any of these, you must add them to
the |parameters| in such a way that the parameters are different when
the \TeX-if is set from when it is not set. An easy way to achieve
this is to write something like
\begin{codeexample}[code only]
  parameters = { \the\pgfarrowlength,...,
                 \ifpgfarrowharpoon h\fi\
                 \ifpgfarrowroundjoin j\fi}  
\end{codeexample}
In other words, for each set parameter on which the arrow tip depends,
a specific letter is added to the parameters, making them unique.

The first two of the above keys are a bit special: Reversing and swapping an
arrow tip can be done just by fiddling with the
transformation matrix: a reverse is a ``flip'' along the $y$-axis and
a swap is a flip along the $x$-axis. This is done automatically by
\pgfname.

Nevertheless, you may wish to modify you code in dependence
especially of the |reverse| key: When |\ifpgfarrowreverse| is true,
\pgfname\ will flip the coordinate system along the $y$-axis, will
negate all end values (like line end, tip end, and so on) and will
exchange the meaning of back end and tip end as well as of visual back
end and visual back end. Usually, this is exactly what one need;
\emph{except} that the line end may no longer be appropriate. After
all, the line end should be chosen so that it is completely covered by
the arrow. Now, when the arrow tip is open, a reversed arrow should no
longer have the line end near the old visual back end, but near to the
old visual tip end.

For these reasons, you may need to make the computation of the line
end dependent on whether the arrow is reversed or not. Note that when
you specify a different line end for a reversed arrow tip, the
transformation and inverting of the coordinate system will still be
done, meaning that if |reverse| is true, you need to specify a line
end in the ``old'' coordinate system that is at the position where,
after everything is inverted, it will be at the correct
position. Usually that means that if the |reverse| option is set, you
need to \emph{increase} the line end.


\subsubsection{Inaccessible Options}

There are some options that influence the way an arrow tip looks, but
that you cannot access inside the setup code. Handling these options
lies entirely with \pgfname. If you wish your setup code to handle
these options, you have to setup your own ``parallel'' options.

\begin{itemize}
\item |quick|, |flex|, |flex'|, and |bend| are all handled
  automatically. You can, however, set the |bending mode| to avoid
  bending of your arrow tip.
\item The colors set by |color| and |fill|. You can, however, access
  them indirectly, namely through the current stroke and fill colors.
\item |sep|
\end{itemize}


\subsubsection{Defining New Arrow Keys}
\label{section-arrow-option-cache}

The set of predefined options is already quite long and most arrow
tips will not need more than the predefined options. However,
sometimes an arrow tip may need to introduce a new special-purpose
option. For instance, suppose we wish to introcue a new fictive arrow
key |depth|. In such cases, you must do two things:

\begin{enumerate}
\item
  Introduce a new dimension register or macro that will hold the
  configuration value and which will be accessed by the setup
  code. The could be achieved by saying
\begin{codeexample}[code only]
\newdimen\pgfarrowdepth
\end{codeexample}
\item
  Introduce a new arrow key option |/pgf/arrow keys/depth| that allows
  users to configure the new macro or register.
\end{enumerate}

When an arrow is selected via for instance |foo[depth=5pt]|, the
key--value pairs between the square brackets are executed with the
path prefix |/pgf/arrow keys|. Thus, in the example, our depth key
would get executed. Thus, it is temping to write something like
\begin{codeexample}[code only]
\pgfkeys{/pgf/arrow keys/depth/.code = \pgfmathsetlength{\pgfarrowdepth}{#1}}
\end{codeexample}

Sadly, this will not work. The reason is that the is yet another level
of caching involved when \pgfname\ processes arrow tips: The option
cache! The problem is each time an arrow tip is used, even when the
drawing code of the arrow tip is nicely cached, we still need to
process the options in |foo[length=5pt]| to find out which version in
the cache we would like to access. To make matters worse, |foo| might
be a shorthand that calls other arrow tips, which add more options,
and so on. Unfortunately, executing keys is quite an expensive
operation (\pgfname's key--value parser is powerful, but that power
comes at a price). So, whenever possible, we do \emph{not} want the
key--value parser to be started.

For these reasons, when something like |foo[|\meta{options}|]| is 
encountered inside a shorthand, the \meta{options} are executed only
once. They should now setup the \emph{arrow option cache}, which is
some code that, when executed, should setup the values that the
\meta{options} configure. In our example, the |depth| key should add
something to the arrow option cache that sets |\pgfarrowdepth| to the
given value.

Adding something to the arrow option cache is done using the following
command:

\begin{command}{\pgfarrowsaddtooptions\marg{code}}
  This command should be called by keys with the prefix
  |/pgf/arrow keys| to add code to the arrow option cache. For our
  |depth| key example, we could use this key as follows:
\begin{codeexample}[code only]
\pgfkeys{/pgf/arrow keys/depth/.code=
  \pgfarrowsaddtooptions{\pgfmathsetlength{\pgfarrowdepth}{#1}}
\end{codeexample}
  Actually, this is still not optimal since the expensive
  |\pgfmathsetlength| command is now called each time an arrow tip is
  used with the |depth| option set. The trick is to do the expensive
  operation only once and then store only very quick code in the arrow
  option cache:
\begin{codeexample}[code only]
\pgfkeys{/pgf/arrow keys/depth/.code=
  \pgfmathsetlength{\somedimen}{#1}
  \pgfarrowsaddtooptions{\pgfarrowdepth=\somedimen} % buggy
\end{codeexample}
  The above code will not (yet) work since |\somedimen| will surely
  have a different value when the cache is executed. The trick is to
  use some |\expandafter|s:
\begin{codeexample}[code only]
\pgfkeys{/pgf/arrow keys/depth/.code=
  \pgfmathsetlength{\somedimen}{#1}
  \expandafter\pgfarrowsaddtooptions\expandafter{\expandafter\pgfarrowdepth\expandafter=\the\somedimen}
\end{codeexample}
\end{command}

\begin{command}{\pgfarrowsaddtolateoptions\marg{code}}
  This command works like |\pgfarrowsaddtooptions|, only the
  \meta{code} will be executed ``later'' than the code added by the
  normal version of the command. This is useful for keys that depend
  on the length of an arrow: Keys like |width'| want to define the
  arrow width as a multiple of the arrow length, but when the |width'|
  key is given, the length may not yet have been specified. By making
  the computation of the width a ``late'' option, we ensure that
  |\pgfarrowlength| will have been setup correctly.
\end{command}

If you define a new option that sets a dimensions and if that
dimension should change in accordance to the setting of either
|scale length| or |scale width|, you need to make \pgfname\ ``aware''
of this using the following key:

\begin{command}{\pgfarrowsaddtolengthscalelist\marg{dimension register}}
  Each time an arrow tip is used, the given \meta{dimension register}
  will be multiplied by the |scale length| factor prior to the actual
  drawing. You call this command only once in the preamble somewhere.
\end{command}

\begin{command}{\pgfarrowsaddtowidthscalelist\marg{dimension register}}
  Works like |\pgfarrowsaddtolengthscalelist|, only for width parameters.
\end{command}


\begin{command}{\pgfarrowsthreeparameters\marg{line-width dependent
      size specification}}
  This command is useful for parsing the values given to keys like
  |length| or |width| the expect a dimension followed optionally for
  some numbers. This command converts the \meta{line-width dependent
    size specification}, which may consist of one, two, or three
  numbers, into a triple of three numbers in curly braces, which gets
  stored in the macro |\pgfarrowstheparameters|. Here is an example,
  where |\showvalueofmacro| is used in this example to show the value
  stored in a macro:
  \makeatletter
  \def\showvalueofmacro#1{%
    \texttt{\expandafter\expandafter\expandafter\expandafter\expandafter\expandafter\expandafter\pgfutil@gobble\expandafter\expandafter\expandafter\string\expandafter\csname#1\endcsname}
  }
\begin{codeexample}[]
\pgfarrowsthreeparameters{2pt 1}
\showvalueofmacro\pgfarrowstheparameters 
\end{codeexample}
\end{command}


\begin{command}{\pgfarrowslinewidthdependent\marg{dimension}\marg{line
      width factor}\marg{outer factor}}
  This command take three parameters and does the ``line width
  dependent computation'' described on page~\pageref{length-arrow-key} 
  for the |length| key. The result is returned in |\pgf@x|.

  The idea is that you can setup line-width dependent keys like
  |length| or |width| using code like the following:
\begin{codeexample}[code only]
\pgfkeys{/pgf/arrow keys/depth/.code={%
  \pgfarrowsthreeparameters{#1}%
  \expandafter\pgfarrowsaddtolateoptions\expandafter{%
    \expandafter\pgfarrowslinewidthdependent\pgfarrowstheparameters% compute...
    \pgfarrowdepth\pgf@x% ... and store.
  }%
}    
\end{codeexample}
\end{command}

\begin{command}{\pgfarrowslengthdependent\marg{dimension}\marg{length factor}\marg{dummy}}
  This command take three parameters, of which the last one is
  ignored, and does the ``length dependent computation'' described for
  the |width'| and |inset'| keys. The result is returned in |\pgf@x|.

  You can setup length dependent keys using code like the following:
\begin{codeexample}[code only]
\pgfkeys{/pgf/arrow keys/depth'/.code={%
  \pgfarrowsthreeparameters{#1}%
  \expandafter\pgfarrowsaddtolateoptions\expandafter{%
    \expandafter\pgfarrowslengthdependent\pgfarrowstheparameters% compute...
    \pgfarrowdepth\pgf@x% ... and store.
  }%
}    
\end{codeexample}
\end{command}


%%% Local Variables:
%%% mode: latex
%%% TeX-master: "pgfmanual"
%%% End: