% !TeX root = tcolorbox.tex
% include file of tcolorbox.tex (manual of the LaTeX package tcolorbox)
\clearpage
\section{Library \mylib{hooks}}\label{sec:hooks}
The library is loaded by a package option or inside the preamble by:
\begin{dispListing}
\tcbuselibrary{hooks}
\end{dispListing}

For the skin related options, the library \mylib{skins} has to be loaded
separately.


\subsection{Concept of Hooks}
A hook is a placeholder in some \LaTeX\ code where additional code
can be added. For example, the \LaTeX\ macro |\AtBeginDocument| adds code to a
hook which is placed at the beginning of every document.

Several option keys of |tcolorbox| allow providing some code which is
added to specific places of a colored box. For example, \refKey{/tcb/before upper}
places code before the content of the upper part. A following usage of this
key overwrites any prior settings.

The library \mylib{hooks} extends \refKey{/tcb/before upper} and several more
existing keys to 'hookable' versions, e.\,g.\ 
\refKey{/tcb/before upper app} and \refKey{/tcb/before upper pre}.
The 'hookable' keys don't overwrite prior settings but either \emph{app}end
or \emph{pre}pend the newly given code to the existing code.

The general naming convention (with some small exceptions) is:
\begin{itemize}
\item \meta{option key} |app|: works like \meta{option key} but
  \emph{app}ends its code to the existing code.
\item \meta{option key} |pre|: works like \meta{option key} but
  \emph{pre}pends its code to the existing code.
\end{itemize}
If the original \meta{option key} is used (again), all code will be overwritten.
Therefore, the order of the option key usage is crucial.



\begin{dispExample}
% \usepackage{array,tabularx}
\newcolumntype{Y}{>{\raggedleft\arraybackslash}X}% see tabularx
\tcbset{enhanced,fonttitle=\bfseries\large,fontupper=\normalsize\sffamily,
  colback=yellow!10!white,colframe=red!50!black,colbacktitle=Salmon!30!white,
  coltitle=black,center title,
  tabularx={X||Y|Y|Y|Y||Y},% this sets 'before upper' and 'after upper'
  before upper app={Group & One & Two & Three & Four & Sum\\\hline\hline}  }

\begin{tcolorbox}[title=My table]
Red   & 1000.00 & 2000.00 &  3000.00 &  4000.00 & 10000.00\\\hline
Green & 2000.00 & 3000.00 &  4000.00 &  5000.00 & 14000.00\\\hline
Blue  & 3000.00 & 4000.00 &  5000.00 &  6000.00 & 18000.00\\\hline\hline
Sum   & 6000.00 & 9000.00 & 12000.00 & 15000.00 & 42000.00
\end{tcolorbox}
\end{dispExample}



\clearpage
\subsection{Box Content Additions}\label{subsec:hookscontentadditions}
The following option keys extend the options given in Subsection \ref{subsec:contentadditions}
from page \pageref{subsec:contentadditions}.

\begin{docTcbKey}{before title app}{=\meta{code}}{no default}
  Appends the given \meta{code} to \refKey{/tcb/before title} \emph{after} the color and font settings
  and \emph{before} the content of the title.
\end{docTcbKey}

\begin{docTcbKey}{before title pre}{=\meta{code}}{no default}
  Prepends the given \meta{code} to \refKey{/tcb/before title} \emph{after} the color and font settings
  and \emph{before} the content of the title.
\end{docTcbKey}

\begin{docTcbKey}{after title app}{=\meta{code}}{no default}
  Appends the given \meta{code} to \refKey{/tcb/after title} \emph{after} the content of the title.
\end{docTcbKey}

\begin{docTcbKey}{after title pre}{=\meta{code}}{no default}
  Prepends the given \meta{code} to \refKey{/tcb/after title} \emph{after} the content of the title.
\end{docTcbKey}

\begin{docTcbKey}{before upper app}{=\meta{code}}{no default}
  Appends the given \meta{code} to \refKey{/tcb/before upper} \emph{after} the color and font settings
  and \emph{before} the content of the upper part.
\end{docTcbKey}

\begin{docTcbKey}{before upper pre}{=\meta{code}}{no default}
  Prepends the given \meta{code} to \refKey{/tcb/before upper} \emph{after} the color and font settings
  and \emph{before} the content of the upper part.
\end{docTcbKey}

\begin{docTcbKey}{after upper app}{=\meta{code}}{no default}
  Appends the given \meta{code} to \refKey{/tcb/after upper} \emph{after} the content of the upper part.
\end{docTcbKey}

\begin{docTcbKey}{after upper pre}{=\meta{code}}{no default}
  Prepends the given \meta{code} to \refKey{/tcb/after upper} \emph{after} the content of the upper part.
\begin{dispExample}
% \tcbuselibrary{theorems}
\tcbset{ams align,%  this sets 'before upper' and 'after upper'
  colback=yellow!10!white,colframe=red!50!black,
  before upper app={\frac{2}{\sqrt{2}}&=\sqrt{2}.\\},
  after upper pre={\\\sin\left(\frac{\pi}{2}\right)&=1.},
}

\begin{tcolorbox}
  \sum\limits_{n=1}^{\infty} \frac{1}{n} &= \infty.\\
  \int x^2 ~\text{d}x &= \frac13 x^3 + c.
\end{tcolorbox}
\end{dispExample}
\end{docTcbKey}

\clearpage
\begin{docTcbKey}{before lower app}{=\meta{code}}{no default}
  Appends the given \meta{code} to \refKey{/tcb/before lower} \emph{after} the color and font settings
  and \emph{before} the content of the lower part.
\end{docTcbKey}

\begin{docTcbKey}{before lower pre}{=\meta{code}}{no default}
  Prepends the given \meta{code} to \refKey{/tcb/before lower} \emph{after} the color and font settings
  and \emph{before} the content of the lower part.
\end{docTcbKey}

\begin{docTcbKey}{after lower app}{=\meta{code}}{no default}
  Appends the given \meta{code} to \refKey{/tcb/after lower} \emph{after} the content of the lower part.
\end{docTcbKey}

\begin{docTcbKey}{after lower pre}{=\meta{code}}{no default}
  Prepends the given \meta{code} to \refKey{/tcb/after lower} \emph{after} the content of the lower part.
\end{docTcbKey}


\subsection{Embedding into the Surroundings}
The following option keys extend the options given in Subsection \ref{subsec:surroundings}
from page \pageref{subsec:surroundings}.

\begin{marker}
The 'hookable' versions are usable inside the document.
In the preamble, they can only be used after explicit setting of
\refKey{/tcb/before} and \refKey{/tcb/after} or by e.\,g.\ \refKey{/tcb/parskip}.
\end{marker}

\begin{docTcbKey}{before app}{=\meta{code}}{no default}
  Appends the given \meta{code} to \refKey{/tcb/before} before the colored box.
\end{docTcbKey}

\begin{docTcbKey}{before pre}{=\meta{code}}{no default}
  Prepends the given \meta{code} to \refKey{/tcb/before} before the colored box.
\end{docTcbKey}

\begin{docTcbKey}{after app}{=\meta{code}}{no default}
  Appends the given \meta{code} to \refKey{/tcb/after} after the colored box.
\end{docTcbKey}

\begin{docTcbKey}{after pre}{=\meta{code}}{no default}
  Prepends the given \meta{code} to \refKey{/tcb/after} after the colored box.
\end{docTcbKey}

\begin{dispExample}
\tcbset{colback=red!5!white,colframe=red!75!black,fonttitle=\bfseries}

\begin{tcolorbox}[title=My title,before app={The box follows:\\[4pt]},
  after app={This is the end.}]
This is a \textbf{tcolorbox}.
\end{tcolorbox}
\end{dispExample}


\clearpage
\subsection{Overlays}
The following option keys extend the options given in Subsection \ref{subsec:overlays}
from page \pageref{subsec:overlays}.

\begin{docTcbKey}{overlay app}{=\meta{graphical code}}{no default}
  Appends the given \meta{graphical code} to \refKey{/tcb/overlay}.


\begin{dispExample}
% \usetikzlibrary{patterns} % preamble
% \tcbuselibrary{skins} % preamble
\tcbset{frogbox/.style={enhanced,colback=green!10,colframe=green!65!black,
  enlarge top by=5.5mm,
  overlay={\foreach \x in {2cm,3.5cm} {
    \begin{scope}[shift={([xshift=\x]frame.north west)}]
      \path[draw=green!65!black,fill=green!10,line width=1mm] (0,0) arc (0:180:5mm);
      \path[fill=black] (-0.2,0) arc (0:180:1mm);
    \end{scope}}}]}}
\tcbset{ribbon/.style={overlay app={%
  \path[fill=blue!75!white,draw=blue,double=white!85!blue,
    preaction={opacity=0.6,fill=blue!75!white},
    line width=0.1mm,double distance=0.2mm,
    pattern=fivepointed stars,pattern color=white!75!blue]
    ([xshift=-0.2mm,yshift=-1.02cm]frame.north east)
    -- ++(-1,1) -- ++(-0.5,0) -- ++(1.5,-1.5) -- cycle;}}}

\begin{tcolorbox}[frogbox,title=My title]
This is a \textbf{tcolorbox}.
\end{tcolorbox}

\begin{tcolorbox}[frogbox,ribbon,title=My title]
This is a \textbf{tcolorbox}.\par
Here, we apply a second overlay.
\end{tcolorbox}
\end{dispExample}
\end{docTcbKey}

\begin{docTcbKey}{overlay pre}{=\meta{graphical code}}{no default}
  Prepends the given \meta{graphical code} to \refKey{/tcb/overlay}.
\end{docTcbKey}

\begin{docTcbKey}{overlay unbroken app}{=\meta{graphical code}}{no default}
  Appends the given \meta{graphical code} to \refKey{/tcb/overlay unbroken}.
\end{docTcbKey}

\begin{docTcbKey}{overlay unbroken pre}{=\meta{graphical code}}{no default}
  Prepends the given \meta{graphical code} to \refKey{/tcb/overlay unbroken}.
\end{docTcbKey}

\begin{docTcbKey}{overlay first app}{=\meta{graphical code}}{no default}
  Appends the given \meta{graphical code} to \refKey{/tcb/overlay first}.
\end{docTcbKey}

\begin{docTcbKey}{overlay first pre}{=\meta{graphical code}}{no default}
  Prepends the given \meta{graphical code} to \refKey{/tcb/overlay first}.
\end{docTcbKey}

\clearpage
\begin{docTcbKey}{overlay middle app}{=\meta{graphical code}}{no default}
  Appends the given \meta{graphical code} to \refKey{/tcb/overlay middle}.
\end{docTcbKey}

\begin{docTcbKey}{overlay middle pre}{=\meta{graphical code}}{no default}
  Prepends the given \meta{graphical code} to \refKey{/tcb/overlay middle}.
\end{docTcbKey}

\begin{docTcbKey}{overlay last app}{=\meta{graphical code}}{no default}
  Appends the given \meta{graphical code} to \refKey{/tcb/overlay last}.
\end{docTcbKey}

\begin{docTcbKey}{overlay last pre}{=\meta{graphical code}}{no default}
  Prepends the given \meta{graphical code} to \refKey{/tcb/overlay last}.
\end{docTcbKey}

\begin{docTcbKey}{overlay broken app}{=\meta{graphical code}}{no default}
  Appends the given \meta{graphical code} to \refKey{/tcb/overlay broken}.
\end{docTcbKey}

\begin{docTcbKey}{overlay broken pre}{=\meta{graphical code}}{no default}
  Prepends the given \meta{graphical code} to \refKey{/tcb/overlay broken}.
\end{docTcbKey}

\begin{docTcbKey}{overlay unbroken and first app}{=\meta{graphical code}}{no default}
  Appends the given \meta{graphical code} to \refKey{/tcb/overlay unbroken and first}.
\end{docTcbKey}

\begin{docTcbKey}{overlay unbroken and first pre}{=\meta{graphical code}}{no default}
  Prepends the given \meta{graphical code} to \refKey{/tcb/overlay unbroken and first}.
\end{docTcbKey}

\begin{docTcbKey}{overlay middle and last app}{=\meta{graphical code}}{no default}
  Appends the given \meta{graphical code} to \refKey{/tcb/overlay middle and last}.
\end{docTcbKey}

\begin{docTcbKey}{overlay middle and last pre}{=\meta{graphical code}}{no default}
  Prepends the given \meta{graphical code} to \refKey{/tcb/overlay middle and last}.
\end{docTcbKey}

\begin{docTcbKey}{overlay unbroken and last app}{=\meta{graphical code}}{no default}
  Appends the given \meta{graphical code} to \refKey{/tcb/overlay unbroken and last}.
\end{docTcbKey}

\begin{docTcbKey}{overlay unbroken and last pre}{=\meta{graphical code}}{no default}
  Prepends the given \meta{graphical code} to \refKey{/tcb/overlay unbroken and last}.
\end{docTcbKey}

\begin{docTcbKey}[][doc new=2014-09-19]{overlay first and middle app}{=\meta{graphical code}}{no default}
  Appends the given \meta{graphical code} to \refKey{/tcb/overlay first and middle}.
\end{docTcbKey}

\begin{docTcbKey}[][doc new=2014-09-19]{overlay first and middle pre}{=\meta{graphical code}}{no default}
  Prepends the given \meta{graphical code} to \refKey{/tcb/overlay first and middle}.
\end{docTcbKey}


\clearpage
\subsection{Watermarks}
The following option keys extend the options given in Subsection \ref{subsec:watermarks}
from page \pageref{subsec:watermarks}.

\begin{marker}
Watermarks are special overlays. The \mylib{hooks} library allows the combination
of several watermarks and overlays.
\end{marker}

\begin{docTcbKey}{watermark text app}{=\meta{text}}{no default}
  Appends a \refKey{/tcb/watermark text} to the colored box.
\begin{dispExample}
\tcbset{colback=red!5!white,colframe=red!75!black,fonttitle=\bfseries}

\begin{tcolorbox}[enhanced,title=My title,watermark graphics=Basilica_5.png,
  watermark opacity=0.25,
  watermark text app=Basilica,watermark color=Navy
  ]
\lipsum[1-2]
\tcblower
This example uses a public domain picture from\\
\url{http://commons.wikimedia.org/wiki/File:Basilica_5.png}
\end{tcolorbox}
\end{dispExample}
\end{docTcbKey}

\begin{docTcbKey}{watermark text pre}{=\meta{text}}{no default}
  Prepends a \refKey{/tcb/watermark text} to the colored box.
\end{docTcbKey}

\begin{docTcbKey}{watermark text app on}{=\meta{part} is \meta{text}}{no default}
  Appends a \refKey{/tcb/watermark text on} the named \meta{part} of a break sequence.
\end{docTcbKey}

\begin{docTcbKey}{watermark text pre on}{=\meta{part} is \meta{text}}{no default}
  Prepends a \refKey{/tcb/watermark text on} the named \meta{part} of a break sequence.
\end{docTcbKey}

\clearpage
\begin{docTcbKey}{watermark graphics app}{=\meta{file name}}{no default}
  Appends a \refKey{/tcb/watermark graphics} referenced by \meta{file name} to the colored box.
\end{docTcbKey}

\begin{docTcbKey}{watermark graphics pre}{=\meta{file name}}{no default}
  Prepends a \refKey{/tcb/watermark graphics} referenced by \meta{file name} to the colored box.
\end{docTcbKey}

\begin{docTcbKey}{watermark graphics app on}{=\meta{part} is \meta{file name}}{no default}
  Appends a \refKey{/tcb/watermark graphics on} the named \meta{part} of a break sequence.
  The picture is referenced by \meta{file name}.
\end{docTcbKey}


\begin{docTcbKey}{watermark graphics pre on}{=\meta{part} is \meta{file name}}{no default}
  Prepends a \refKey{/tcb/watermark graphics on} the named \meta{part} of a break sequence.
  The picture is referenced by \meta{file name}.
\end{docTcbKey}


\begin{docTcbKey}{watermark tikz app}{=\meta{graphical code}}{no default}
  Appends a \refKey{/tcb/watermark tikz} with the  given |tikz| \meta{graphical code} to the colored box.
\end{docTcbKey}

\begin{docTcbKey}{watermark tikz pre}{=\meta{graphical code}}{no default}
  Prepends a \refKey{/tcb/watermark tikz} with the  given |tikz| \meta{graphical code} to the colored box.

\begin{dispExample}
% \usepackage{tikz}
\tcbset{colback=red!5!white,colframe=red!75!black,fonttitle=\bfseries,
  watermark color=Navy,watermark opacity=0.25,
  smiley/.style={watermark tikz pre={%
    \path[fill=yellow,draw=yellow!75!red] (0,0) circle (1cm);
    \fill[red] (45:5mm) circle (1mm);
    \fill[red] (135:5mm) circle (1mm);
    \draw[line width=1mm,red] (215:5mm) arc (215:325:5mm);}}}

\begin{tcolorbox}[enhanced,title=My title, watermark text=Watermark,
  smiley]
\lipsum[1-2]
\end{tcolorbox}
\end{dispExample}
\end{docTcbKey}

\begin{docTcbKey}{watermark tikz app on}{=\meta{part} is \meta{graphical code}}{no default}
  Appends a \refKey{/tcb/watermark tikz on} the named \meta{part} of a break sequence.
\end{docTcbKey}

\begin{docTcbKey}{watermark tikz pre on}{=\meta{part} is \meta{graphical code}}{no default}
  Prepends a \refKey{/tcb/watermark tikz on} the named \meta{part} of a break sequence.
\end{docTcbKey}


\clearpage
\subsection{Underlays}
The following option keys extend the options given in \Vref{subsec:skinunderlay}.
There are no |app| type keys since underlays are stackable by default.

\begin{docTcbKey}{underlay pre}{=\meta{graphical code}}{no default}
  Prepends the given \meta{graphical code} to \refKey{/tcb/underlay}.
\end{docTcbKey}

\begin{docTcbKey}{underlay unbroken pre}{=\meta{graphical code}}{no default}
  Prepends the given \meta{graphical code} to \refKey{/tcb/underlay unbroken}.
\end{docTcbKey}

\begin{docTcbKey}{underlay first pre}{=\meta{graphical code}}{no default}
  Prepends the given \meta{graphical code} to \refKey{/tcb/underlay first}.
\end{docTcbKey}

\begin{docTcbKey}{underlay middle pre}{=\meta{graphical code}}{no default}
  Prepends the given \meta{graphical code} to \refKey{/tcb/underlay middle}.
\end{docTcbKey}

\begin{docTcbKey}{underlay last pre}{=\meta{graphical code}}{no default}
  Prepends the given \meta{graphical code} to \refKey{/tcb/underlay last}.
\end{docTcbKey}

\begin{docTcbKey}{underlay boxed title pre}{=\meta{graphical code}}{no default}
  Prepends the given \meta{graphical code} to \refKey{/tcb/underlay boxed title}.
\end{docTcbKey}

\begin{docTcbKey}{underlay broken pre}{=\meta{graphical code}}{no default}
  Prepends the given \meta{graphical code} to \refKey{/tcb/underlay broken}.
\end{docTcbKey}

\begin{docTcbKey}{underlay unbroken and first pre}{=\meta{graphical code}}{no default}
  Prepends the given \meta{graphical code} to \refKey{/tcb/underlay unbroken and first}.
\end{docTcbKey}

\begin{docTcbKey}{underlay middle and last pre}{=\meta{graphical code}}{no default}
  Prepends the given \meta{graphical code} to \refKey{/tcb/underlay middle and last}.
\end{docTcbKey}

\begin{docTcbKey}{underlay unbroken and last pre}{=\meta{graphical code}}{no default}
  Prepends the given \meta{graphical code} to \refKey{/tcb/underlay unbroken and last}.
\end{docTcbKey}

\begin{docTcbKey}[][doc new=2014-09-19]{underlay first and middle pre}{=\meta{graphical code}}{no default}
  Prepends the given \meta{graphical code} to \refKey{/tcb/underlay first and middle}.
\end{docTcbKey}


\clearpage
\subsection{Finishes}
The following option keys extend the options given in \Vref{subsec:skinfinish}.
There are no |app| type keys since finishes are stackable by default.


\begin{docTcbKey}{finish pre}{=\meta{graphical code}}{no default}
  Prepends the given \meta{graphical code} to \refKey{/tcb/finish}.
\end{docTcbKey}

\begin{docTcbKey}{finish unbroken pre}{=\meta{graphical code}}{no default}
  Prepends the given \meta{graphical code} to \refKey{/tcb/finish unbroken}.
\end{docTcbKey}

\begin{docTcbKey}{finish first pre}{=\meta{graphical code}}{no default}
  Prepends the given \meta{graphical code} to \refKey{/tcb/finish first}.
\end{docTcbKey}

\begin{docTcbKey}{finish middle pre}{=\meta{graphical code}}{no default}
  Prepends the given \meta{graphical code} to \refKey{/tcb/finish middle}.
\end{docTcbKey}

\begin{docTcbKey}{finish last pre}{=\meta{graphical code}}{no default}
  Prepends the given \meta{graphical code} to \refKey{/tcb/finish last}.
\end{docTcbKey}

\begin{docTcbKey}{finish broken pre}{=\meta{graphical code}}{no default}
  Prepends the given \meta{graphical code} to \refKey{/tcb/finish broken}.
\end{docTcbKey}

\begin{docTcbKey}{finish unbroken and first pre}{=\meta{graphical code}}{no default}
  Prepends the given \meta{graphical code} to \refKey{/tcb/finish unbroken and first}.
\end{docTcbKey}

\begin{docTcbKey}{finish middle and last pre}{=\meta{graphical code}}{no default}
  Prepends the given \meta{graphical code} to \refKey{/tcb/finish middle and last}.
\end{docTcbKey}

\begin{docTcbKey}{finish unbroken and last pre}{=\meta{graphical code}}{no default}
  Prepends the given \meta{graphical code} to \refKey{/tcb/finish unbroken and last}.
\end{docTcbKey}

\begin{docTcbKey}[][doc new=2014-09-19]{finish first and middle pre}{=\meta{graphical code}}{no default}
  Prepends the given \meta{graphical code} to \refKey{/tcb/finish first and middle}.
\end{docTcbKey}


\subsection{Skin Code}
The following option keys extend the options given in Subsection \ref{subsec:addcodeoptions}
from page \pageref{subsec:addcodeoptions}.

\begin{docTcbKey}{frame code app}{=\meta{graphical code}}{no default}
  Appends the given \meta{graphical code} to \refKey{/tcb/frame code}.
\end{docTcbKey}

\begin{docTcbKey}{frame code pre}{=\meta{graphical code}}{no default}
  Prepends the given \meta{graphical code} to \refKey{/tcb/frame code}.
\end{docTcbKey}

\begin{docTcbKey}{interior titled code app}{=\meta{graphical code}}{no default}
  Appends the given \meta{graphical code} to \refKey{/tcb/interior titled code}.
\begin{dispExample}
\begin{tcolorbox}[title=My title,enhanced,colframe=Navy,
  frame code app={\draw[yellow,line width=1cm] (
    frame.south west)--(frame.north east);},
  interior titled code app={\draw[red,line width=1cm]
    (frame.north west)--(frame.south east);},
  ]
\lipsum[1]
\end{tcolorbox}
\end{dispExample}
\end{docTcbKey}

\begin{docTcbKey}{interior titled code pre}{=\meta{graphical code}}{no default}
  Prepends the given \meta{graphical code} to \refKey{/tcb/interior titled code}.
\end{docTcbKey}

\begin{docTcbKey}{interior code app}{=\meta{graphical code}}{no default}
  Appends the given \meta{graphical code} to \refKey{/tcb/interior code}.
\end{docTcbKey}

\begin{docTcbKey}{interior code pre}{=\meta{graphical code}}{no default}
  Prepends the given \meta{graphical code} to \refKey{/tcb/interior code}.
\end{docTcbKey}

\begin{docTcbKey}{segmentation code app}{=\meta{graphical code}}{no default}
  Appends the given \meta{graphical code} to \refKey{/tcb/segmentation code}.
\end{docTcbKey}

\begin{docTcbKey}{segmentation code pre}{=\meta{graphical code}}{no default}
  Prepends the given \meta{graphical code} to \refKey{/tcb/segmentation code}.
\end{docTcbKey}


\begin{docTcbKey}{title code app}{=\meta{graphical code}}{no default}
  Appends the given \meta{graphical code} to \refKey{/tcb/title code}.
\end{docTcbKey}

\begin{docTcbKey}{title code pre}{=\meta{graphical code}}{no default}
  Prepends the given \meta{graphical code} to \refKey{/tcb/title code}.
\end{docTcbKey}



