| 1 |
% !TeX TS-program = lualatex |
| 2 |
% !TeX spellcheck = en_US |
| 3 |
% !TeX root = tikz-ext-manual.tex |
| 4 |
% Copyright 2023 by Qrrbrbirlbel |
| 5 |
% |
| 6 |
% This file may be distributed and/or modified |
| 7 |
% |
| 8 |
% 1. under the LaTeX Project Public License and/or |
| 9 |
% 2. under the GNU Free Documentation License. |
| 10 |
% |
| 11 |
|
| 12 |
\section{Arrow Pics} |
| 13 |
\label{tikzlibrary:arrows} |
| 14 |
\tikzset{external/export/.try=false}% |
| 15 |
\begin{tikzlibrary}{ext.arrows-plus} |
| 16 |
This library defines pics and keys |
| 17 |
that can be used to place (bended) arrow tips on paths. |
| 18 |
\end{tikzlibrary} |
| 19 |
|
| 20 |
\begin{multicols}{2} |
| 21 |
The \referenceDecorationandIndexO{markings} decoration |
| 22 |
already provides the functionality to place arrow tips along the path. |
| 23 |
The pics and keys provided by this library serve as an alternative. |
| 24 |
|
| 25 |
Many of the pics and keys share various keys that specify |
| 26 |
where and how the arrow tips are placed. |
| 27 |
\begin{key}{/\tikzext/pos <=\meta{value} (initially 0.0)} |
| 28 |
If the pic type supports it and a start arrow tip sequence is provided |
| 29 |
this specifies the position of that sequence. |
| 30 |
\end{key} |
| 31 |
\begin{key}{/\tikzext/pos >=\meta{value} (initially 0.5)} |
| 32 |
This is an alias for \referenceKeyandIndex{pos}, |
| 33 |
if an end arrow tip sequence is provided, it is placed at this position. |
| 34 |
\end{key} |
| 35 |
\begin{key}{/\tikzext/pos < angle=\meta{angle}} |
| 36 |
For tips along an arc the angle along that arc can be specified for the start tip sequence. |
| 37 |
\end{key} |
| 38 |
\begin{key}{/\tikzext/pos > angle=\meta{angle}} |
| 39 |
For tips along an arc the angle along that arc can be specified for the end tip sequence. |
| 40 |
\end{key} |
| 41 |
\begin{key}{/\tikzext/arrow shift mode=\meta{shift mode} (initially total length)} |
| 42 |
This key is used to set the \meta{shift mode} for the arrow tip. |
| 43 |
It can be one of the following. |
| 44 |
\begin{description} |
| 45 |
\item[|arrow shift mode|=\declare{|off|}] |
| 46 |
|
| 47 |
This disables the shifting. |
| 48 |
\item[|arrow shift mode|=\declare{|total length|}] |
| 49 |
|
| 50 |
The total length of the whole arrow tip sequence will be used. |
| 51 |
\item[|arrow shift mode|=\declare{|total|}] |
| 52 |
|
| 53 |
This is an alias for |total length|. |
| 54 |
\item[|arrow shift mode|=\declare{|length until line end|}] |
| 55 |
|
| 56 |
The length of the whole arrow tip until the line end will be used -- |
| 57 |
as reported by \pgfname\ which might not always be the expected one. |
| 58 |
\item[|arrow shift mode|=\declare{|line end|}] |
| 59 |
|
| 60 |
This is an alias for |length until line end|. |
| 61 |
\end{description} |
| 62 |
\begin{codeexample}[preamble=\usetikzlibrary{ext.arrows-plus}] |
| 63 |
\begin{tikzpicture}[>={Straight Barb[color=red]}, ultra thick] |
| 64 |
\ttfamily |
| 65 |
\foreach[count=\y] \shiftmode in {off, total length, length until line end} |
| 66 |
\draw[ext/arrow shift mode=\shiftmode] (0, -\y ) |
| 67 |
-- pic {ext/arrow=>} ++(right:2) |
| 68 |
-- pic {ext/arrow=>.>>} ++(right:2) node[below right] {\shiftmode} |
| 69 |
++(down:.4) -- pic {ext/arrow=>.>>} ++( left:2) |
| 70 |
-- pic {ext/arrow=>} ++( left:2); |
| 71 |
\draw[thin, gray] (1,-.75) -- +(down:3) (3,-.75) -- +(down:3); |
| 72 |
\end{tikzpicture} |
| 73 |
\end{codeexample} |
| 74 |
|
| 75 |
For single arrow tips it might be better to use the Centered arrow tip variants |
| 76 |
of the \referenceLibraryandIndex{ext.arrows} library (see sec~\ref{pgflibrary:arrows}) |
| 77 |
and disabled |arrow shift mode|. |
| 78 |
\end{key} |
| 79 |
|
| 80 |
When an arrow tip sequence is to be drawn depending on the shift mode |
| 81 |
its total length or its length until the line end will be determined |
| 82 |
and multiplied with the |arrow shift factor|. |
| 83 |
The result of this evaluation is used to shift the arrow tip sequence |
| 84 |
in the tip's direction. |
| 85 |
|
| 86 |
\begin{key}{/\tikzext/arrow shift factor start=\meta{value} (initially 0.5)} |
| 87 |
This determines the shift factor for the start tip sequence. |
| 88 |
|
| 89 |
The default value is probably good for most cases. |
| 90 |
\end{key} |
| 91 |
\begin{key}{/\tikzext/arrow shift factor end=\meta{value} (initially 0.5)} |
| 92 |
This determines the shift factor for the start tip sequence. |
| 93 |
|
| 94 |
The default value is probably good for most cases. |
| 95 |
\end{key} |
| 96 |
\begin{key}{/\tikzext/arrow shift factor=\meta{value}} |
| 97 |
This sets both the start and end shift factor. |
| 98 |
\end{key} |
| 99 |
\subsection{Arrow pic types} |
| 100 |
|
| 101 |
This library provides the following pics: |
| 102 |
\begin{description} |
| 103 |
\item[|ext/arrow|] |
| 104 |
This is the simplest implementation to place an arrow tip along a path. |
| 105 |
It uses the current timer that is also used to place nodes. |
| 106 |
|
| 107 |
It can be used without any adjustment for every path operation that provides such a timer. |
| 108 |
These do \emph{not} include |
| 109 |
\referencePathOperationandIndexO{circle}, |
| 110 |
\referencePathOperationandIndexO{ellipse}, |
| 111 |
\referencePathOperationandIndexO{plot} and |
| 112 |
\referencePathOperationandIndexO{grid}. |
| 113 |
For \referencePathOperationandIndexO{rectangle}, |
| 114 |
\referencePathOperationandIndexO{parabola}, |
| 115 |
\referencePathOperationandIndexO{sin} and |
| 116 |
\referencePathOperationandIndexO{cos}, |
| 117 |
the \referenceLibraryandIndex{ext.paths.timer} library is recommended or even necessary |
| 118 |
(see section~\ref{library:timer}). |
| 119 |
|
| 120 |
The arrow tips will never be bended. For this the following pic types |
| 121 |
or the \referenceKeyandIndex[/\tikzext/]{arc arrows} key will be necessary. |
| 122 |
|
| 123 |
Due to \cite{PgfIssueSloped} with an active transformation, |
| 124 |
the arrow tips won't be placed correctly in many cases. |
| 125 |
For this \emph{and} bended arrow tips the following pics are necessary. |
| 126 |
|
| 127 |
\item[|ext/softpath arrows|] |
| 128 |
This pic type places a possible bended arrow tip on the last segment of the path. |
| 129 |
|
| 130 |
% For the path operators \referencePathOperationandIndexO{--}, |
| 131 |
% {\catcode`\|=12 \referencePathOperationandIndexO{|-} |
| 132 |
% and \referencePathOperationandIndexO{-|}} |
| 133 |
% this works even with a non-identity transformation. |
| 134 |
% If possible, the current timer will be used to take more segments into account so |
| 135 |
% that the arrow tip can be placed along the recent path operation. |
| 136 |
|
| 137 |
This won't work for \referencePathOperationandIndexO{arc}s, |
| 138 |
for this the \referenceKeyandIndex[/\tikzext/]{arc arrows} key will be necessary. |
| 139 |
|
| 140 |
This pic type can place two tip specification, |
| 141 |
one at |pos >| and one at |pos <| in the reversed direction. |
| 142 |
|
| 143 |
\item[|ext/softpath arrow|] |
| 144 |
This is an alias for |softpath arrows| with an empty start arrow tip specification. |
| 145 |
|
| 146 |
\end{description} |
| 147 |
\begin{pictype}{ext/arrow}{\opt{|=|\meta{\rmfamily arrow tip specification}}} |
| 148 |
This pic draws the given \meta{arrow tip specification} |
| 149 |
(defaults to the end tip specification of the path). |
| 150 |
|
| 151 |
|
| 152 |
This obviously is best used as a pic along a path segment that supports it. |
| 153 |
It \emph{does not} support bended arrow tips. |
| 154 |
\begin{codeexample}[preamble=\usetikzlibrary{arrows.meta, bending, ext.arrows-plus}] |
| 155 |
\begin{tikzpicture}[>={Triangle[color=red]}, arrows={[bend]}, ultra thick] |
| 156 |
\ttfamily |
| 157 |
\foreach[count=\y] \shiftmode in {off, total length, length until line end} |
| 158 |
\draw[ext/arrow shift mode=\shiftmode] (0, -\y ) |
| 159 |
to[bend left] pic {ext/arrow=>} ++(right:2) |
| 160 |
to[bend left] pic {ext/arrow=>>.>} ++(right:2) |
| 161 |
node[below right] {\shiftmode} |
| 162 |
++(down:.4) to[bend right] pic {ext/arrow=>>.>} ++( left:2) |
| 163 |
to[bend right] pic {ext/arrow=>} ++( left:2); |
| 164 |
\draw[thin, gray] (1,-.5) -- +(down:3) (3,-.5) -- +(down:3); |
| 165 |
\end{tikzpicture} |
| 166 |
\end{codeexample} |
| 167 |
\end{pictype} |
| 168 |
|
| 169 |
\begin{pictype}{ext/softpath arrows}{\opt{|=|\meta{\rmfamily start tip specification}|-|\meta{\rmfamily end tip specification}}} |
| 170 |
This pic draws the given arrow tip specification |
| 171 |
(defaults to the already present tip specification of the path) |
| 172 |
along the previous path segment (a curve or a line). |
| 173 |
It supports the |pos <| key. |
| 174 |
|
| 175 |
\paragraph{Note:} For arcs with an angle greater than 90${}^\circ$ |
| 176 |
this will not work as expected. Use the |/tikz/ext/arc arrows| key instead. |
| 177 |
\end{pictype} |
| 178 |
\begin{pictype}{ext/softpath arrow}{\opt{|=|\meta{\rmfamily end tip specification}}} |
| 179 |
This pic type is an alias for |softpath arrows = -|\meta{end tip specification}. |
| 180 |
|
| 181 |
\begin{codeexample}[preamble=\usetikzlibrary{arrows.meta, bending, ext.arrows-plus}] |
| 182 |
\begin{tikzpicture}[>={Triangle[color=red]}, arrows={[bend]}, ultra thick] |
| 183 |
\ttfamily |
| 184 |
\foreach[count=\y] \shiftmode in {off, total length, length until line end} |
| 185 |
\draw[ext/arrow shift mode=\shiftmode] (0, -\y ) |
| 186 |
to[bend left] pic {ext/softpath arrow=>} ++(right:2) |
| 187 |
to[bend left] pic {ext/softpath arrow=>>.>} ++(right:2) |
| 188 |
node[below right] {\shiftmode} |
| 189 |
++(down:.4) to[bend right] pic {ext/softpath arrow=>>.>} ++( left:2) |
| 190 |
to[bend right] pic {ext/softpath arrow=>} ++( left:2); |
| 191 |
\draw[thin, gray] (1,-.5) -- +(down:3) (3,-.5) -- +(down:3); |
| 192 |
\end{tikzpicture} |
| 193 |
\end{codeexample} |
| 194 |
\end{pictype} |
| 195 |
|
| 196 |
\subsection{Arrow keys} |
| 197 |
The last pic type |softpath arrows| is also available as a key |
| 198 |
which is the preferred version. |
| 199 |
\begin{key}{/\tikzext/softpath arrows=\opt{\meta{options}} (default ->)} |
| 200 |
This key adds arrow tips to the previous path segment (a curve or a line). |
| 201 |
|
| 202 |
\begin{stylekey}{/\tikzext/every softpath arrows (initially \{\})} |
| 203 |
This style will be applied for every instance of |softpath arrows| (key version, not the pic). |
| 204 |
It also sets up forwarding |
| 205 |
\begin{itemize} |
| 206 |
\item from |/tikz/pos >| to |/tikz/ext/pos >| and |
| 207 |
\item from |/tikz/pos <| to |/tikz/ext/pos >|. |
| 208 |
\end{itemize} |
| 209 |
\end{stylekey} |
| 210 |
\end{key} |
| 211 |
|
| 212 |
For |arc|s the following key needs to be used directly after the |arc| path operation. |
| 213 |
\begin{key}{/\tikzext/arc arrows=\opt{\meta{options}} (default ->)} |
| 214 |
This key adds arrow tips to the previous arc segment. |
| 215 |
\begin{stylekey}{/\tikzext/every arc arrows (initially \{\})} |
| 216 |
This style will be applied for every instance of |arc arrows|. |
| 217 |
It also sets up forwarding |
| 218 |
\begin{itemize} |
| 219 |
\item from |/tikz/pos >| to |/tikz/ext/pos >|, |
| 220 |
\item from |/tikz/pos <| to |/tikz/ext/pos >| as well as |
| 221 |
\item from |/tikz/pos > angle| to |/tikz/ext/pos > angle| and |
| 222 |
\item from |/tikz/pos < angle| to |/tikz/ext/pos < angle|. |
| 223 |
\end{itemize} |
| 224 |
\begin{codeexample}[preamble=\usetikzlibrary{arrows.meta, ext.arrows-plus}] |
| 225 |
\begin{tikzpicture} |
| 226 |
\draw (0,0) -- (135:1) |
| 227 |
(0,0) -- (225:1) [help lines]; |
| 228 |
\draw[arrows={[bend] Stealth-Latex}] |
| 229 |
(120:1) arc[start angle=120, |
| 230 |
end angle=240, radius=1] |
| 231 |
[ext/arc arrows={pos < angle=135, |
| 232 |
pos > angle=225, |
| 233 |
arrows=[red]}]; |
| 234 |
\end{tikzpicture} |
| 235 |
\end{codeexample} |
| 236 |
\end{stylekey} |
| 237 |
|
| 238 |
|
| 239 |
\paragraph{Tip:} |
| 240 |
Use an arc with the full 360${}^\circ$ to place bended arrow tips along a circle or an ellipse. |
| 241 |
\end{key} |
| 242 |
\subsection{Shifted and bended arrows for the \texttt{decorations.markings} library} |
| 243 |
Many paths are not properly accessible by the previous methods. |
| 244 |
If this library is loaded \emph{after} |
| 245 |
the \referenceLibraryandIndexO{decorations.markings} library, |
| 246 |
both the |\arrow| and |
| 247 |
the |\arrowreversed| macros are enhanced. |
| 248 |
|
| 249 |
\begin{command}{\arrow\opt{|**|\oarg{options}}\marg{arrow end tip}} |
| 250 |
This macro works the same as before but the one-starred version |
| 251 |
applies the shifting as specified |
| 252 |
by |arrow shift mode| and |arrow shift factor| |
| 253 |
where as the two-starred version also bends the arrow tip. |
| 254 |
\end{command} |
| 255 |
\begin{command}{\arrowreversed\opt{|**|\oarg{options}}\marg{arrow end tip}} |
| 256 |
As above, only the arrow end tip is flipped and points in the other direction. |
| 257 |
\end{command} |
| 258 |
\begin{codeexample}[width=2cm,preamble=\usetikzlibrary{bending, decorations.markings, ext.arrows-plus}] |
| 259 |
\tikzset{ |
| 260 |
arr/.style={ |
| 261 |
postaction=decorate, |
| 262 |
decoration={ |
| 263 |
name=markings, |
| 264 |
mark={between positions .25 and 1 step .25 with |
| 265 |
\arrow#1[red]{> _ < _ >}}}}} |
| 266 |
\tikz[y=1.5cm, >=Stealth, arrows={[round]}, nodes={circle, draw}] |
| 267 |
\path node[arr= ]{Ti\emph kZ} % \arrow |
| 268 |
(0,-1) node[arr=* ]{Ti\emph kZ} % \arrow* |
| 269 |
(0,-2) node[arr=**]{Ti\emph kZ} % \arrow** |
| 270 |
; |
| 271 |
\end{codeexample} |
| 272 |
\end{multicols} |
| 273 |
\endinput |