The TikZ and PGF Packages
Manual for version 3.1.10

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.

Defining a Complete New Arrow Tip Kind. The ⟨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:

• • name=⟨name⟩ or name=⟨start name⟩-⟨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 first 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.

• • parameters={⟨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 105.5.)

  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 ⟨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 ⟨list of macros⟩ should be set to \the\pgfarrowlength,\the\pgfarrowwidth. (Actually, the comma is optional, the ⟨list of macros⟩ does not really have to be a list, just something that can be expanded unambiguously.)

  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 pgf thinks that it can reuse some code when, in reality, this code actually depends on a parameter not listed here.

• • setup code={⟨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 ⟨code⟩ gets executed (only this once). The code can now do arbitrarily complicated computations the prepare the later drawing of the arrow tip. Also the ⟨code⟩ must specify the different tip and back ends and the convex hull points. This is done by calling the following macros inside the ⟨code⟩:

  \pgfarrowssettipend{⟨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 ⟨dimension⟩. For example, for our earlier example of the large arrow tip, where the tip end was at 1cm, we would call

  copy
\pgfarrowssettipend{1cm}


  Note that for efficiency reasons, the ⟨dimension⟩ is not passed through \pgfmathsetlength; rather what happens is that \pgf@x=⟨dimension⟩ gets executed. In particular, you can pack further computations into the ⟨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} - \frac 12\mathrm {linewidth}\) as the tip end:

  copy
\pgfarrowssettipend{1cm\advance\pgf@x by-.5\pgflinewidth}


  If the command is not called at all inside the setup code, the tip end is set to 0pt.

  \pgfarrowssetbackend{⟨dimension⟩} ¶

  Works like the command for the tip end, only it sets the back end. In our example we would call

  copy
\pgfarrowssettipend{-3cm}


  Defaults to 0pt.

  \pgfarrowssetlineend{⟨dimension⟩} ¶

  Sets the line end, so in the example we have \pgfarrowssettipend{-1cm}. Default to 0pt.

  \pgfarrowssetvisualbackend{⟨dimension⟩} ¶

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

  \pgfarrowssetvisualtipend{⟨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.

  \pgfarrowshullpoint{⟨x dimension⟩}{⟨y dimension⟩} ¶

  Adds a point to the convex hull of the arrow tip. As for the previous commands, no math parsing is done; instead pgf says \pgf@x=⟨x dimension⟩ and then \pgf@y=⟨y dimension⟩. Thus, both “dimensions” can contain code for advancing and thus modifying \pgf@x and \pgf@y.

  In our example we would write

  copy
\pgfarrowshullpoint{1cm}{0pt}
\pgfarrowshullpoint{-3cm}{2cm}
\pgfarrowshullpoint{-3cm}{-2cm}


  \pgfarrowsupperhullpoint{⟨x dimension⟩}{⟨y dimension⟩} ¶

  This command works like the previous command, only it normally adds 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

  copy
\pgfarrowshullpoint{1cm}{0pt}
\pgfarrowsupperhullpoint{-3cm}{2cm}


  If the ⟨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.

  \pgfarrowssave{⟨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.

  \pgfarrowssavethe{⟨register⟩} ¶

  Works like \pgfarrowssave, only the parameter must be a register and \the⟨register⟩ will be saved. Typically, you will write something like

  copy
\pgfarrowssavethe{\pgfarrowlength}
\pgfarrowssavethe{\pgfarrowwidth}


  To ensure that inside the drawing code the the dimension registers \pgfarrowlength and \pgfarrowwidth are setup with the values they had during the setup.

• • drawing code={⟨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 ⟨code⟩ will we stored in a special cache; but in some cases the ⟨code⟩ gets executed each time the arrow tip is used, so do not assume anything about it. Inside the ⟨code⟩, you have access to all values that were saved in the setup code as well as to the line width.

  The ⟨code⟩ should draw the arrow tip “going right along the \(x\)-axis”. pgf 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 ⟨code⟩:

  • – In the ⟨code⟩ you may 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.

  • – 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.

  • – When the arrow tip code is executed, it is automatically put inside a low-level scope, so nothing will “leak out” from the scope.

  • – The high-level coordinate transformation matrix will be set to the identity matrix when the code is executed for the first time.

• • cache=⟨true or false⟩

  When set to true, which is the default, the ⟨code⟩ will be executed only once for a particular value of parameters and the low-level commands created by the drawing code (using the system layer protocol subsystem, see Section 122) will be cached and reused later on. However, when the drawing code contains “uncacheable” code like a call to \pgftext, caching must be switched off by saying cache=false.

• • bending mode=⟨mode⟩

  This key is important only when the bend option is used with an arrow, see Section 16.3.8 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 ⟨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 108.4.7 for details. Which of these ways is use can be configured by setting ⟨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 or even better results, it is the default. Some arrow tips, however, profit from saying bending mode=polar.

• • defaults=⟨arrow keys⟩

  The ⟨arrow keys⟩ allow you to configure the default values for the parameters on which an arrow tip depends. The ⟨arrow keys⟩ will be executed first before any other arrow tip options are executed, see Section 16.4.5 for the exact sequence. Also see Section 105.5 below for more details on arrow options.

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 example. 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:

We can now use it:

Defining a Shorthand. The \pgfdeclarearrow command can also used to define shorthands. This works as follows:

• • First, you must provide a name just in the same way as when you define a full-flung new arrow tip kind.

• • Second, instead of all of the other options listed above, you just use one more option:

  means=⟨end arrow specification⟩

  This sets up things so that whenever ⟨name⟩ is now used in an arrow specification, it will be replaced by the ⟨end arrow specification⟩ (the problems resulting form the ⟨name⟩ begin used in a start arrow specification are taken care of automatically). See also Section 16.4.4 for details on the order in which options get executed in such cases.

  Note that the ⟨end arrow specification⟩ will be executed immediately to build the so-called arrow option caches, a concept explored in more detail in Section 105.5.4. 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 ⟨end arrow specification⟩ will be evaluated immediately. For instance, when you write

  copy
\pgfdeclarearrow{ name=foo, means = bar[length=2cm+\mydimen] }


  The value 2cm+\mydimen is evaluated immediately. When foo is used later on and \mydimen has changed, this has no effect.

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:

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:

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 \expandafters:

This command works like \pgfarrowsaddtooptions, only the ⟨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.

Each time an arrow tip is used, the given ⟨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.

Works like \pgfarrowsaddtolengthscalelist, only for width parameters.

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 ⟨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:

This command takes three parameters and does the “line width dependent computation” described in section 16.3.1 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:

This command takes 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: