% !TeX spellcheck = en_US
% !TeX root = tikz-ext-manual.tex
% Copyright 2023 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{Arrow Tips}
\label{pgflibrary:arrows}
\tikzset{external/export/.try=false}%
\begin{pgflibrary}{ext.arrows}
  This library adds arrows to \pgfname/\tikzname.
  
  \inspiration{ArrowLoop-Q,ArrowHug-Q,ArrowUntipped1-Q,ArrowUntipped2-Q,DoubleTipQ}
              {ArrowLoop-A,ArrowHug-A,ArrowUntipped1-A,ArrowUntipped2-A,DoubleTipA}
\end{pgflibrary}
\begin{multicols}{2}
The arrow tips of the \referenceLibraryandIndexO{arrows.meta} library always
just touch the end of original line -- which is usually
what you want.

But for some arrow tips (and when they lie along a path) it makes sense
that these tips shoot a bit over the end of the line.
This is why these arrow tips exist.
They can be categorized into three groups:
\begin{enumerate}
\item Centered
\item Untipped
\item Overtipped\footnote{The Overtipped arrow tips aren't yet implemented.}
\end{enumerate}
Not all original arrow tips got all variants.
For a summary, refer to table on the right side.
As with the original tips of the \referenceLibraryandIndexO{arrows.meta} library
these can be organized in the following categories.
\newcolumn
\begin{center}
\newcommand*\tip[2][]{%
  \tikzset{external/export/.try=false}%
  \tikz[arrows={ext_#2 \arrowtiprow[reversed] - \arrowtiprow[sep] . ext_#2 \arrowtiprow[]}, baseline=+-.5ex,
    trim left=+-3mm, trim right=+13mm]
    \draw[line width=+.5mm, postaction={draw, gray, thin,-}] (0,0) -- + (right:1);%
}%
\def\tiprow#1 &{#1\gdef\arrowtiprow{#1} &}%
\def\Tiprow#1 &{\quad#1\gdef\arrowtiprow{#1} &}%
%\centering
%\caption{Variants of the original \texttt{arrows.meta} arrow tips.
%  For each example, the order is 1. reversed variant, 2. original, 3. variant.
%  They gray line shows where the path actually ends.
%}\label{tab:tips}
\begin{tabular}{ll ccc}
  \toprule
  Group        & Original                   & Centered       &    Untipped    & Overtipped \\ \midrule
  Barbed       & \tiprow Arc Barb           & \tip{Centered} & \tip{Untipped} &     --     \\
               & \Tiprow Parenthesis        & \tip{Centered} & \tip{Untipped} &     --     \\
               & \tiprow Hooks              & \tip{Centered} &       --       &     --     \\
               & \tiprow Straight Barb      & \tip{Centered} &       --       &     --     \\
               & \tiprow Tee Barb           & \tip{Centered} & \tip{Untipped} &     --     \\
               & \Tiprow Bar                & \tip{Centered} & \tip{Untipped} &     --     \\
               & \Tiprow Bracket            & \tip{Centered} & \tip{Untipped} &     --     \\ \midrule
%  Mathematical & Classical TikZ Rightarrow  & --             &       --       &     --     \\
%               & Computer Modern Rightarrow & --             &       --       &     --     \\
%               & \quad To                   & --             &       --       &     --     \\
%               & Implies                    & --             &       --       &     --     \\ \midrule
  Geometric    & \tiprow Circle             & \tip{Centered} & \tip{Untipped} &     --     \\
               & \Tiprow Ellipse            & \tip{Centered} & \tip{Untipped} &     --     \\
               & \tiprow Kite               & \tip{Centered} &       --       &     --     \\
               & \Tiprow Diamond            & \tip{Centered} &       --       &     --     \\
               & \Tiprow Turned Square      & \tip{Centered} &       --       &     --     \\
               & \tiprow LaTeX              & --             &       --       &     --     \\
               & \tiprow Square             & \tip{Centered} &       --       &     --     \\
               & \Tiprow Rectangle          & \tip{Centered} &       --       &     --     \\
               & \tiprow Stealth            & \tip{Centered} &       --       &     --     \\
               & \Tiprow Triangle           & \tip{Centered} &       --       &     --     \\ \midrule
%  Caps         &                            & --             &       --       &     --     \\
  Rays         & \tiprow Rays               & \tip{Centered} &       --       &     --     \\ \bottomrule
\end{tabular}
\end{center}
\newcolumn

\subsection{Centered}
\subsubsection{Barbed Arrow Tips}
\begin{arrowtipsimple}{ext\textunderscore Centered Arc Barb}\tipcompat
    This is a variant of the \referenceArrowtipandIndexO{Arc Barb} tip.
    The center of the arc lies on the original end of the path.
\end{arrowtipsimple}

\begin{arrowtipsimple}{ext\textunderscore Centered Bar}\tipcompat
    A variant of the simple \referenceArrowtipandIndexO{Bar} tip.
    This is a simple instance of |ext_Centered Tee Barb| for length zero.
    
    The middle of the line will lie on original end of the path.
\end{arrowtipsimple}

\begin{arrowtipsimple}{ext\textunderscore Centered Bracket}\tipcompat
    This is a variant of the \referenceArrowtipandIndexO{Bracket} tip and
    therefore an instance of the |ext_Centered Tee Barb| arrow tip that results in something
    resembling a bracket.
    
    The middle of the vertical part will lie on the original end of the path.
\end{arrowtipsimple}

\begin{arrowtipsimple}{ext\textunderscore Centered Hooks}\tipcompat
    A variant of the \referenceArrowtipandIndexO{Hooks} tip.
    The starting point of the hooks will lie on the original end of the path.
\end{arrowtipsimple}

\begin{arrowtipsimple}{ext\textunderscore Centered Parenthesis}\tipcompat
    This is a variant of the \referenceArrowtipandIndexO{Parenthesis} tip and
    thus an instance of the |ext_Centered Arc Barb| arrow tip.
\end{arrowtipsimple}

\begin{arrowtipsimple}{ext\textunderscore Centered Straight Barb}\tipcompat
    A variant of the \referenceArrowtipandIndexO{Straight Barb} tip.
\end{arrowtipsimple}

\begin{arrowtipsimple}{ext\textunderscore Centered Tee Barb}\tipcompat
    A variant of the \referenceArrowtipandIndexO{Tee Barb} tip.
    
    The middle of the vertical part will lie on the original end of the path.
\end{arrowtipsimple}

\subsubsection{Geometric Arrow Tips}
\begin{arrowtipsimple}{ext\textunderscore Centered Circle}\tipcompat
    A variant of the \referenceArrowtipandIndexO{Circle} tip.
    The center of the circle will lie on the original end of the path.
\end{arrowtipsimple}

\begin{arrowtipsimple}{ext\textunderscore Centered Diamond}\tipcompat
    This is a variant of the \referenceArrowtipandIndexO{Diamond} tip and
    thus an instance of |ext_Centered Kite| where the length is larger than the width.
\end{arrowtipsimple}

\begin{arrowtipsimple}{ext\textunderscore Centered Ellipse}\tipcompat
    This is a variant of the \referenceArrowtipandIndexO{Ellipse} tip
    and thus another name for the |ext_Centered Circle| tip
    that is twice as wide as high.
\end{arrowtipsimple}

\begin{arrowtipsimple}{ext\textunderscore Centered Kite}\tipcompat
    A variant of the \referenceArrowtipandIndexO{Kite} tip.
    
    The widest part will lie on the original end of the path.
\end{arrowtipsimple}

\begin{arrowtipsimple}{ext\textunderscore Centered Rectangle}\tipcompat
    A variant of the \referenceArrowtipandIndexO{Rectangle} tip.
    By default, it is twice as long as high.
\end{arrowtipsimple}

\begin{arrowtipsimple}{ext\textunderscore Centered Square}\tipcompat
    A variant of the \referenceArrowtipandIndexO{Square} tip.
\end{arrowtipsimple}

\begin{arrowtipsimple}{ext\textunderscore Centered Stealth}\tipcompat
    This is a variant of the \referenceArrowtipandIndexO{Stealth} tip.
    
    The weighted center will lie at the original end of the path.
\end{arrowtipsimple}

\begin{arrowtipsimple}{ext\textunderscore Centered Triangle}\tipcompat
    This is a variant of the \referenceArrowtipandIndexO{Triangle} tip and
    thus an instance of the |ext_Centered Kite| tip with zero inset.
\end{arrowtipsimple}

\begin{arrowtipsimple}{ext\textunderscore Centered Turned Square}\tipcompat
    This is a variant of the \referenceArrowtipandIndexO{Turned Square} tip and
    thus an instance of the |ext_Centered Kite| tip with identical width and height and mid-inset.
\end{arrowtipsimple}

\subsubsection{Special Arrow Tips}
\begin{arrowtipsimple}{ext\textunderscore Centered Rays}\tipcompat
    A variant of the \referenceArrowtipandIndexO{Rays} tip.
    The origin of the rays will lie on the original end of the path.
\end{arrowtipsimple}

\subsection{Untipped}
\subsubsection{Barbed Arrow Tips}
\begin{arrowtipsimple}{ext\textunderscore Centered Arc Barb}\tipcompat
    This is a variant of the \referenceArrowtipandIndexO{Arc Barb} tip.
    The arrow tip will protrude half its line width over the original end of the path.
\end{arrowtipsimple}

\begin{arrowtipsimple}{ext\textunderscore Untipped Bar}\tipcompat
    A variant of the simple \referenceArrowtipandIndexO{Bar} tip.
    This is a simple instance of |ext_Untipped Tee Barb| for length zero.
    
    The middle of the line will lie on original end of the path.
\end{arrowtipsimple}

\begin{arrowtipsimple}{ext\textunderscore Untipped Bracket}\tipcompat
    This is a variant of the \referenceArrowtipandIndexO{Bracket} tip and
    therefore an instance of the |ext_Untipped Tee Barb| arrow tip that results in something
    resembling a bracket.
    
    The arrow tip will protrude half its line width over the original end of the path.
\end{arrowtipsimple}

\begin{arrowtipsimple}{ext\textunderscore Untipped Parenthesis}\tipcompat
    This is a variant of the \referenceArrowtipandIndexO{Parenthesis} tip and
    thus an instance of the |ext_Untipped Arc Barb| arrow tip.
\end{arrowtipsimple}

\begin{arrowtipsimple}{ext\textunderscore Untipped Tee Barb}\tipcompat
    A variant of the \referenceArrowtipandIndexO{Tee Barb} tip.
    
    The middle of the vertical part will lie on the original end of the path.
\end{arrowtipsimple}

\subsubsection{Geometric Arrow Tips}
\begin{arrowtipsimple}{ext\textunderscore Untipped Circle}\tipcompat
    A variant of the \referenceArrowtipandIndexO{Circle} tip.
    This tip will protrude half its line width over the original end of the path.
\end{arrowtipsimple}

\begin{arrowtipsimple}{ext\textunderscore Untipped Ellipse}\tipcompat
    This is a variant of the \referenceArrowtipandIndexO{Ellipse} tip
    and thus another name for the |ext_Untipped Circle| tip
    that is twice as wide as high.
\end{arrowtipsimple}

\newcolumn
\subsection{Original Arrow Tips}
\begin{arrowtipsimple}{ext\textunderscore Hug Cap}\tipcompat
This arrow tips will hug a circle that would touch the end of the path.

Use the \referenceKeyandIndexO[/pgf/arrow keys/]{length} key to set up the radius of that circle.

\begin{codeexample}[preamble=\usepgflibrary{ext.arrows}]
\begin{tikzpicture}[
  dot/.style 2 args={
    shape=circle, outer sep=+0pt, fill={#1}, minimum size={#2}}]
\node[dot={red} {2cm}] (A)           {};
\node[dot={blue}{3cm}] (B) at (6,0) {};
\draw[
  line width=1.5cm,
  arrows={ext_Hug Cap[length=1cm]-ext_Hug Cap[length=1.5cm]}
] (A) to[out=45, in=180] (B);
\end{tikzpicture}
\end{codeexample}
\end{arrowtipsimple}

\makeatletter
\newcommand*\extus{%
  \ifx\path\tikz@command@path
    ext_%
  \else
    ext\textunderscore
  \fi
}
\makeatother
\begin{arrowtip}{\extus Loop}{\tipCompat{Loop}
  This arrow tip attaches a one-sided loop to the end of the line.
  The |length| refers to the length of the whole tip while the |inset|
  specifies the radius of the three rounded corners.
  The width of the tip is twice the |length| (but can't specified independently).
}{length=1.5cm,inset=3.5mm}{length=1.5cm,radius=3.5mm/1.5cm}
    \begin{arrowexamples}
        \arrowexample[]
        \arrowexampledup[sep]
        \arrowexampledupdot[sep]
        \arrowexample[open]
        \arrowexample[open, swap]
        \arrowexample[length=5pt,inset=0pt]
        \arrowexample[reversed]
        \arrowexample[slant=.3]
        \arrowexample[red]
    \end{arrowexamples}
    %
    The following options have no effect: |harpoon|, |round|, |line width|.

    On |double| lines, the arrow tip will not look correct.
\end{arrowtip}
\begin{arrowtipsimple}{\extus Double Stealth}
  This arrow tip is similar to the original \referenceArrowtipandIndexO{Stealth},
  its back is left open so that it aligns neatly to a |double|d path.
\end{arrowtipsimple}
\begin{arrowtipsimple}{\extus Double Triangle}
  This arrow tip is similar to the original \referenceArrowtipandIndexO{Triangle},
  its back is left open so that it aligns neatly to a |double|d path.
\end{arrowtipsimple}
\begin{arrowtipsimple}{\extus Double Cap}
  This arrow tip closes a |double|d line so that it not left open.
\end{arrowtipsimple}
\begin{codeexample}[preamble=\usepgflibrary{ext.arrows}]
\begin{tikzpicture}
\draw[
  ext_Double Cap-ext_Double Stealth,
  double distance=1cm,
  line width=3mm
] (0,0) to[bend left] (right:9);
\end{tikzpicture}
\end{codeexample}
\end{multicols}
\tikzset{external/export/.try=true}%
\endinput
