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