summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/tcolorbox/tcolorbox.doc.coreoptions.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/latex/tcolorbox/tcolorbox.doc.coreoptions.tex')
-rw-r--r--Master/texmf-dist/doc/latex/tcolorbox/tcolorbox.doc.coreoptions.tex197
1 files changed, 181 insertions, 16 deletions
diff --git a/Master/texmf-dist/doc/latex/tcolorbox/tcolorbox.doc.coreoptions.tex b/Master/texmf-dist/doc/latex/tcolorbox/tcolorbox.doc.coreoptions.tex
index c220d7ceb70..c96326f8f5e 100644
--- a/Master/texmf-dist/doc/latex/tcolorbox/tcolorbox.doc.coreoptions.tex
+++ b/Master/texmf-dist/doc/latex/tcolorbox/tcolorbox.doc.coreoptions.tex
@@ -1357,10 +1357,9 @@ are drawn by the codes given with
%\newlength{\examlen}
\colorlet{colexam}{red!75!black}
-\newtcolorbox{myexample}{%
- phantom={\refstepcounter{example}%
- \settowidth{\global\examlen}{\Large\bfseries Example \arabic{example}}},%
- title={Example \arabic{example}},
+\newtcolorbox[use counter=example]{myexample}{%
+ phantom={\settowidth{\global\examlen}{\Large\bfseries Example \thetcbcounter}},%
+ title={Example \thetcbcounter},
coltitle=colexam,fonttitle=\Large\bfseries,
enhanced,breakable,before=\par\medskip,parbox=false,
frame hidden,interior hidden,segmentation hidden,
@@ -1396,17 +1395,16 @@ are drawn by the codes given with
\begin{dispExample}
% \tcbuselibrary{skins}
% \newcounter{example}
-\newtcolorbox{FancyTitle}[3][]{%
+\newtcolorbox[use counter=example]{FancyTitle}[3][]{%
enhanced,colback=blue!10!white,colframe=orange,top=4mm,
enlarge top by=\baselineskip/2+1mm,
enlarge top at break by=0mm,pad at break=2mm,
- fontupper=\normalsize,
- step and label={example}{#3},
+ fontupper=\normalsize,label={#3},
overlay unbroken and first={%
\node[rectangle,rounded corners,draw=black,fill=blue!20!white,
inner sep=1mm,anchor=west,font=\small]
at ([xshift=4.5mm]frame.north west)
- {\strut\textbf{Example \arabic{example}: #2}};},
+ {\strut\textbf{Example \thetcbcounter: #2}};},
#1}%
\begin{FancyTitle}{My fancy title}{fancy:title}
@@ -1885,6 +1883,133 @@ et malesuada fames ac turpis egestas. \tcbox{Mauris ut leo.}
\end{dispExample}
\end{docTcbKey}
+\clearpage
+\subsection{Layered Boxes and Every Box Settings}\label{subsec:everybox}
+A |tcolorbox| may contain another |tcolorbox| and so on. The package
+takes track of the nesting level using a counter |tcblayer|. Counter values
+may be used for doing some fancy things, but you should never change
+the counter value yourself.
+
+The package takes special care for the first four layers or nesting levels,
+called managed layers.
+Here, footnote texts are administrated to find their intended place
+and specific layer dependent options may be set by changing
+\refKey{/tcb/every box on layer n}.
+If needed, the number of managed layers can be increased by setting
+\refCom{tcbsetmanagedlayer} to a higher value than 4.
+
+The following styles have a considerable influence on how layered boxes
+are processed. Note especially that nested boxes are getting a
+\refKey{/tcb/reset} by default. You can change this, but be prepared for
+suprises if you do.
+
+If the defaults are \emph{not changed}, a |tcolorbox| gets its options
+in the following order. Following options overwrite preceding options.
+\begin{enumerate}
+\item On package load, all options are set to default values.
+\item Every \refCom{tcbset} command adds or changes options for the following boxes
+ inside the current \TeX\ group.
+\item While entering a |tcolorbox|, a \refKey{/tcb/every box on layer n} or
+ \refKey{/tcb/every box on higher layers} option list is applied.
+ With default settings this means:
+ \begin{itemize}
+ \item For layer 1 (lowest layer), the \refKey{/tcb/every box} option list is applied.
+ Not overwritten options given by a preceding \refCom{tcbset} survive.
+ \item For layer 2 and above (nested boxes), a \refKey{/tcb/reset} followed by
+ \refKey{/tcb/every box} option list is applied.
+ Every resettable options given by a preceding \refCom{tcbset}
+ and by the sourrounding box(es) are reset.
+ \end{itemize}
+\item The \meta{options} given to the |tcolorbox| are applied.
+ Or, if the box was generated by \refCom{newtcolorbox} or friends,
+ the \meta{options} given there are applied.
+\item If the box was generated by \refCom{newtcolorbox} or friends,
+ some automated options are applied.
+\end{enumerate}
+
+
+\begin{docTcbKey}{every box}{}{style}
+By default, this style is empty.
+\begin{dispListing}
+% default setting:
+\tcbset{every box/.style={}}
+\end{dispListing}
+It may be changed by redefining this style.
+\begin{dispListing}
+% setting all boxes to be enhanced:
+\tcbset{every box/.style={enhanced}}
+\end{dispListing}
+\end{docTcbKey}
+
+\clearpage
+\begin{docTcbKey}{every box on layer n}{}{style}
+Here, |n| has to be replaced by a number ranging from 1 to the highest
+managed layer number (4 by default).
+\begin{dispListing}
+% default settings:
+\tcbset{
+ every box on layer 1/.style={every box},
+ every box on layer 2/.style={reset,every box},
+ every box on layer 3/.style={reset,every box},
+ every box on layer 4/.style={reset,every box},
+ }
+\end{dispListing}
+\end{docTcbKey}
+
+
+\begin{docTcbKey}{every box on higher layers}{}{style}
+Higher layers are layers above the highest
+managed layer number (4 by default).
+\begin{dispListing}
+\tcbset{every box on higher layers/.style={reset,every box}}
+\end{dispListing}
+\end{docTcbKey}
+
+
+\begin{docCommand}{tcbsetmanagedlayer}{\marg{number}}
+Replaces the highest managed layer number by \meta{number} where 4 is
+the default. This macro can only be used inside the preamble.
+Using a \meta{number} lower than 4 typically makes no sense, but is
+not forbidden.
+\end{docCommand}
+
+\begin{tcboutputlisting}
+% \usepackage{lipsum}
+% \tcbuselibrary{skins,breakable}
+\tcbset{enhanced,breakable,colframe=red!75!black,fonttitle=\bfseries,
+ colback=red!5!white,
+ every box/.style={enhanced,watermark text=\thetcblayer,
+ before=\par\smallskip,after=\par\smallskip},
+ every box on layer 2/.style={reset,every box,colback=yellow!10!white,
+ drop fuzzy shadow}}
+\begin{tcolorbox}[title=Layer 1 Box]
+Here comes a footnote\footnote{Footnote from layer 1 box}.
+\lipsum[2]
+ \begin{tcolorbox}[title=Layer 2 Box]
+ abc\footnote{The footnote of abc}
+ \end{tcolorbox}
+ \begin{tcolorbox}[title=Another Box,ams equation]
+ \tcbhighmath{\sum\limits_{n=1}^{\infty} \frac{1}{n}} = \infty.
+ \end{tcolorbox}
+Some text\footnote{Footnote from some text}.
+ \begin{tcolorbox}[title=Yet Another Box]
+ \tcboxfit[height=2cm]{\lipsum[1]}
+ My text.
+ \begin{tcolorbox}
+ Another lipsum text\footnote{A lipsum text}. \lipsum[3]
+ \begin{tcolorbox}[title=Layer 4,colframe=blue,colback=white]
+ Layer 4\footnote{Layer 4 footnote}
+ \end{tcolorbox}
+ The End\footnote{Last footnote}.
+ \end{tcolorbox}
+ \end{tcolorbox}
+\end{tcolorbox}
+\end{tcboutputlisting}
+
+\tcbinputlisting{base example,listing only,listing style=mydocumentation}
+
+{\tcbuselistingtext}
+
\clearpage
\subsection{Capture Mode}\label{subsec:capture}
@@ -2013,12 +2138,13 @@ the core package are therefore described in section \ref{sec:skincorekeys} from
page \pageref{sec:skincorekeys}.
\clearpage
-\subsection{Counters and Page References}
+\subsection{Counters, Labels and References}
\begin{docTcbKey}{phantom}{=\meta{code}}{no default, initially unset}
The \meta{code} is put in a box at the upper left corner of the |tcolorbox|.
If the |tcolorbox| is breakable, the \meta{code} is executed for the first box of
-the break sequence only.\par
+the break sequence only. If there already was some phantom code given, the
+new \meta{code} is appended.\par
The \meta{code} is intended to be used for counter stepping, labelling, and
related operations which do not produce visible text.
\begin{itemize}
@@ -2042,14 +2168,50 @@ Example \ref{exe:tabular_example} on page \pageref{exe:tabular_example}.
Removes the phantom code if set before.
\end{docTcbKey}
+\begin{docTcbKey}{label}{=\meta{marker}}{no default, initially unset}
+Shortcut for |phantom={\label{#1}}|. The \meta{marker} is set as label text
+for a reference with the |\ref| macro.
+Typically, this option is used for numbered boxes, see Subsection \ref{sec:numberedboxes}
+from page \pageref{sec:numberedboxes}, e.\,g.\ \refKey{/tcb/new/auto counter}.
+\end{docTcbKey}
+
+\begin{docTcbKey}{step}{=\meta{counter}}{no default, initially unset}
+Shortcut for |phantom={\refstepcounter{#1}}|. The given \meta{counter} is
+increased and ready for labelling. This option is not needed when
+using the convenient automated numbering introduced with version 2.40,
+see Subsection \ref{sec:numberedboxes}
+from page \pageref{sec:numberedboxes}.
+\end{docTcbKey}
+
\begin{docTcbKey}{step and label}{=\marg{counter}\marg{marker}}{no default, initially unset}
-Shortcut for |phantom={\refstepcounter{#1}\label{#2}}|. The \meta{counter} is
-increased and the \meta{marker} is set as label text.\par
-Examples for the |phantom| usage are given in Section \ref{sec:latextutorial}
-from page \pageref{sec:latextutorial}, e.\,g.\
-Example \ref{firstExample} on page \pageref{firstExample}.
+Shortcut for using \refKey{/tcb/step} and \refKey{/tcb/label}. This option is not needed when
+using the convenient automated numbering introduced with version 2.40,
+see Subsection \ref{sec:numberedboxes}
+from page \pageref{sec:numberedboxes}.
\end{docTcbKey}
+
+\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} is used, this key
+describes the \meta{text} for an entry into the generated list, e.\,g.
+\begin{dispListing}
+list entry={\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} 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:\\
+|\addcontentsline|\marg{list}\marg{type}\marg{entry text}
+\end{docTcbKey}
+
+
\clearpage
\begin{docTcbKey}{check odd page}{\colOpt{=\meta{boolean value}}}{default |true|, initially |false|}
If set to |true|, the even/odd page testing from the package |changepage|
@@ -2127,5 +2289,8 @@ Sets (nearly) all |tcolorbox| settings (including loaded libraries) back to thei
\refKey{/tcb/savedelimiter} and \refKey{/tcb/capture} keep their values.
This option is useful for boxes in boxes where the inner box should not inherit
the settings of the outer box.
-See \refCom{tcbhighmath} for an example.
+Note that for boxes inside boxes the |reset| is done automatically, if the
+standard settings of the package are used (v2.40 and above), see
+Section \ref{subsec:everybox} from page \pageref{subsec:everybox}.
+%See \refCom{tcbhighmath} for an example.
\end{docTcbKey}