% !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{More Horizontal and Vertical Lines}
\label{library:paths.ortho}

\begin{tikzlibrary}{ext.paths.ortho}
  This library adds new path specifications \verb!|-|!, \verb!-|-! as well as
  |r-ud|, |r-du|, |r-lr| and |r-rl|.
\end{tikzlibrary}

\subsection{Zig-Zag}
Similar to the path operations \verb!|-! and \verb!-|! this library adds\indexPathOperationO{\protect\pgfmanualbar-}\indexPathOperationO{-\protect\pgfmanualbar}
the path operations \verb!|-|! and \verb!-|-!.
{\catcode`\|=12
\begin{pathoperation}[noindex]{|-|}{\opt{\oarg{options}}\meta{coordinate or cycle}}
    \index{---1@\protect\texttt{\protect\pgfmanualbar-\protect\pgfmanualbar} path operation}%
    \index{Path operations!---1@\protect\texttt{\protect\pgfmanualbar-\protect\pgfmanualbar}}%
    \pgfmanualpdflabel[\catcode`\|=12 ]{|-|}{}%
    This operation means ``first vertical, then horizontal and then vertical again''.
\end{pathoperation}
\begin{pathoperation}[noindex]{-|-}{\opt{\oarg{options}}\meta{coordinate or cycle}}
    \index{--1@\protect\texttt{-\protect\pgfmanualbar-} path operation}%
    \index{Path operations!--1@\protect\texttt{-\protect\pgfmanualbar-}}%
    \pgfmanualpdflabel[\catcode`\|=12 ]{-|-}{}%
    This operation means ``first horizontal, then vertical and then horizontal again''.
\end{pathoperation}
}
\begin{key}{/tikz/ortho/ratio=\meta{ratio} (initially 0.5)}
  This sets the ratio for the middle part of the Zig-Zag connection.
  
  For values $\meta{ratio} < 0$ and $\meta{ratio} > 1$ the Zig-Zag lines will
  look more like Zig-Zig lines.
\begin{codeexample}[preamble=\usetikzlibrary{paths.ortho}]
\begin{tikzpicture}[very thick, rounded corners]
\draw[help lines] (-.25, -1.25) grid (2.25, 1.25);
\draw (0, 0) -|-            (2, 1) --
      (2, 0) -|-[ratio=.25] (0,-1) -- cycle;
\end{tikzpicture}
\end{codeexample}
\end{key}
%TODO: hvvh/distance needs fixing, maybe?
\begin{key}{/tikz/ortho/distance=\meta{distance}}
  This sets the distance between the start point
  and the middle part of the Zig-Zag connection.
  
  For values $\meta{distance} < 0$ the distance will be used for the target coordinate.
\begin{codeexample}[width=8cm,preamble=\usetikzlibrary{ext.paths.ortho}]
\begin{tikzpicture}[very thick,-latex]
\draw[help lines,-] (-.25, -.25) grid (5.25, 3.25);
\draw (0, 0) -|-[distance= .5cm] ++(2, 1);
\draw (0, 2) -|-[distance=-.5cm] ++(2, 1);

\tikzset{xshift=3cm}
\draw (2, 1) -|-[distance= .5cm] ++(-2, -1);
\draw (2, 3) -|-[distance=-.5cm] ++(-2, -1);
\end{tikzpicture}
\end{codeexample}
\end{key}
\begin{key}{/tikz/ortho/from center=\opt{\meta{true or false}} (default true)}
  When nodes get connected the placement of the middle part of the Zig-Zag
  and the Zig-Zig (see below) connections will be calculated from the border
  of these nodes.
  The middle part of the connections can be calculated from the nodes' center
  if this key is set to |true|.
\end{key}

New timers are setup for both the Zig-Zag and the Zig-Zig connections,
these can be configured through the following keys.
\begin{codeexample}[width=8cm,preamble=\usetikzlibrary{paths.ortho}]
\tikz \draw (0,0) -|- (2,3) 
  foreach \p in {0.0, 0.25, 0.5, 0.75, 1.0}{
    node [pos=\p] {\p}};
\end{codeexample}
\begin{key}{/tikz/ortho/spacing=\meta{number} (initially 4)}
  Unless $\meta{number} = 0$ is set
  \begin{itemize}
  \item |pos = 0| will be at the start,\indexKeyO{pos}
  \item |pos = 1| will be at the end,
  \item |pos = |$\frac{1}{\meta{number}}$ will be at the first kink,
  \item |pos = |$\frac{\meta{number}-1}{\meta{number}}$ will be at the second kink and
  \item |pos = .5| will be in the middle of the middle part of the connection.
  \end{itemize}
  
  If $\meta{number} = 0$ then
  \begin{itemize}
  \item |pos = -1| will be at the start,
  \item |pos = 2| will be at the end,
  \item |pos = 0| will be at the first kink,
  \item |pos = 1| will be at the second kink and
  \item |pos = .5| will still be in the middle of the middle part of the connection.
  \end{itemize}
\end{key}
\begin{key}{/tikz/ortho/middle 0 to 1}
  This is an alias for |spacing = 0|.
\end{key}

\subsection{Zig-Zig}
\begin{pathoperation}{r-ud}{\opt{\oarg{options}}\meta{coordinate or cycle}}
  This operation means ``first up, then horizontal and then down''.
  \begin{key}{/tikz/ortho/ud distance=\meta{length} (initially .5cm)}
    This sets the distance between the start and the horizontal line to \meta{length}.
  \end{key}
\end{pathoperation}
\begin{pathoperation}{r-du}{\opt{\oarg{options}}\meta{coordinate or cycle}}
  This operation means ``first down, then horizontal and then up''.
  \begin{key}{/tikz/ortho/du distance=\meta{length} (initially .5cm)}
    This sets the distance between the start and the horizontal line to \meta{length}.
  \end{key}
\end{pathoperation}
\begin{pathoperation}{r-lr}{\opt{\oarg{options}}\meta{coordinate or cycle}}
  This operation means ``left down, then vertical and then right''.
  \begin{key}{/tikz/ortho/lr distance=\meta{length} (initially .5cm)}
    This sets the distance between the start and the vertical line to \meta{length}.
  \end{key}
\end{pathoperation}
\begin{pathoperation}{r-rl}{\opt{\oarg{options}}\meta{coordinate or cycle}}
  This operation means ``first right, then vertical and then down''.
  \begin{key}{/tikz/ortho/rl distance=\meta{length} (initially .5cm)}
    This sets the distance between the start and the vertical line to \meta{length}.
  \end{key}
\end{pathoperation}

All distances can be set with one key.
\begin{key}{/tikz/ortho/udlr distance=\meta{length}}
  Sets all the previous distances to the same value \meta{length}.
\end{key}

\subsection{Even more Horizontal and Vertical Lines}

The following keys can be used to access vertical and horizontal line path operations.
\begin{stylekey}{/tikz/horizontal vertical}
  This installs  \verb!to path = -| (\tikztotarget) \tikztonodes!\indexKeyO{to path}
  that can be used with the path operations |to| or |edge|.
\end{stylekey}
\begin{stylekey}{/tikz/vertical horizontal}
  This installs \verb!to path = |- (\tikztotarget) \tikztonodes!
  that can be used with the path operations |to| or |edge|.
\end{stylekey}
\begin{stylekey}{/tikz/horizontal vertical horizontal}
  This installs  \verb!to path = -|- (\tikztotarget) \tikztonodes!
  that can be used with the path operations |to| or |edge|.
\end{stylekey}
\begin{stylekey}{/tikz/vertical horizontal vertical}
  This installs  \verb!to path = |-| (\tikztotarget) \tikztonodes!
  that can be used with the path operations |to| or |edge|.
\end{stylekey}

When connecting rectangular nodes, these keys could be useful as well.
They all need to be given to a |to| or |edge| path operation.
\begin{stylekey}{/tikz/only vertical second=\opt{\meta{length}} (default 0pt)}
This draws a vertical line from the start point to the target point so that
it connects to the target point in the center (or at its border in case it is a node).

The optional \meta{length} can be used to shift the line orthogonally to its direction.
\end{stylekey}
\begin{stylekey}{/tikz/only horizontal second=\opt{\meta{length}} (default 0pt)}
This draws a horizontal line from the start point to the target point so that
it connects to the target point in the center (or at its border in case it is a node).

The optional \meta{length} can be used to shift the line orthogonally to its direction.
\end{stylekey}
\begin{stylekey}{/tikz/only vertical first=\opt{\meta{length}} (default 0pt)}
This draws a vertical line from the start point to the target point so that
it connects to the start point in the center (or at its border in case it is a node).

The optional \meta{length} can be used to shift the line orthogonally to its direction.
\end{stylekey}
\begin{stylekey}{/tikz/only horizontal first=\opt{\meta{length}} (default 0pt)}
This draws a horizontal line from the start point to the target point so that
it connects to the start point in the center (or at its border in case it is a node).

The optional \meta{length} can be used to shift the line orthogonally to its direction.
\end{stylekey}

\pagebreak
Since all previous key are rather cumbersome, one can install shortcuts for these.
\begin{stylekey}{/tikz/ortho/install shortcuts}
Installs the following shortcuts:\\
{\ttfamily
\begin{tabular}{l@{\hspace{.5em}${}\to{}$\hspace{.5em}}l}
  \pgfmanualbar-              & vertical horizontal            \\
  -\pgfmanualbar              & horizontal vertical            \\
  -\pgfmanualbar-             & horizontal vertical horizontal \\
  \pgfmanualbar-\pgfmanualbar & vertical horizontal vertical   \\
  \pgfmanualbar*              & only vertical first            \\
  *\pgfmanualbar              & only vertical second           \\
  -*                          & only horizontal first          \\
  *-                          & only horizontal second
\end{tabular}
}
\end{stylekey}