Debian Codegraph @

texmf-dist/doc/latex/tikz-ext/tikz-ext-manual-en-library-arrows-plus.tex

raw
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