diff options
Diffstat (limited to 'macros/latex/contrib/tcolorbox/tcolorbox.doc.coreoptions.tex')
-rw-r--r-- | macros/latex/contrib/tcolorbox/tcolorbox.doc.coreoptions.tex | 150 |
1 files changed, 133 insertions, 17 deletions
diff --git a/macros/latex/contrib/tcolorbox/tcolorbox.doc.coreoptions.tex b/macros/latex/contrib/tcolorbox/tcolorbox.doc.coreoptions.tex index 9144696d2c..e20936d76b 100644 --- a/macros/latex/contrib/tcolorbox/tcolorbox.doc.coreoptions.tex +++ b/macros/latex/contrib/tcolorbox/tcolorbox.doc.coreoptions.tex @@ -4,7 +4,11 @@ \section{Option Keys}\label{sec:optkeys}% \tcbset{external/prefix=external/coreoptions_}% For the \meta{options} in \refEnv{tcolorbox} respectively \refCom{tcbset} -the following |pgf| keys can be applied. The key tree path |/tcb/| is not to +the following |pgf| keys can be applied% +\footnote{Strictly speaking, they are \texttt{pgfkeys} keys. + The \texttt{pgfkeys} package is auto-loaded by \texttt{pgf} and is + documented in \cite[Part~VII]{tantau:tikz_and_pgf}.}. +The key tree path |/tcb/| is not to be used inside these macros. It is easy to add your own style keys using the syntax for |pgf| keys, see \cite{tantau:tikz_and_pgf,sturm:latex} or the examples starting from page~\pageref{sec:latextutorial}. @@ -272,8 +276,10 @@ This is a \textbf{tcolorbox} (but invisible). This is the counterpart of \refKey{/tcb/savelowerto}, but it saves not only the upper part but the whole content. If a lower part is present, it is also saved including \refCom{tcblower}. + An empty \meta{file name} deactivates \refKey{/tcb/saveto}. \begin{marker} - This option cannot be combined with \refKey{/tcb/savelowerto}. + This option cannot be combined with \refKey{/tcb/savelowerto} or + \refKey{/tcb/redirectlowerto}. \end{marker} \begin{exdispExample}{saveto_1} @@ -315,6 +321,12 @@ Now, we load the saved text: \item\docValue{ignored}: the lower part is not used (here). \end{itemize} The last two values are usually applied in connection with |savelowerto|. + + \begin{marker} + The lower part is always typeset into a box which is used or dropped + accordingly. The only exception is applying \refKey{/tcb/redirectlowerto}. + \end{marker} + \begin{exdispExample}{lowerbox} \begin{tcolorbox}[lowerbox=invisible,colback=white] This is a \textbf{tcolorbox}. @@ -331,8 +343,14 @@ This is the lower part (but ignored). \end{docTcbKey} +\clearpage \begin{docTcbKey}[][doc updated=2014-11-28]{savelowerto}{=\meta{file name}}{no default, initially empty} Saves the content of the lower part into a file for an optional later usage. + An empty \meta{file name} deactivates \refKey{/tcb/savelowerto}. + \begin{marker} + This option cannot be combined with \refKey{/tcb/saveto}. + \end{marker} + \begin{exdispExample}{savelowerto} \begin{tcolorbox}[lowerbox=invisible,savelowerto=\jobname_bspsave.tex,colback=white] This is a \textbf{tcolorbox}. @@ -346,18 +364,23 @@ Now, we load the saved text:\\ \end{exdispExample} \end{docTcbKey} +\medskip -\clearpage \begin{docTcbKey}[][doc new=2023-07-17]{redirectlowerto}{=\meta{file name}}{no default, initially empty} This is a combination of \refKey{/tcb/savelowerto} and \refKey{/tcb/lowerbox}|=|\docValue{ignored} \emph{and additionally} avoids typesetting the content of the lower part. This can be useful, if the lower part contains counters or similar. + An empty \meta{file name} deactivates the saving, but the \refKey{/tcb/lowerbox} + setting will still be \docValue{ignored}. + \begin{marker} + This option cannot be combined with \refKey{/tcb/saveto}. + \end{marker} \begin{exdispExample}{redirectlowerto} \setcounter{enumi}{1} Test counter: \theenumi -\begin{tcolorbox}[redirectlowerto=\jobname_bspsave.tex,colback=white] +\begin{tcolorbox}[redirectlowerto=\jobname_bspsave2.tex,colback=white] This is a \textbf{tcolorbox}. \tcblower This is the lower part.\stepcounter{enumi} @@ -365,7 +388,7 @@ New value of test counter: \theenumi. \end{tcolorbox} Now, we load the saved text:\\ -\input{\jobname_bspsave.tex} +\input{\jobname_bspsave2.tex} \end{exdispExample} \end{docTcbKey} @@ -425,7 +448,7 @@ This is the lower part. \clearpage \begin{docTcbKey}{savedelimiter}{=\meta{name}}{no default, initially \texttt{tcolorbox}} Used in connection with new environment definitions which extend - |tcolorbox| and use or allow the option |savelowerto|. + |tcolorbox| and use or allow the option \refKey{/tcb/savelowerto} or \refKey{/tcb/redirectlowerto}. To catch the end of the new box environment \meta{name} has to be the name of this environment. Additionally, the environment definition has to use |\tcolorbox| instead of @@ -433,7 +456,7 @@ This is the lower part. \begin{exdispExample}{savedelimiter1} \newenvironment{mybox}[1]{% \tcolorbox[savedelimiter=mybox, - savelowerto=\jobname_bspsave2.tex,lowerbox=ignored, + savelowerto=\jobname_bspsave3.tex,lowerbox=ignored, colback=red!5!white,colframe=red!75!black,fonttitle=\bfseries, title={#1}]}% {\endtcolorbox} @@ -446,17 +469,17 @@ Saved lower part! Now, the saved part is used: \begin{tcolorbox}[colback=green!5] -\input{\jobname_bspsave2.tex} +\input{\jobname_bspsave3.tex} \end{tcolorbox} \end{exdispExample} \enlargethispage*{1cm} -The |savedelimiter| is used implicitely with \refCom{newtcolorbox} which +The |savedelimiter| is used implicitly with \refCom{newtcolorbox} which allows a more convenient usage: \begin{exdispExample}{savedelimiter2} \newtcolorbox{mybox}[1]{% - savelowerto=\jobname_bspsave2.tex,lowerbox=ignored, + savelowerto=\jobname_bspsave4.tex,lowerbox=ignored, colback=red!5!white,colframe=red!75!black,fonttitle=\bfseries, title={#1}}% @@ -468,7 +491,7 @@ Saved lower part! Now, the saved part is used: \begin{tcolorbox}[colback=green!5] -\input{\jobname_bspsave2.tex} +\input{\jobname_bspsave4.tex} \end{tcolorbox} \end{exdispExample} \end{docTcbKey} @@ -2631,6 +2654,99 @@ Lower part. \end{exdispExample*} \end{docTcbKey} +\clearpage + +\begin{docTcbKeys}[ + doc new = 2023-10-16, + doc description = style, + ] + { + { doc name = environment upper, doc parameter={=\meta{name}} }, + { doc name = environment upper args, doc parameter={=\marg{name}\marg{code}} } + } + This shortcut style sets \refKey{/tcb/before upper*} + to |\begin|\marg{name} and \refKey{/tcb/after upper*} + to |\end|\marg{name}, i.e. the upper part is enclosed by the environment \meta{name}. + The second variant also places \meta{code} after |\begin|\marg{name}. +\begin{exdispExample}{environment_upper_1} +\begin{tcolorbox}[colback=yellow!30, colframe=yellow!80!black, + environment upper=itemize +] + \item one + \item two +\end{tcolorbox} +\end{exdispExample} + Note that you may need \emph{additional} brackets around \meta{code}, if + \meta{code} contains some para\-meter(s) for the environment \meta{name}. +\begin{exdispExample}{environment_upper_2} +\begin{tcolorbox}[center upper, + colback=yellow!30, colframe=yellow!80!black, + environment upper args={tabular}{{cc}} +] + one & two \\ + three & four\\ +\end{tcolorbox} +\end{exdispExample} +\begin{exdispExample}{environment_upper_3} +\begin{tcolorbox}[colback=yellow!30, colframe=yellow!80!black, + environment upper args = {list}{{\bfseries Fact:} + {\setlength\itemsep{0pt}\setlength\parsep{0pt}}}, +] + \item Blue is red + \item Red is green +\end{tcolorbox} +\end{exdispExample} +\end{docTcbKeys} + + +\begin{marker} +\refKey{/tcb/environment upper} and friends (following) cannot be used to +wrap another |tcolorbox|-based environment, i.e. never use +|/tcb/environment upper=tcolorbox| or +|/tcb/environment upper=etc-derived-from-tcolorbox|. +\end{marker} + + +\clearpage + +\begin{docTcbKeys}[ + doc new = 2023-10-16, + doc description = style, + ] + { + { doc name = environment lower, doc parameter={=\meta{name}} }, + { doc name = environment lower args, doc parameter={=\marg{name}\marg{code}} } + } + This shortcut style sets \refKey{/tcb/before lower*} + to |\begin|\marg{name} and \refKey{/tcb/after lower*} + to |\end|\marg{name}, i.e. the lower part is enclosed by the environment \meta{name}. + The second variant also places \meta{code} after |\begin|\marg{name}. + Note that you may need \emph{additional} brackets around \meta{code}, if + \meta{code} contains some para\-meter(s) for the environment \meta{name}. + + See \refKey{/tcb/environment upper} for analog examples. +\end{docTcbKeys} + + +\begin{docTcbKeys}[ + doc new = 2023-10-16, + doc description = style, + ] + { + { doc name = environment title, doc parameter={=\meta{name}} }, + { doc name = environment title args, doc parameter={=\marg{name}\marg{code}} } + } + This shortcut style sets \refKey{/tcb/before title*} + to |\begin|\marg{name} and \refKey{/tcb/after title*} + to |\end|\marg{name}, i.e. the title text is enclosed by the environment \meta{name}. + The second variant also places \meta{code} after |\begin|\marg{name}. + Note that you may need \emph{additional} brackets around \meta{code}, if + \meta{code} contains some para\-meter(s) for the environment \meta{name}. + + See \refKey{/tcb/environment upper} for analog examples. +\end{docTcbKeys} + + \clearpage \subsection{Overlays}\label{subsec:overlays} @@ -3848,7 +3964,7 @@ in the following order. Following options overwrite preceding options. \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. + and by the surrounding 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, @@ -4013,7 +4129,7 @@ This is a tcolorbox. \clearpage \subsection{Text Characteristics} -\begin{docTcbKey}[][doc updated=2015-10-14]{parbox}{\colOpt{=true\textbar false}}{default |true|, initially |true|} +\begin{docTcbKey}[][doc updated=2024-01-10]{parbox}{\colOpt{=true\textbar false}}{default |true|, initially |true|} The text inside a |tcolorbox| is formatted using a \LaTeX\ |minipage| if the box is unbreakable. If breakable, the box tries a mimicry of a |minipage|. In a |minipage| or |parbox|, paragraphs are formatted slightly different @@ -4072,7 +4188,7 @@ targeting different box types and they do not blend very well. \subsection{Files} \begin{docTcbKey}{tempfile}{=\meta{file name}}{no default, initially \cs{jobname.tcbtemp}} Sets \meta{file name} as name for the temporary file which is used inside - \refEnv{tcbwritetemp} and \refCom{tcbusetemp} implicitely. + \refEnv{tcbwritetemp} and \refCom{tcbusetemp} implicitly. \end{docTcbKey} \clearpage @@ -4430,7 +4546,7 @@ of a page. \refKey{/tcb/toggle enlargement}, and \refKey{/tcb/if odd page} automatically set |check odd page|, but for -\refCom{tcbifoddpage} this option has to be set explicitely. +\refCom{tcbifoddpage} this option has to be set explicitly. \end{docTcbKey} \enlargethispage*{1cm} @@ -4451,7 +4567,7 @@ If a box is \refKey{/tcb/breakable}, using \refKey{/tcb/if odd page} only acts upon the \emph{first} box. If the setting should be repeated for every partial box of the break sequence, the option should be packed into \refKey{/tcb/extras}. In this case, \refKey{/tcb/check odd page} -has to be set explicitely! Also see \refKey{/tcb/if odd page*}. +has to be set explicitly! Also see \refKey{/tcb/if odd page*}. \end{marker} \end{docTcbKey} @@ -4638,7 +4754,7 @@ Sets (nearly) all |tcolorbox| settings (including loaded libraries) back to thei \emph{plus} any settings given by \refCom{tcbsetforeverylayer}. \refKey{/tcb/savedelimiter}, \refKey{/tcb/capture}, and \refKey{/tcb/shield externalize} keep their values. -Also, all raster values (see \Vref{sec:raster}) are not resetted. +Also, all raster values (see \Vref{sec:raster}) are not reset. This option is useful for boxes in boxes where the inner box should not inherit the settings of the outer box. |