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