Debian Codegraph @

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

raw
1 % !TeX root = tikz-ext-manual.tex
2 % !TeX spellcheck = en_US
3 % Copyright 2022 by Qrrbrbirlbel
4 %
5 % This file may be distributed and/or modified
6 %
7 % 1. under the LaTeX Project Public License and/or
8 % 2. under the GNU Free Documentation License.
9 %
10
11 \section{Nodes}
12 \begin{tikzlibrary}{ext.nodes}
13 This library extends \tikzname's functionalities when it comes to nodes.
14 \inspiration{NodesOnLine-Q, NodesOnCurve-Q}{NodesOnLine-A, NodesOnCurve-A}
15 \end{tikzlibrary}
16
17 \begin{multicols}{2}
18
19 \subsection{Pic as a node}
20 \begin{key}{/\tikzext/pic=\opt{\meta{boolean}} (default true, initially false)}
21 \keycompat{tikz}
22 This key allows one to use a pic where usually only nodes are accepted,
23 for example as a label.
24 \begin{codeexample}[preamble=\usetikzlibrary{ext.nodes, ext.misc}]
25 \begin{tikzpicture}[
26 slsl/.pic={\draw(-2pt, 1.5pt)--( 2pt, .5pt)
27 ( 2pt,-1.5pt)--(-2pt,-.5pt);}]
28 \node[
29 draw, minimum width=3cm, minimum height=1cm,
30 label={[ext/pic ] east:slsl},
31 label={[ext/pic, rotate= 90]north:slsl},
32 label={[ext/pic ] west:slsl},
33 label={[ext/pic, rotate=-90]south:slsl}]{};
34 \end{tikzpicture}
35 \end{codeexample}
36 \end{key}
37
38 \subsection{Nodes on paths}
39 When nodes are placed along paths they don't interrupt
40 the path at that place.
41 The decoration \referenceLibraryandIndexO{markings}
42 and its \referenceKeyandIndexO[/pgf/decoration/]{mark connection node}
43 key can help but only works for straight paths and
44 doesn't play nicely with arrow tips.
45
46 This library provides alternatives.
47 These are separated into straight paths, i.\,e. \referencePathOperationandIndexO{--},
48 and everything else (including any |to path|).
49
50 \subsubsection{Nodes on Lines}
51
52 \begin{stylekey}{/\tikzext/node on line=\opt{\meta{anchor specification}} (default |\{\}|)}
53 \keycompat{tikz}
54 This installs a \referenceKeyandIndexO{to path} that places \emph{one}
55 node along a straight line but connect the line with it.
56
57 This allows a node to be placed \emph{on} a straight line without having to
58 use |fill = white| or similar tricks to make the line disappear
59 beneath the node.
60
61 The optional \meta{anchor specification} allows to specify the
62 anchors to which the line should connect.
63 It allows one or two anchors divided by | and | to be specified.
64 \end{stylekey}
65
66 \begin{stylekey}{/\tikzext/nodes on line}
67 \keycompat{tikz}
68 This is similar to the previous key but allows
69 multiple nodes to be placed on a straight line
70 \emph{if} they are in the correct order (from start to target),
71 don't overlap with each other, the start or the target.
72
73 It allows \emph{no} anchor specification.
74 \end{stylekey}
75
76 \begin{codeexample}[preamble=\usetikzlibrary{ext.nodes, quotes}]
77 \tikz[inner sep=.15em, circle, nodes=draw, sloped]
78 \draw[ultra thick, ->, ext/node on line] (0,0) to["0"] (1,1)
79 to["1"] (2,0)
80 to[ext/nodes on line, "2.1" near start, "2.2", "2.3" near end] (5,1);
81 \end{codeexample}
82 \begin{codeexample}[preamble=\usetikzlibrary{ext.nodes, quotes}]
83 \tikz[inner sep=.15em, nodes=draw]
84 \draw[thick, ->, ext/node on line=west and east]
85 (0,0) to["0"] (1,1)
86 to["1"] (2,0)
87 to["2"] (4,1);
88 \end{codeexample}
89
90 \subsubsection{Nodes on Curves}
91 The following keys need the \referenceLibraryandIndexO{intersections}
92 and the \referenceLibraryandIndexExt{spath3} \cite{spath3}
93 library to be loaded. They will not be automatically
94 loaded by this library.
95
96 Any \referenceKeyandIndexO[/pgf/]{outer sep} will be ignored.
97
98 If you can, use \texttt{fill=\meta{bg color}}
99 instead of these keys, it will be much faster and easier.
100
101 \begin{stylekey}{/\tikzext/nodes on curve=\meta{to path} (default line to)}
102 \keycompat{tikz}
103 Similar to |nodes on line|, this key allows
104 to have nodes on arbitrary paths.
105
106 This is not suitable for paths connecting nodes.
107 \end{stylekey}
108
109 \begin{stylekey}{/\tikzext/nodes on curve'=\meta{to path} (default line to)}
110 \keycompat{tikz}
111 As above but suitable for connecting nodes.
112 \end{stylekey}
113
114 \begin{codeexample}[preamble=\usetikzlibrary{ext.nodes, intersections, quotes, spath3}]
115 \begin{tikzpicture}[ultra thick]
116 \node (A) at (0, 0) {A} ;
117 \node (B) at (3, 0) {B} ;
118 \draw [red, ->, ext/nodes on curve'=bend left]
119 (A) to node[blue,draw]{label} (B)
120 to ["X" {sloped, near start},
121 "Z" {sloped, near end},
122 "Y"] (A);
123 \end{tikzpicture}
124 \end{codeexample}
125 \begin{codeexample}[preamble=\usetikzlibrary{ext.nodes, intersections, quotes, spath3}]
126 \tikz[inner sep=.15em, circle, nodes={draw, green}, sloped, ultra thick]
127 \draw[->, ext/nodes on curve=bend left] (0,0) to["0"] (1,1)
128 to["1"] (2,0)
129 to["2" near start, "3", "4" near end] (4,1)
130 -- ++(down:1);
131 \end{codeexample}
132
133 \newcolumn
134 \subsection{Automatic placement of nodes}
135 The \referenceKeyandIndexO{auto} key allows automatic placement of
136 nodes along a path segment.
137 This library extends this in various ways.
138
139 \subsubsection{More than left and right}
140 Besides |left| and |right| that are provided by \tikzname\
141 the following placement mechanism are provided:
142 \begin{itemize}
143 \item |ext/left| will place a node to the left of the direction of the line,
144 \item |ext/right| will place a node to the right of the direction of the line,
145 \item |ext/above| will place a node towards the direction of the line,
146 \item |ext/below| will place a node against the direction of the line,
147 \item |ext/west| will place a node towards the left side of the paper,
148 \item |ext/east| will place a node towards the right side of the paper,
149 \item |ext/north| will place a node towards the upper side of the paper and
150 \item |ext/south| will place a node twoards the lower side of the paper.
151 \end{itemize}
152 The placement mechanisms |ext/left| and |ext/right| are like the original
153 |left| and |right| mechanisms but don't swap sides when \referenceKeyandIndexO{sloped}
154 is used.
155
156 Certain cases exist for |ext/west|, |ext/east|, |ext/north| and |ext/south| placements
157 where it is not clear how a node should be placed.
158 These cases and their behavior can be seen in figure~\ref{fig:autoplacements}.
159 %\begin{codeexample}[preamble=\usetikzlibrary{ext.nodes, ext.arrows}]
160 \begin{figure*}
161 \begin{center}
162 \small
163 \newcommand*\tikzauto[3]{%
164 \path[{ext_Centered Circle[black]}-Latex, auto=ext/#1, passive/.style={gray, nodes=gray, behind path}]
165 (0,0) edge[#2] node {#1} (left:2) edge[#2] node {#1} (right:2)
166 edge[#3] node {#1} ( up:2) edge[#3] node {#1} ( down:2);}
167 \tikz[x=+.75cm,y=+.75cm]\matrix[nodes=draw, row sep=5mm, column sep=5mm, ampersand replacement=\&]{
168 \tikzauto{west}{}{passive} \& \tikzauto{east}{}{passive} \\
169 \tikzauto{north}{passive}{} \& \tikzauto{south}{passive}{} \\};
170 \end{center}
171 \caption{Behavior of \texttt{ext/est}, \texttt{ext/east}, \texttt{ext/north} and \texttt{ext/south} in certain cases}
172 \label{fig:autoplacements}
173 \end{figure*}
174 %\end{codeexample}
175
176 \subsubsection{Offset}
177 Nodes are usually placed with their border (including any |outer sep|)
178 on the line.
179 With the following option, a node will be shifted a certain offset distance.
180
181 \begin{key}{/\tikzext/auto with offset=\opt{\meta{true or false}} (default true)}
182 This key activates the offset function.
183 \end{key}
184 \begin{key}{/\tikzext/auto offset (initially 1cm)}
185 The offset distance itself.
186 \end{key}
187
188 For the \referenceDecorationandIndexO{brace} decoration,
189 the following keys are provided which needs the
190 \referenceLibraryandIndexO{decorations.pathreplacing} loaded before they
191 can be used.
192 \begin{key}{/\tikzext/nodes/install auto offset for brace decoration=\opt{\meta{distance}} (default 0pt)}
193 This key installs the necessary customizations
194 for the \referenceKeyandIndexO[/pgf/decoration/]{raise} key
195 so that the given value is available as an offset.
196
197 It also makes available the following keys.
198 \begin{key}{/\tikzext/auto offset for brace decoration}
199 This sets \referenceKeyandIndex[/\tikzext/]{auto offset} to
200 \texttt{\textbackslash pgfdecorationsegmentamplitude+
201 (\textbackslash pgfkeysvalueof\{/pgf/decoration/raise\})}.
202 \end{key}
203 %\columnbreak
204 \begin{stylekey}{/\tikzext/every brace node}
205 Using this key on a node along a path that's decorated by the |brace| decoration
206 will offset the node so that it will be placed at the tip of the brace.
207 \end{stylekey}
208 \end{key}
209
210 \paragraph{Implementation note:}
211 This redefines the keys \referenceKeyandIndexO{auto},
212 \referenceKeyandIndexO{swap} and \referenceKeyandIndexO{sloped}.
213 One can install custom auto placement rules by using the following key.
214 \begin{key}{/\tikzext/nodes/install auto=\marg{left}\marg{right}}
215 This key defines \texttt{/tikz/auto/\meta{left}} which activates the auto placement
216 and installs the appropriate placement function.
217 Further more, the key \texttt{/tikz/swap/\meta{left}} will be defined
218 to active the \meta{right} placement function.
219
220 The key |/tikz/swap| has been defined to apply \texttt{/tikz/swap/\meta{dir}}
221 where \meta{dir} is the current placement function.
222 \end{key}
223 \subsubsection{Precise placement}
224 The default behavior of the |auto| placement mechanism is
225 to snap to one of the eight compass directions.
226 \begin{key}{/\tikzext/precise auto angle=\opt{\meta{true or false}} (default true)}
227 With this option set to |true|, the |auto| placement won't snap
228 to one of the eight compass directions.
229
230 This key disables the \referenceKeyandIndexO{sloped} option
231 which in turn will disable this option.
232 \end{key}
233 \end{multicols}