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