% !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{Layers}
\begin{tikzlibrary}{ext.layers}
This library extends \tikzname's functionalities to put nodes, edges, matrices and pics
on a separate layer without having to use the \referenceEnvironmentandIndexO{pgfonlayer} environment.

\textbf{Consider this library experimental.}
If you can, avoid it and use the |pgfonlayer| environment
or change the drawing order.
\end{tikzlibrary}

\begin{multicols}{2}
%\subsection{Internal keys}
\begin{key}{/\tikzext/layers/patch=\mchoice{node, matrix, pic, edge, all}}
\keycompat{tikz-ext/layers}
Since this library is experimental, its functionality needs to be activated explicitly.
Patches exist for
\begin{itemize}
\item |node|,
\item |matrix|,
\item |pic|%
  \footnote{Only the normal \referenceKeyandIndexO[/tikz/pics/]{code}
            can be placed on different layers.
            Both \referenceKeyandIndexO[/tikz/pics/]{background code}
            and \referenceKeyandIndexO[/tikz/pics/]{foreground code}
            will not be affected.},
\item |edge| or
\item |all| which applies all the patches at once.
\end{itemize}
\end{key}
%
%These keys only work when a patch is applied.
%These will be used internally.
%\begin{key}{/\tikzext/layers/on layer=\meta{layer}}
%\keycompat{tikz-ext/layers}
%Places an object on the \pgfname\ layer \meta{layer}.
%\end{key}
%\begin{key}{/\tikzext/layers/in box=\meta{box}}
%\keycompat{tikz-ext/layers}
%Places an object in the \TeX\ box \meta{box}.
%\end{key}

%\subsection{User-level keys}
\newcolumn
\begin{key}{/\tikzext/node on layer=\meta{layer}}
\keycompat{tikz}
If the |node| patch is applied, this key places a node on layer \meta{layer}.
\end{key}
%\begin{key}{/\tikzext/node in box=\meta{box}}
%\keycompat{tikz}
%If the |node| patch is applied, this key places a node in box \meta{box}.
%\end{key}

\begin{key}{/\tikzext/matrix on layer=\meta{layer}}
\keycompat{tikz}
If the |matrix| patch is applied, this key places the matrix on layer \meta{layer}.
\end{key}
%\begin{key}{/\tikzext/matrix in box=\meta{box}}
%\keycompat{tikz}
%If the |matrix| patch is applied, this key places the matrix in box \meta{box}.
%\end{key}

\begin{key}{/\tikzext/edge on layer=\meta{layer}}
\keycompat{tikz}
If the |edge| patch is applied, this key places the edge on layer \meta{layer}.
\end{key}
%\begin{key}{/\tikzext/edge in box=\meta{box}}
%\keycompat{tikz}
%If the |edge| patch is applied, this key places the edge in box \meta{box}.
%\end{key}

\begin{key}{/\tikzext/pic on layer=\meta{layer}}
\keycompat{tikz}
If the |pic| patch is applied, this key places the main code of a pic on layer \meta{layer}.
\end{key}
%\begin{key}{/\tikzext/pic in box=\meta{box}}
%\keycompat{tikz}
%If the |pic| patch is applied, this key places the main code of a pic in box \meta{box}.
%\end{key}
\end{multicols}
\begin{codeexample}[width=.5\linewidth,preamble=\usetikzlibrary{ext.layers}]
\pgfdeclarelayer{front}
\begin{tikzpicture}[ext/layers/patch=node]
\pgfsetlayers{main,front}
\draw (0, -1) -- node[
                   ext/node on layer=front,
                   draw, fill=white, sloped
                 ] {On Top} (2,1);
\draw[red] (0, 1) -- (2, -1);
\end{tikzpicture}
\end{codeexample}