% !TeX root = tcolorbox.tex
% include file of tcolorbox.tex (manual of the LaTeX package tcolorbox)
\clearpage
\section{Initialization Option Keys}\label{sec:initkeys}%
\tcbset{external/prefix=external/initoptions_}%
The \emph{initialization} options are only applicable for the generation
of new environments and commands based on |tcolorbox| and friends.
Particularly, they can be used for
\begin{itemize}
\item\refCom{newtcolorbox}, \refCom{NewTColorBox}, \refCom{NewTotalTColorBox},
\item\refCom{newtcbox}, \refCom{NewTCBox}, \refCom{NewTotalTCBox},
\item\refCom{newtcblisting}, \refCom{NewTCBListing},
\item\refCom{newtcbinputlisting}, \refCom{NewTCBInputListing},
\item\refCom{newtcbtheorem}, \refCom{NewTcbTheorem},
\item\refCom{newtcboxfit}, \refCom{NewTCBoxFit}, \refCom{NewTotalTCBoxFit},
\end{itemize}
and friends like \refCom{renewtcolorbox}, etc.

\bigskip
\begin{marker}
Typically, these options may generate counters and alike.
It is \textbf{strongly} recommended that you use initialization options inside
the preamble only. Otherwise, you may get trouble when using \LaTeX's |\include| features.
Also, it is recommended to generate new environments and commands with these
options \emph{after} |hyperref| is loaded to avoid warnings about
\emph{duplicate identifiers}.
\end{marker}


\subsection{Numbered Boxes}\label{sec:numberedboxes}
Counters assigned using the initialization options are administrated
automatically. Especially, they are increased for each new box.
Independent from the real counter name, the counter value can be
referenced by \docAuxCommand{thetcbcounter}, e.\,g.\ inside the title of
the box. The real counter name is stored inside \docAuxCommand{tcbcounter}.

\begin{newTcbKey}{auto counter}{}{no value, initially unset}
Creates a new counter automatically.
With \refKey{/tcb/new/number format} and
\refKey{/tcb/new/number within}, the appearance and behavior of the counter
can be changed. The counter value is referenced by \docAuxCommand{thetcbcounter}.

\inputpreamblelisting{A}

\begin{dispExample}
\begin{pabox}[label={myautocounter}]{Title with number}
This box is automatically numbered with \ref{myautocounter} on page
\pageref{myautocounter}. Inside the box, the \thetcbcounter\ can
also be referenced by |\thetcbcounter|.
The real counter name is \texttt{\tcbcounter}.
\end{pabox}
\end{dispExample}
\end{newTcbKey}

\clearpage
\begin{newTcbKey}{use counter from}{=\meta{tcolorbox}}{no default, initially unset}
Here, a counter from another \meta{tcolorbox} is reused.
Note that the settings for \refKey{/tcb/new/number format} and
\refKey{/tcb/new/number within} are inherited and cannot be changed.
The counter value is referenced by \docAuxCommand{thetcbcounter}.

\begin{dispExample}
\newtcolorbox[use counter from=pabox]{mybox}[2][]{%
colback=blue!5!white,colframe=blue!75!black,fonttitle=\bfseries,
title=Some Box \thetcbcounter: #2,#1}

\begin{mybox}[label={myusecounterfrom}]{Title with continued number}
This box is automatically numbered with \ref{myusecounterfrom} on page
\pageref{myusecounterfrom}. Inside the box, the \thetcbcounter\ can
also be referenced by |\thetcbcounter|.
The real counter name is \texttt{\tcbcounter}.
\end{mybox}
\end{dispExample}
\end{newTcbKey}


\begin{newTcbKey}{use counter}{=\meta{counter}}{no default, initially unset}
Here, an ordinary existing \LaTeX\ \meta{counter} is used for numbering.
With \refKey{/tcb/new/number format} and
\refKey{/tcb/new/number within}, the appearance and behavior of the counter
can be changed. The counter value is referenced by \docAuxCommand{thetcbcounter}.

\begin{dispExample}
% \newcounter{myexample}%  preamble
\newtcolorbox[use counter=myexample,number format=\Alph]{mybox}[2][]{%
colback=green!5!white,colframe=green!55!black,fonttitle=\bfseries,
title=Some Box \thetcbcounter: #2,#1}

\begin{mybox}[label={myusecounter}]{Title with \LaTeX\ number}
This box is automatically numbered with \ref{myusecounter} on page
\pageref{myusecounter}. Inside the box, the \thetcbcounter\ can
also be referenced by |\thetcbcounter|.
The real counter name is \texttt{\tcbcounter}.
\end{mybox}
\end{dispExample}
\end{newTcbKey}


\begin{newTcbKey}[][doc new=2014-09-19]{use counter*}{=\meta{counter}}{no default, initially unset}
An existing \LaTeX\ \meta{counter} is used for numbering. In contrast to
\refKey{/tcb/new/use counter}, the options \refKey{/tcb/new/number format} and
\refKey{/tcb/new/number within} are ignored. Use this for counters which
are already configured outside the |tcolorbox| package, e.\,g.\ the standard
|figure| counter.
\end{newTcbKey}


\begin{newTcbKey}{no counter}{}{no value, initially set}
The created boxes are not numbered. This is the default. The option may
be used to overrule a previous option.
\end{newTcbKey}

\enlargethispage*{1cm}

\begin{newTcbKey}[][doc new=2019-10-18]{reset counter on overlays}{\colOpt{=true\textbar false}}{default |true|, initially |false|}
For |beamer| slides, this invokes the |\resetcounteronoverlays| command
for the box counter. The counter is automatically reset on subsequent
overlay slides of a frame.
Thereby, the counter will be the same on all slides of every frame.
\end{newTcbKey}


\clearpage
\begin{newTcbKey}{number within}{=\meta{counter}}{no default, initially unset}
The automatic counter is set to zero, if \meta{counter} is increased.
Additionally, during output, the value of \meta{counter} is prepended to the value of
the automatic counter.\par
To prepend the automatic counter with the chapter number and to reset it
with every new chapter, use:
\begin{dispListing}
number within=chapter
\end{dispListing}
See \refKey{/tcb/new/use counter} for a complete example.
\end{newTcbKey}


\begin{newTcbKey}{number format}{=\meta{format macro}}{no default, initially \texttt{\textbackslash arabic}}
Declares the format of the automatic counter. The \meta{format macro} can be
any valid \LaTeX\ number formatting macro like |\arabic|, |\roman|, etc.\par
To display the counter value in large roman numbers, use:
\begin{dispListing}
number format=\Roman
\end{dispListing}
See \refKey{/tcb/new/auto counter} for a complete example.
\end{newTcbKey}


\begin{newTcbKey}{number freestyle}{=\meta{code}}{no default, initially unset}
Allows advanced control over the complete number format. This option overrules
the format given by \refKey{/tcb/new/number within} and \refKey{/tcb/new/number format}.
Nevertheless, you can combine it with \refKey{/tcb/new/number within} to
get the desired reset property.\par
The \meta{code} is some formatting code which should contain |\tcbcounter| to
reference the automated counter. Since this \meta{code} is expanded, you have
to secure each macro with |\noexpand| with \emph{exception} of |\tcbcounter|.

\inputpreamblelisting{H}

\begin{dispExample}
\begin{phbox}[label={myfreestyle}]{Title with freestyle number}
This box is automatically numbered with \ref{myfreestyle} on page
\pageref{myfreestyle}. Inside the box, the \thetcbcounter\ can
also be referenced by |\thetcbcounter|.
The real counter name is \texttt{\tcbcounter}.
\end{phbox}
\end{dispExample}
\end{newTcbKey}

\clearpage
\begin{marker}
The following options \refKey{/tcb/new/crefname} and \refKey{/tcb/new/Crefname}
need to be set inside the preamble.
\end{marker}

\begin{newTcbKey}[][doc updated=2014-12-01]{crefname}{=\marg{singular}\marg{plural}}{no default, initially unset}
  This option key can be used only in conjunction with the |cleveref| package
  \cite{cubitt:2018a} which has to be loaded separately.
  It creates a cross-reference type for the new |tcolorbox|'es, where the
  lowercase \meta{singular} and \meta{plural} forms of the cross-reference are given.
  This type is the environment or macro name and \refKey{/tcb/label type} is set automatically.
  See \refKey{/tcb/label type} and \cite{cubitt:2018a} for more information.
\end{newTcbKey}


\begin{newTcbKey}[][doc updated=2014-12-01]{Crefname}{=\marg{singular}\marg{plural}}{no default, initially unset}
  This option key can be used only in conjunction with the |cleveref| package
  \cite{cubitt:2018a} which has to be loaded separately.
  It creates a cross-reference type for the new |tcolorbox|'es, where the
  uppercase \meta{singular} and \meta{plural} forms of the cross-reference are given.
  This type is the environment or macro name and \refKey{/tcb/label type} is set automatically.
  See \refKey{/tcb/label type} and \cite{cubitt:2018a} for more information.
\end{newTcbKey}

\inputpreamblelisting{I}
\begin{dispExample}
% \usepackage{varioref}
% \usepackage{cleveref}
\begin{mybluebox}[label={myreference}]{My title}
This is an example.
\end{mybluebox}

\Cref{myreference}, \cref{myreference}.\\
\Cpageref{myreference}, \cpageref{myreference}.\\
\nameCref{myreference}, \namecref{myreference}.\\
\labelcref{myreference}, \labelcpageref{myreference}.\\
With \texttt{varioref}:\\
\Vref{myreference}, \vref{myreference}.\\
\Vref*{myreference}, \vref*{myreference}.
\end{dispExample}

\clearpage

\begin{newTcbKey}[][doc new and updated={2014-09-19}{2023-07-03}]{blend into}{=\meta{name}}{style, no default, initially unset}
Used to comfortably blend into an existing schema of naming and numbering for
some selected cases. For example, a |tcolorbox| can be used to display
and entitle an image pretending to be a standard |figure| environment.
Here, \refKey{/tcb/title} is used instead of the standard |\caption|
and \refKey{/tcb/list text} can be used instead of the optional parameter
of the standard |\caption|.
Also, \refKey{/tcb/new/list type} is automatically adapted (changed with version 6.0.5).

Feasible values for \meta{name} are:
\begin{itemize}
\item\docValue{figures}: blend into the standard |figure| environment.
\item\docValue{tables}: blend into the standard |table| environment.
\item\docValue{listings}: blend into the standard |lstlisting| environment
  of the package |listings| \cite{hoffmann:listings}.
  \begin{marker}
  Note that |blend into=listings| can only be used in the document content
  or, preferably, inside a |\AtBeginDocument| clause! Using it without
  |\AtBeginDocument| inside the preamble does not work since the |listings|
  packages initializes its counter also inside |\AtBeginDocument|.
  \end{marker}
\end{itemize}
\end{newTcbKey}

\enlargethispage*{5cm}
\begin{dispListing}
\begin{figure}[htb]
  \centering\includegraphics[height=4cm]{lichtspiel.jpg}
  \caption{A standard figure}
\end{figure}

\newtcolorbox[blend into=figures]{myfigure}[2][]{float=htb,capture=hbox,
  title={#2},every float=\centering,#1}

\begin{myfigure}{A tcolorbox figure}
  \includegraphics[height=4cm]{lichtspiel.jpg}
\end{myfigure}
\end{dispListing}
{\tcbusetemp}



\clearpage
\begin{docTcbKey}[][doc new=2015-03-13]{blend before title}{=\meta{value}}{no default, initially \docValue{colon}}
  This option formats the title output of \refKey{/tcb/new/blend into}.
  Note that this is a common |tcolorbox| option which should be set
  globally or in the normal option part of \refCom{newtcolorbox}.

Feasible values for \meta{value} are:
\begin{itemize}
\item\docValue{colon}: use name/number plus colon.
\item\docValue{dash}: use name/number plus dash.
\item\docValue{colon hang}: use name/number plus colon with hanging indent.
\item\docValue{dash hang}: use name/number plus dash with hanging indent.
\end{itemize}

\begin{dispListing}
\newtcolorbox[blend into=figures]{myfigure}[2][]{float=htb,capture=hbox,
  blend before title=dash hang,title={#2},every float=\centering,#1}

\begin{myfigure}{A tcolorbox figure with quite a long title}
  \includegraphics[height=5cm]{lichtspiel.jpg}
\end{myfigure}
\end{dispListing}
{\tcbusetemp}
\end{docTcbKey}

\clearpage
\begin{docTcbKey}[][doc new=2015-03-13]{blend before title code}{=\meta{code}}{no default}
  This option formats the title output of \refKey{/tcb/new/blend into}.
  The \meta{code} takes one parameter, the name/number.
  Use this, if \refKey{/tcb/blend before title} is not flexible enough.

\begin{dispListing}
\newtcolorbox[blend into=figures]{myfigure}[2][]{float=htb,capture=hbox,
  blend before title code={\fbox{##1}\ },title={#2},every float=\centering,#1}

\begin{myfigure}{A tcolorbox figure}
  \includegraphics[height=6cm]{lichtspiel.jpg}
\end{myfigure}
\end{dispListing}
{\tcbusetemp}
\end{docTcbKey}



\clearpage
\subsection{Lists of \texttt{tcolorbox}es}\label{sec:listsof}
For figures and tables, \LaTeX\ provides the |\listoffigures| and
|\listoftables| commands to create lists of these numbered entities.
Also, a |tcolorbox| can be part of such a kind of list.
\begin{enumerate}
\item Assign a list \meta{name} by the \emph{initialization} option
  \refKey{/tcb/new/list inside}.
\item Optionally, a new \meta{type} for list entries may be assigned
  by the \emph{initialization} option \refKey{/tcb/new/list type}.
\item List entries a generated automatically within each new |tcolorbox|
  using the above initialization.
  \begin{itemize}
  \item If \refKey{/tcb/list entry} is set, the entry is generated with it.
  \item Otherwise, if \refKey{/tcb/title} is set, the entry is generated with it.
  \item Otherwise, the entry is generated with the current number and the environment name.
  \end{itemize}
\item The generated list is displayed by \refCom{tcblistof}.
\end{enumerate}

\begin{newTcbKey}{list inside}{=\meta{name}}{no default, initially unset}
Assigns a list or contents file to the generated |tcolorbox|es.
Entries to this list are saved to a file which gets the \meta{name} as
file name extension. The list is referenced by this name in
\refCom{tcblistof}.
For example:
\begin{dispListing}
list inside=exam
\end{dispListing}
See Section \ref{listing:exercises} from page \pageref{listing:exercises}
for a complete example.
\end{newTcbKey}


\begin{newTcbKey}{list type}{=\meta{type}}{no default, initially |tcolorbox|}
Optionally, some \meta{type} can be assigned to the list entries.
For a new \meta{type}, a macro |\l@|\meta{type} has to exist which controls
the format of the list entry. The default type is defined by
\begin{dispListing}
\newcommand*\l@tcolorbox{\@dottedtocline{1}{1.5em}{2.3em}}
\end{dispListing}
This is identical to the |\l@section| setting of \LaTeX. |\l@tcolorbox| can
be redefined or a new \meta{type} can be assigned.
\end{newTcbKey}


\clearpage
\begin{docCommand}[doc updated=2021-05-20]{tcblistof}{\oarg{macro}\marg{name}\oarg{short}\marg{title text}}
Displays the generated list of |tcolorbox|es with the given \meta{name}.
The heading is generated by \meta{macro}\oarg{short}\marg{title text} where \texttt{\textbackslash section}
is the default setting for \meta{macro}.
Here, as usual, \meta{title text} is the title of the section or chapter
while \meta{short} is a shorter title for headings and table of contents.
\begin{itemize}
\item If \meta{macro} ends with a |*|, \refCom{tcblistof} mimics the behavior of
  |\listoffigures| from the standard \LaTeX\ classes and adds the title
  to the left and right mark for headings.
\item If \meta{macro} starts with |\chapter|, a possible two column document setting
  is restored to one column (as standard \LaTeX\ classes do for |\listoffigures|).
\end{itemize}

\medskip
To display the list inside a subsection, use for example:
\begin{dispListing}
\tcblistof[\subsection]{exam}{List of Exercises}
\end{dispListing}
The result of the example is found as Subsection \ref{listofexercises} on
page \pageref{listofexercises}.

\medskip
To apply the list similar to |\listoffigures| for a report or book, use for example:
\begin{dispListing}
\tcblistof[\chapter*]{exam}{List of Exercises}
\end{dispListing}

\medskip
To set a short title for headings with the default |\section| setting, use for example:
\begin{dispListing}
\tcblistof{exam}[List of Exercises]{Elaborate List of Fine Exercises
                                    for all Students of my Course}
\end{dispListing}

\begin{marker}
The core of the list is generated by |\@starttoc|\marg{name} which
can be wrapped into an own macro.
\end{marker}
\end{docCommand}

\clearpage

\begin{marker}
The following options are not initialization options, but common options,
which are typically reasonable in connection with lists of |tcolorbox|es.
\end{marker}

\begin{docTcbKey}{list entry}{=\meta{text}}{no default, initially unset}
If the \flqq list of tcolorbox(es)\frqq\ feature described in
%Subsection \ref{sec:listsof} from page \pageref{sec:listsof}
the current subsection
is used, this key
describes the \meta{text} for an entry into the generated list, e.\,g.
\begin{dispListing}
list entry={\protect\numberline{\thetcbcounter}My beautiful Example}
\end{dispListing}
See Section \ref{listing:exercises} from page \pageref{listing:exercises}
for a complete example.\par
If |\thetcbcounter| is omitted, \refKey{/tcb/list entry} could be used for
unnumbered boxes too.
\begin{marker}
This is a customization option. For numbered boxes, \refKey{/tcb/list entry}
typically has not to be given, because this entry will be generated automatically.
\end{marker}
\end{docTcbKey}

\begin{docTcbKey}[][doc new=2014-09-19]{list text}{=\meta{text}}{style, no default}
This is a shortcut for setting \refKey{/tcb/list entry} to\\
|\protect\numberline{\thetcbcounter}|\meta{text}.
So, the following settings are identical:
\begin{dispListing}
list text={My beautiful Example},
list entry={\protect\numberline{\thetcbcounter}My beautiful Example}
\end{dispListing}
See Section \ref{listing:exercises} from page \pageref{listing:exercises}
for a complete example.
\end{docTcbKey}

\begin{docTcbKey}{add to list}{=\marg{list}\marg{type}}{no default, initially unset}
If the \flqq list of tcolorbox(es)\frqq\ feature described in
%Subsection \ref{sec:listsof} from page \pageref{sec:listsof}
the current subsection
is used, list entries are
generated automatically. With this key, you can enforce an entry to the
given \meta{list} with the given \meta{type}.
This issues:\par
|\addcontentsline|\marg{list}\marg{type}\marg{entry text}\par
\meta{entry text} may be given by \refKey{/tcb/list entry}.
\begin{marker}
This is a customization option. For numbered boxes, this feature is configured
automatically, where
\meta{list} is set by \refKey{/tcb/new/list inside} and
\meta{type} is set by \refKey{/tcb/new/list type}
\end{marker}
\end{docTcbKey}