% !TeX root = tikz-ext-manual.tex
% !TeX spellcheck = en_US
% Copyright 2022 by Qrrbrbirlbel
%
% This file may be distributed and/or modified
%
% 1. under the LaTeX Project Public License and/or
% 2. under the GNU Free Documentation License.
%

\section{Nodes}
\begin{tikzlibrary}{ext.nodes}
This library extends \tikzname's functionalities when it comes to nodes.
\inspiration{NodesOnLine-Q, NodesOnCurve-Q}{NodesOnLine-A, NodesOnCurve-A}
\end{tikzlibrary}

\begin{multicols}{2}

\subsection{Pic as a node}
\begin{key}{/\tikzext/pic=\opt{\meta{boolean}} (default true, initially false)}
\keycompat{tikz}
This key allows one to use a pic where usually only nodes are accepted,
for example as a label.
\begin{codeexample}[preamble=\usetikzlibrary{ext.nodes, ext.misc}]
\begin{tikzpicture}[
 slsl/.pic={\draw(-2pt, 1.5pt)--( 2pt, .5pt)
                 ( 2pt,-1.5pt)--(-2pt,-.5pt);}]
\node[
 draw, minimum width=3cm, minimum height=1cm,
 label={[ext/pic            ] east:slsl},
 label={[ext/pic, rotate= 90]north:slsl},
 label={[ext/pic            ] west:slsl},
 label={[ext/pic, rotate=-90]south:slsl}]{};
\end{tikzpicture}
\end{codeexample}
\end{key}

\subsection{Nodes on paths}
When nodes are placed along paths they don't interrupt
the path at that place.
The decoration \referenceLibraryandIndexO{markings}
and its \referenceKeyandIndexO[/pgf/decoration/]{mark connection node}
key can help but only works for straight paths and
doesn't play nicely with arrow tips.

This library provides alternatives.
These are separated into straight paths, i.\,e. \referencePathOperationandIndexO{--},
and everything else (including any |to path|).

\subsubsection{Nodes on Lines}

\begin{stylekey}{/\tikzext/node on line=\opt{\meta{anchor specification}} (default |\{\}|)}
\keycompat{tikz}
This installs a \referenceKeyandIndexO{to path} that places \emph{one}
node along a straight line but connect the line with it.

This allows a node to be placed \emph{on} a straight line without having to
use |fill = white| or similar tricks to make the line disappear
beneath the node.

The optional \meta{anchor specification} allows to specify the
anchors to which the line should connect.
It allows one or two anchors divided by | and | to be specified.
\end{stylekey}

\begin{stylekey}{/\tikzext/nodes on line}
\keycompat{tikz}
This is similar to the previous key but allows
multiple nodes to be placed on a straight line
\emph{if} they are in the correct order (from start to target),
don't overlap with each other, the start or the target.

It allows \emph{no} anchor specification.
\end{stylekey}

\begin{codeexample}[preamble=\usetikzlibrary{ext.nodes, quotes}]
\tikz[inner sep=.15em, circle, nodes=draw, sloped]
 \draw[ultra thick, ->, ext/node on line] (0,0) to["0"] (1,1)
                                                to["1"] (2,0)
   to[ext/nodes on line, "2.1" near start, "2.2", "2.3" near end] (5,1);
\end{codeexample}
\begin{codeexample}[preamble=\usetikzlibrary{ext.nodes, quotes}]
\tikz[inner sep=.15em, nodes=draw]
 \draw[thick, ->, ext/node on line=west and east]
    (0,0) to["0"] (1,1)
          to["1"] (2,0)
          to["2"] (4,1);
\end{codeexample}

\subsubsection{Nodes on Curves}
The following keys need the \referenceLibraryandIndexO{intersections}
and the \referenceLibraryandIndexExt{spath3} \cite{spath3}
library to be loaded. They will not be automatically
loaded by this library.

Any \referenceKeyandIndexO[/pgf/]{outer sep} will be ignored.

If you can, use \texttt{fill=\meta{bg color}}
instead of these keys, it will be much faster and easier.

\begin{stylekey}{/\tikzext/nodes on curve=\meta{to path} (default line to)}
\keycompat{tikz}
Similar to |nodes on line|, this key allows
to have nodes on arbitrary paths.

This is not suitable for paths connecting nodes.
\end{stylekey}

\begin{stylekey}{/\tikzext/nodes on curve'=\meta{to path} (default line to)}
\keycompat{tikz}
As above but suitable for connecting nodes.
\end{stylekey}

\begin{codeexample}[preamble=\usetikzlibrary{ext.nodes, intersections, quotes, spath3}]
\begin{tikzpicture}[ultra thick]
 \node (A) at (0, 0) {A} ;
 \node (B) at (3, 0) {B} ;
 \draw [red, ->, ext/nodes on curve'=bend left]
   (A) to node[blue,draw]{label} (B)
       to ["X" {sloped, near start},
           "Z" {sloped, near end},
           "Y"] (A);
\end{tikzpicture}
\end{codeexample}
\begin{codeexample}[preamble=\usetikzlibrary{ext.nodes, intersections, quotes, spath3}]
\tikz[inner sep=.15em, circle, nodes={draw, green}, sloped, ultra thick]
 \draw[->, ext/nodes on curve=bend left] (0,0) to["0"] (1,1)
                                               to["1"] (2,0)
                 to["2" near start, "3", "4" near end] (4,1)
                                               -- ++(down:1);
\end{codeexample}

\newcolumn
\subsection{Automatic placement of nodes}
The \referenceKeyandIndexO{auto} key allows automatic placement of
nodes along a path segment.
This library extends this in various ways.

\subsubsection{More than left and right}
Besides |left| and |right| that are provided by \tikzname\
the following placement mechanism are provided:
\begin{itemize}
\item |ext/left| will place a node to the left of the direction of the line,
\item |ext/right| will place a node to the right of the direction of the line,
\item |ext/above| will place a node towards the direction of the line,
\item |ext/below| will place a node against the direction of the line,
\item |ext/west| will place a node towards the left side of the paper,
\item |ext/east| will place a node towards the right side of the paper,
\item |ext/north| will place a node towards the upper side of the paper and
\item |ext/south| will place a node twoards the lower side of the paper.
\end{itemize}
The placement mechanisms |ext/left| and |ext/right| are like the original
|left| and |right| mechanisms but don't swap sides when \referenceKeyandIndexO{sloped}
is used.

Certain cases exist for |ext/west|, |ext/east|, |ext/north| and |ext/south| placements
where it is not clear how a node should be placed.
These cases and their behavior can be seen in figure~\ref{fig:autoplacements}.
%\begin{codeexample}[preamble=\usetikzlibrary{ext.nodes, ext.arrows}]
\begin{figure*}
\begin{center}
\small
\newcommand*\tikzauto[3]{%
 \path[{ext_Centered Circle[black]}-Latex, auto=ext/#1, passive/.style={gray, nodes=gray, behind path}]
   (0,0) edge[#2] node {#1} (left:2) edge[#2] node {#1} (right:2)
         edge[#3] node {#1} (  up:2) edge[#3] node {#1} ( down:2);}
\tikz[x=+.75cm,y=+.75cm]\matrix[nodes=draw, row sep=5mm, column sep=5mm, ampersand replacement=\&]{
 \tikzauto{west}{}{passive}  \& \tikzauto{east}{}{passive}  \\
 \tikzauto{north}{passive}{} \& \tikzauto{south}{passive}{} \\};
\end{center}
\caption{Behavior of \texttt{ext/est}, \texttt{ext/east}, \texttt{ext/north} and \texttt{ext/south} in certain cases}
\label{fig:autoplacements}
\end{figure*}
%\end{codeexample}

\subsubsection{Offset}
Nodes are usually placed with their border (including any |outer sep|)
on the line.
With the following option, a node will be shifted a certain offset distance.

\begin{key}{/\tikzext/auto with offset=\opt{\meta{true or false}} (default true)}
 This key activates the offset function.
\end{key}
\begin{key}{/\tikzext/auto offset (initially 1cm)}
The offset distance itself.
\end{key}

For the \referenceDecorationandIndexO{brace} decoration,
the following keys are provided which needs the
\referenceLibraryandIndexO{decorations.pathreplacing} loaded before they
can be used.
\begin{key}{/\tikzext/nodes/install auto offset for brace decoration=\opt{\meta{distance}} (default 0pt)}
This key installs the necessary customizations
for the \referenceKeyandIndexO[/pgf/decoration/]{raise} key
so that the given value is available as an offset.

It also makes available the following keys.
\begin{key}{/\tikzext/auto offset for brace decoration}
This sets \referenceKeyandIndex[/\tikzext/]{auto offset} to
\texttt{\textbackslash pgfdecorationsegmentamplitude+
 (\textbackslash pgfkeysvalueof\{/pgf/decoration/raise\})}.
\end{key}
%\columnbreak
\begin{stylekey}{/\tikzext/every brace node}
Using this key on a node along a path that's decorated by the |brace| decoration
will offset the node so that it will be placed at the tip of the brace.
\end{stylekey}
\end{key}

\paragraph{Implementation note:}
This redefines the keys \referenceKeyandIndexO{auto},
\referenceKeyandIndexO{swap} and \referenceKeyandIndexO{sloped}.
One can install custom auto placement rules by using the following key.
\begin{key}{/\tikzext/nodes/install auto=\marg{left}\marg{right}}
 This key defines \texttt{/tikz/auto/\meta{left}} which activates the auto placement
 and installs the appropriate placement function.
 Further more, the key \texttt{/tikz/swap/\meta{left}} will be defined
 to active the \meta{right} placement function.

 The key |/tikz/swap| has been defined to apply \texttt{/tikz/swap/\meta{dir}}
 where \meta{dir} is the current placement function.
\end{key}
\subsubsection{Precise placement}
The default behavior of the |auto| placement mechanism is
to snap to one of the eight compass directions.
\begin{key}{/\tikzext/precise auto angle=\opt{\meta{true or false}} (default true)}
With this option set to |true|, the |auto| placement won't snap
to one of the eight compass directions.

This key disables the \referenceKeyandIndexO{sloped} option
which in turn will disable this option.
\end{key}
\end{multicols}

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.