diff options
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.tex | 197 |
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} |