diff options
author | Norbert Preining <norbert@preining.info> | 2019-09-02 13:46:59 +0900 |
---|---|---|
committer | Norbert Preining <norbert@preining.info> | 2019-09-02 13:46:59 +0900 |
commit | e0c6872cf40896c7be36b11dcc744620f10adf1d (patch) | |
tree | 60335e10d2f4354b0674ec22d7b53f0f8abee672 /macros/latex/contrib/tcolorbox/tcolorbox.doc.technical.tex |
Initial commit
Diffstat (limited to 'macros/latex/contrib/tcolorbox/tcolorbox.doc.technical.tex')
-rw-r--r-- | macros/latex/contrib/tcolorbox/tcolorbox.doc.technical.tex | 769 |
1 files changed, 769 insertions, 0 deletions
diff --git a/macros/latex/contrib/tcolorbox/tcolorbox.doc.technical.tex b/macros/latex/contrib/tcolorbox/tcolorbox.doc.technical.tex new file mode 100644 index 0000000000..2d637f4678 --- /dev/null +++ b/macros/latex/contrib/tcolorbox/tcolorbox.doc.technical.tex @@ -0,0 +1,769 @@ +% !TeX root = tcolorbox.tex +% include file of tcolorbox.tex (manual of the LaTeX package tcolorbox) +\clearpage +\section{Technical Overview and Customization}\label{sec:technical}% +\tcbset{external/prefix=external/technical_}% +This section provides a technical overview of the skin concept of |tcolorbox|. +For most applications of |tcolorbox|, one will not need to know the bells and +whistles described herein. +You may proceed to \Vref{sec:skins} where the customization options +for most users are documented. + +The following explanations also cover options and settings from the \mylib{skins} library, +see \Vref{sec:skins}. + +\subsection{Skins and Drawing Engines}\label{sec:skincorekeys} +From a technical point of view, a \emph{skin} is a style definition for the +appearance of a |tcolorbox|. The core package provides some additional +option keys for skins but only two skins called \refSkin{standard} +and \refSkin{standard jigsaw}. +The \mylib{skins} library adds several more skins. To change to a skin, only one +option from the core package has to be set. + +\begin{docTcbKey}{skin}{=\meta{name}}{style, no default, initially \texttt{standard}} + Sets the current skin to \meta{name}. This is a style definition which sets all the following + keys, i.\,e.\ for many use cases there is nothing more to do. +\begin{dispExample} +\tcbset{colback=Salmon!50!white,colframe=FireBrick!75!black, + width=(\linewidth-8mm)/2,before=,after=\hfill,equal height group=ske} + +\begin{tcolorbox}[adjusted title=My title] + This is my content. +\end{tcolorbox} +\begin{tcolorbox}[skin=beamer,beamer,adjusted title=My title] + This is my content. +\end{tcolorbox} +\end{dispExample} +\end{docTcbKey} + +\begin{docTcbKey}{skin first}{=\meta{name}}{style, no default, initially \texttt{standard}} + If the box is set to be \refKey{/tcb/breakable} and \emph{is} broken actually, + then the skin for the \emph{first} part of the break sequence + is set to \meta{name}, see Subsection \ref{subsec:breaksequence} on page \pageref{subsec:breaksequence}. + Typically, this key is set by a \refKey{/tcb/skin}. +\end{docTcbKey} + + +\begin{docTcbKey}{skin middle}{=\meta{name}}{style, no default, initially \texttt{standard}} + If the box is set to be \refKey{/tcb/breakable} and \emph{is} broken actually, + then the skin for the \emph{middle} parts (if any) of the break sequence + is set to \meta{name}, see Subsection \ref{subsec:breaksequence} on page \pageref{subsec:breaksequence}. + Typically, this key is set by a \refKey{/tcb/skin}. +\end{docTcbKey} + + +\begin{docTcbKey}{skin last}{=\meta{name}}{style, no default, initially \texttt{standard}} + If the box is set to be \refKey{/tcb/breakable} and \emph{is} broken actually, + then the skin for the \emph{last} part of the break sequence + is set to \meta{name}, see Subsection \ref{subsec:breaksequence} on page \pageref{subsec:breaksequence}. + Typically, this key is set by a \refKey{/tcb/skin}. +\end{docTcbKey} + + +\clearpage + +\begin{docTcbKey}{graphical environment}{=\meta{name}}{no default, initially \texttt{pgfpicture}} + Sets the graphical environment for the |tcolorbox| to \meta{name}. + Feasible values are |pgfpicture| and |tikzpicture| or environments which + inherit from one of these two. This key is set by a \refKey{/tcb/skin} and + may seldom be used directly. +\end{docTcbKey} + +The skin of a |tcolorbox| is drawn by up to four \emph{engines}. +Afterwards, the text content is drawn which is not part of a skin. +The four steps are: +\begin{enumerate} +\item The \emph{frame} of the box, drawn by \refKey{/tcb/frame engine}. +\item The \emph{interior} of the box. The interior of a box with title is + drawn differently from a box without title. + \refKey{/tcb/interior titled engine} or \refKey{/tcb/interior engine} + is used to draw the interior. +\item The \emph{segmentation} (line) of the box, if there is a lower part; + drawn by \refKey{/tcb/segmentation engine}. +\item The \emph{title area} of the box, if there is a title and + \refKey{/tcb/title filled} is set to |true|; drawn + by \refKey{/tcb/title engine}. +\end{enumerate} + +%Every engine for the up to four steps can be set to one of the following types: +%\begin{enumerate} +%\item\docValue{standard}: the original code from the core package. +%\item\docValue{path}: a |tikz| path which can be controlled by options. +%\item\docValue{pathfirst}: a |tikz| path which can be controlled by options. +%\item\docValue{pathmiddle}: a |tikz| path which can be controlled by options. +%\item\docValue{pathlast}: a |tikz| path which can be controlled by options. +%\item\docValue{freelance}: arbitrary user code. +%\item\docValue{spartan}: a quite spartan code. +%\end{enumerate} +%\clearpage + +\begin{docTcbKey}{frame engine}{=\meta{name}}{no default, initially \texttt{standard}} + Sets the \emph{frame} drawing engine for a box to \meta{name}. + Typically, this key is set by a \refKey{/tcb/skin}. + Feasible values for \meta{name} are: + \begin{itemize} + \item\docValue{standard}: the original code from the core package, + \item\docValue{path}: a |tikz| path which is controlled by \refKey{/tcb/frame style}, + \item\docValue{pathjigsaw}: a |tikz| path which is controlled by \refKey{/tcb/frame style}, + \item\docValue{pathfirst}: a |tikz| path which is controlled by \refKey{/tcb/frame style}, + \item\docValue{pathfirstjigsaw}: a |tikz| path which is controlled by \refKey{/tcb/frame style}, + \item\docValue{pathmiddle}: a |tikz| path which is controlled by \refKey{/tcb/frame style}, + \item\docValue{pathmiddlejigsaw}: a |tikz| path which is controlled by \refKey{/tcb/frame style}, + \item\docValue{pathlast}: a |tikz| path which is controlled by \refKey{/tcb/frame style}, + \item\docValue{pathlastjigsaw}: a |tikz| path which is controlled by \refKey{/tcb/frame style}, + \item\docValue{freelance}: deprecated. + \item\docValue{spartan}: a quite spartan code. + \item\docValue{empty}: draw nothing. +\end{itemize} +\end{docTcbKey} + +\begin{docTcbKey}{interior titled engine}{=\meta{name}}{no default, initially \texttt{standard}} + Sets the \emph{interior} drawing engine for a titled box to \meta{name}. + Typically, this key is set by a \refKey{/tcb/skin}. + Feasible values for \meta{name} are: + \begin{itemize} + \item\docValue{standard}: the original code from the core package, + \item\docValue{path}: a |tikz| path which is controlled by \refKey{/tcb/interior style}, + \item\docValue{pathfirst}: a |tikz| path which is controlled by \refKey{/tcb/interior style}, + \item\docValue{pathmiddle}: a |tikz| path which is controlled by \refKey{/tcb/interior style}, + \item\docValue{pathlast}: a |tikz| path which is controlled by \refKey{/tcb/interior style}, + \item\docValue{freelance}: deprecated. + \item\docValue{spartan}: a quite spartan code. + \item\docValue{empty}: draw nothing. + \end{itemize} +\end{docTcbKey} + +\clearpage +\begin{docTcbKey}{interior engine}{=\meta{name}}{no default, initially \texttt{standard}} + Sets the \emph{interior} drawing engine for an untitled box to \meta{name}. + Typically, this key is set by a \refKey{/tcb/skin}. + Feasible values for \meta{name} are: + \begin{itemize} + \item\docValue{standard}: the original code from the core package, + \item\docValue{path}: a |tikz| path which is controlled by \refKey{/tcb/interior style}, + \item\docValue{pathfirst}: a |tikz| path which is controlled by \refKey{/tcb/interior style}, + \item\docValue{pathmiddle}: a |tikz| path which is controlled by \refKey{/tcb/interior style}, + \item\docValue{pathlast}: a |tikz| path which is controlled by \refKey{/tcb/interior style}, + \item\docValue{freelance}: deprecated. + \item\docValue{spartan}: a quite spartan code. + \item\docValue{empty}: draw nothing. + \end{itemize} +\end{docTcbKey} + +\begin{docTcbKey}{segmentation engine}{=\meta{name}}{no default, initially \texttt{standard}} + Sets the \emph{segmentation} (line) drawing engine for a box to \meta{name}. + Typically, this key is set by a \refKey{/tcb/skin}. + Feasible values for \meta{name} are: + \begin{itemize} + \item\docValue{standard}: the original code from the core package, + \item\docValue{path}: a |tikz| path which is controlled by \refKey{/tcb/segmentation style}, + \item\docValue{freelance}: deprecated. + \item\docValue{spartan}: a quite spartan code. + \item\docValue{empty}: draw nothing. + \end{itemize} +\end{docTcbKey} + +\begin{docTcbKey}{title engine}{=\meta{name}}{no default, initially \texttt{standard}} + Sets the \emph{title area} drawing engine for a titled box to \meta{name}. + Typically, this key is set by a \refKey{/tcb/skin}. + Feasible values for \meta{name} are: + \begin{itemize} + \item\docValue{standard}: the original code from the core package, + \item\docValue{path}: a |tikz| path which is controlled by \refKey{/tcb/title style}, + \item\docValue{pathfirst}: a |tikz| path which is controlled by \refKey{/tcb/title style}, + \item\docValue{pathmiddle}: a |tikz| path which is controlled by \refKey{/tcb/title style}, + \item\docValue{pathlast}: a |tikz| path which is controlled by \refKey{/tcb/title style}, + \item\docValue{freelance}: deprecated. + \item\docValue{spartan}: a quite spartan code. + \item\docValue{empty}: draw nothing. + \end{itemize} +\end{docTcbKey} + +\begin{marker} +After an engine is set to an initializing value, the resulting graphical +code can be changed using code option keys, see \Vref{subsec:addcodeoptions}. +\end{marker} + +\clearpage +\begin{docTcbKey}{geometry nodes}{\colOpt{=true\textbar false}}{default |true|, initially |false|} + If set to |true|, up to four |tikz| nodes are defined for a |tcolorbox| + which are named |frame|, |interior|, |segmentation|, and |title|. These nodes + describe the boundaries of the equally named parts of a |tcolorbox|. + They are used by most engines based on \tikzname. + Typically, this key is set automatically by a \refKey{/tcb/skin}. +\begin{dispExample} +\tcbset{colback=Salmon!50!white,colframe=FireBrick!75!black, + width=(\linewidth-8mm)/2,before=,after=\hfill,equal height group=geon} + +\begin{tcolorbox}[adjusted title=The title] + The upper part.\tcblower The lower part. +\end{tcolorbox} +\begin{tcolorbox}[enhanced,adjusted title=The title, + frame code={\path[draw=red,fill=red!25] + (frame.south west) rectangle (frame.north east);}, + interior titled code={\path[draw=blue,fill=blue!25] + (interior.south west) rectangle (interior.north east);}, + segmentation code={\path[draw=green,fill=green!25] + (segmentation.south west) rectangle (segmentation.north east);}, + title code={\path[draw=black,fill=brown!75!black] + (title.south west) rectangle (title.north east);}] + The upper part.\tcblower The lower part. +\end{tcolorbox} +\end{dispExample} +\end{docTcbKey} + + + + + + +\clearpage +\subsection{Code Option Keys}\label{subsec:addcodeoptions} +The following code options are applicable for all skins. +%which +%use engines of type |freelance|. +%Especially, the skin \refSkin{freelance} supports \emph{all} of them, +%\refSkin{standard} and \refSkin{enhanced} \emph{none} of them. +The used \meta{graphical code} can be any |pgf| code. For all skins +with exception of \refSkin{standard} +and \refSkin{standard jigsaw}, the \meta{graphical code} can also +be any \tikzname\ code. + + +\begin{docTcbKey}{frame code}{\colOpt{=\meta{graphical code}}}{code, default from |standard|} + The given \meta{graphical code} is used for drawing the \emph{frame} of the box. + %This option is available only if the \refKey{/tcb/frame engine} is set to |freelance|. +\begin{dispExample} +\tcbset{colback=red!5!white,colframe=red!75!black} + +\begin{tcolorbox}[enhanced,frame code={ + \foreach \n in {north east,north west,south east,south west} + {\path [fill=red!75!black] (interior.\n) circle (3mm); }; }] +This is a \textbf{tcolorbox}. +\tcblower +This is the lower part. +\end{tcolorbox} +\end{dispExample} +\end{docTcbKey} + + +\begin{docTcbKey}{frame empty}{}{style, no value} + This is a shortcut for setting \refKey{/tcb/frame code} to empty. + This option removes the drawing of the frame. + Alternatively, use \refKey{/tcb/frame hidden}. +\end{docTcbKey} + + +\begin{docTcbKey}{interior titled code}{\colOpt{=\meta{graphical code}}}{code, default from |standard|} + The given \meta{graphical code} is used + for drawing the \emph{interior} of the box, if the box comes with a title. + %This option is available only if the \refKey{/tcb/interior titled engine} is set to |freelance|. +\begin{dispExample} +\tcbset{colback=red!5!white,colframe=red!75!black,fonttitle=\bfseries} + +\begin{tcolorbox}[enhanced,title=My title,interior titled code={ + \path[draw=red!5!white,line width=5mm,line cap=round] + ([xshift=3mm,yshift=-3mm]interior.north west) + --([xshift=-3mm,yshift=3mm]interior.south east) + ([xshift=3mm,yshift=3mm]interior.south west) + --([xshift=-3mm,yshift=-3mm]interior.north east);}] +This is a \textbf{tcolorbox}. +\tcblower +This is the lower part. +\end{tcolorbox} +\end{dispExample} +\end{docTcbKey} + + +\begin{docTcbKey}{interior titled empty}{}{style, no value} + This is a shortcut for setting \refKey{/tcb/interior titled code} to empty. + This option removes the drawing of the untitled interior. + Alternatively, use \refKey{/tcb/interior hidden}. +\end{docTcbKey} + + + +\clearpage +\begin{docTcbKey}{interior code}{\colOpt{=\meta{graphical code}}}{code, default from |standard|} + The given \meta{graphical code} is used + for drawing the \emph{interior} of the box, if the box is without a title.%\\ + %This option is available only if the \refKey{/tcb/interior engine} is set to |freelance|. +\begin{dispExample} +\tcbset{colback=red!5!white,colframe=red!75!black} + +\begin{tcolorbox}[enhanced,interior code={ + \path[draw=red!5!white,line width=5mm,line cap=round] + ([xshift=3mm,yshift=-3mm]interior.north west) + --([xshift=-3mm,yshift=3mm]interior.south east) + ([xshift=3mm,yshift=3mm]interior.south west) + --([xshift=-3mm,yshift=-3mm]interior.north east);}] +This is a \textbf{tcolorbox}. +\tcblower +This is the lower part. +\end{tcolorbox} +\end{dispExample} +\end{docTcbKey} + +\begin{docTcbKey}{interior empty}{}{style, no value} + This is a shortcut for setting \refKey{/tcb/interior code} to empty. + This option removes the drawing of the interior. + Alternatively, use \refKey{/tcb/interior hidden}. +\end{docTcbKey} + + +\begin{docTcbKey}{segmentation code}{\colOpt{=\meta{graphical code}}}{code, default from |standard|} + The given \meta{graphical code} is used for drawing the + \emph{segmentation} area of the box.%\\ + %This option is available only if the \refKey{/tcb/segmentation engine} is set to |freelance|. +\begin{dispExample} +\tcbset{colback=red!5!white,colframe=red!75!black,fonttitle=\bfseries} + +\begin{tcolorbox}[enhanced,title=My title,segmentation code={ + \path[top color=red!5!white,bottom color=red!5!white,middle color=blue] + (segmentation.south west) rectangle (segmentation.north east);}] +This is a \textbf{tcolorbox}. +\tcblower +This is the lower part. +\end{tcolorbox} +\end{dispExample} +\end{docTcbKey} + + +\begin{docTcbKey}{segmentation empty}{}{style, no value} + This is a shortcut for setting \refKey{/tcb/segmentation code} to empty. + This option removes the drawing of the segmentation line. + Alternatively, use \refKey{/tcb/segmentation hidden}. +\end{docTcbKey} + + + +\clearpage +\begin{docTcbKey}{title code}{\colOpt{=\meta{graphical code}}}{code, default from |standard|} + The given \meta{graphical code} is used for drawing the + \emph{title} area of the box. + %\\ + %This option is available only if the \refKey{/tcb/title engine} is set to |freelance|. +\begin{dispExample} +\tcbset{colback=red!5!white,colframe=red!75!black,fonttitle=\bfseries, + coltitle=black} + +\begin{tcolorbox}[enhanced,title=My title,title code={ + \path[draw=yellow,solid,decorate,line width=2mm, + decoration={coil,aspect=0,segment length=10.1mm}] + ([xshift=1mm]title.west) -- ([xshift=-1mm]title.east);}] +This is a \textbf{tcolorbox}. +\tcblower +This is the lower part. +\end{tcolorbox} +\end{dispExample} +\end{docTcbKey} + + +\begin{docTcbKey}{title empty}{}{style, no value} + This is a shortcut for setting \refKey{/tcb/title code} to empty. + This option removes the drawing of the title area. + Alternatively, use \refKey{/tcb/title hidden}. +\end{docTcbKey} + +\clearpage +\subsection{Subskins}\label{subsec:subskins} +A subskin is a new \refKey{/tcb/skin} based on an existing skin which +is extended or changed. + +\begin{marker} +Never use geometry settings or bounding box options inside a subskin definition! +If one skin is replaced by another skin, the overall bounding box should stay +constant. Especially, if a skin is used for a breakable box, unpredictable +and unpleasant results could arise otherwise. If you want to change the +geometry also, use an additional style. See the skin \refSkin{beamer} and +the style \refKey{/tcb/beamer} as pattern. +\end{marker} + +\begin{docCommand}{tcbsubskin}{\marg{name}\marg{base skin}\marg{options}} + Creates a new skin \meta{name} which inherits all properties of an + existing \meta{base skin} plus the given \meta{options}. + The new skin \meta{name} can be used as value for the keys + \refKey{/tcb/skin}, + \refKey{/tcb/skin first}, + \refKey{/tcb/skin middle}, and + \refKey{/tcb/skin last}. + As \meta{base skin}, one can take \refSkin{standard}, \refSkin{empty}, + \refSkin{enhanced}, or any skin from the \mylib{skins} library, + see \Vref{sec:skins}. + +\begin{dispExample} +% \tcbuselibrary{skins} +\tcbsubskin{mycross}{empty}{frame code={% + \draw[red,line width=5pt] (frame.south west)--(frame.north east); + \draw[red,line width=5pt] (frame.north west)--(frame.south east);}, + skin first=mycross,skin middle=mycross,skin last=mycross } + +\begin{tcolorbox}[skin=mycross] + This is my content. +\end{tcolorbox} +\end{dispExample} + +\end{docCommand} + + +\begin{docTcbKey}{skin first is subskin of}{=\marg{base skin}\marg{options}}{no default, initially unset} + Creates a new unnamed skin which inherits all properties of an + existing \meta{base skin} plus the given \meta{options}. + This skin is set as \refKey{/tcb/skin first}.\\ + See a detailed example on page~\pageref{freeboxexample}. +\end{docTcbKey} + + +\begin{docTcbKey}{skin middle is subskin of}{=\marg{base skin}\marg{options}}{no default, initially unset} + Creates a new unnamed skin which inherits all properties of an + existing \meta{base skin} plus the given \meta{options}. + This skin is set as \refKey{/tcb/skin middle}.\\ + See a detailed example on page~\pageref{freeboxexample}. +\end{docTcbKey} + + +\begin{docTcbKey}{skin last is subskin of}{=\marg{base skin}\marg{options}}{no default, initially unset} + Creates a new unnamed skin which inherits all properties of an + existing \meta{base skin} plus the given \meta{options}. + This skin is set as \refKey{/tcb/skin last}.\\ + See a detailed example on page~\pageref{freeboxexample}. +\end{docTcbKey} + + +\clearpage +\subsection{Drawing Scheme}\label{subsec:tcolorboxdrawing} + +\bgroup + +Depending on the complexity of a |tcolorbox| definition, the resulting box +is drawn in a more or less complex series of steps. + +To document and demonstrate these drawing steps, we consider the +following box definition: + +\begin{dispListing} +\newtcolorbox{testbox}[1][]{enhanced,title=Test Box, + boxrule=1mm,titlerule=0.5mm,colframe=blue!50!black, + interior style={top color=blue!20!green!50!white,bottom color=blue!20!yellow!50!white}, + colbacktitle=blue!50!green!90!white,segmentation style={solid}, + fonttitle=\bfseries,drop fuzzy shadow,borderline={0.3mm}{0.35mm}{yellow!50!white}, + underlay={\path[fill image opacity=0.15,fill image scale=0.9, + fill stretch picture={\draw[blue,line width=2mm] circle (1);}] + (interior.south west) rectangle (interior.north east);}, + watermark text={Watermark},watermark color={green!20!white}, + finish={\begin{tcbclipframe} + \path[bottom color=black,top color=black!50!white,opacity=0.1] + (frame.south west) -- (frame.south east) -- (frame.north east) -- cycle; + \path[top color=white,bottom color=black!50!white,opacity=0.1] + (frame.south west) -- (frame.north east) -- (frame.north west) -- cycle; + \end{tcbclipframe}},#1} +\end{dispListing} +\tcbusetemp + +For this definition, we get the maximal number of drawing steps: + +\newtcolorbox{itembox}{oversize,enhanced,frame empty,segmentation empty,colback=white,middle=2mm,boxsep=0pt, + fuzzy halo=0.5mm with blue!15!white, + before lower=\raggedright\begin{itemize},after lower=\end{itemize}} + +\tcbset{finishcomment/.style={ + finish={\node[fill=white,draw=black!50!white,rounded corners] at (frame.center) {#1};} +}} + + +\begin{itembox} +\begin{testbox}[frame empty,interior titled empty,title empty,segmentation empty, + no shadow,no borderline,no underlay,no overlay,no finish,opacityupper=0,opacitylower=0,opacitytitle=0, + drop fuzzy shadow=red!75!white, + finishcomment={1.~shadow}] +\lipsum[2] +\tcblower +Lower part +\end{testbox} +\tcblower +\item Section~\ref{subsec:shadows} on page \pageref{subsec:shadows}. +\end{itembox} + +\begin{itembox} +\begin{testbox}[interior titled empty,title empty,segmentation empty, + no borderline,no underlay,no overlay,no finish,opacityupper=0,opacitylower=0,opacitytitle=0, + colframe=red!75!white, + finishcomment={2.~frame}] +\lipsum[2] +\tcblower +Lower part +\end{testbox} +\tcblower +\item\refKey{/tcb/colframe}, \refKey{/tcb/opacityframe} +\item\refKey{/tcb/frame code} +\item\refKey{/tcb/frame style} +\end{itembox} + + +\begin{itembox} +\begin{testbox}[title empty,segmentation empty, + no borderline,no underlay,no overlay,no finish,opacityupper=0,opacitylower=0,opacitytitle=0, + colback=red!75!white, + finishcomment={3.~interior}] +\lipsum[2] +\tcblower +Lower part +\end{testbox} +\tcblower +\item\refKey{/tcb/colback}, \refKey{/tcb/opacityback} +\item\refKey{/tcb/interior code}, \refKey{/tcb/interior titled code} +\item\refKey{/tcb/interior style} +\end{itembox} + + +\begin{itembox} +\begin{testbox}[segmentation empty, + no borderline,no underlay,no overlay,no finish,opacityupper=0,opacitylower=0,opacitytitle=0, + colbacktitle=red!75!white, + finishcomment={4.~title area}] +\lipsum[2] +\tcblower +Lower part +\end{testbox} +\tcblower +\item\refKey{/tcb/colbacktitle}, \refKey{/tcb/opacitybacktitle} +\item\refKey{/tcb/title code} +\item\refKey{/tcb/title style} +\end{itembox} + + +\begin{itembox} +\begin{testbox}[ + no borderline,no underlay,no overlay,no finish,opacityupper=0,opacitylower=0,opacitytitle=0, + segmentation style={solid,red!75!white}, + finishcomment={5.~segmentation}] +\lipsum[2] +\tcblower +Lower part +\end{testbox} +\tcblower +\item\refKey{/tcb/lower separated} +\item\refKey{/tcb/segmentation code} +\item\refKey{/tcb/segmentation style} +\end{itembox} + + +\begin{itembox} +\begin{testbox}[ + no borderline,no underlay,no overlay,no finish,opacityupper=0,opacitylower=0,opacitytitle=0, + borderline={0.3mm}{0.35mm}{red!75!white}, + finishcomment={6.~border line}] +\lipsum[2] +\tcblower +Lower part +\end{testbox} +\tcblower +\item\Vref{subsec:borderline} +\end{itembox} + + +\begin{itembox} +\begin{testbox}[ + no underlay,no overlay,no finish,opacityupper=0,opacitylower=0,opacitytitle=0, + underlay={\path[opacity=0.15,fill image scale=0.9, + fill stretch picture={\draw[red,line width=2mm] circle (1);}] + (interior.south west) rectangle (interior.north east);}, + finishcomment={7.~underlay}] +\lipsum[2] +\tcblower +Lower part +\end{testbox} +\tcblower +\item\Vref{subsec:skinboxedtitle} +\item\Vref{subsec:skinunderlay} +\end{itembox} + + +\begin{itembox} +\begin{testbox}[ + no finish,opacityupper=0,opacitylower=0,opacitytitle=0, + watermark color={red!75!white}, + finishcomment={8.~overlay}] +\lipsum[2] +\tcblower +Lower part +\end{testbox} +\tcblower +\item\Vref{subsec:overlays} +\item\Vref{subsec:watermarks} +\end{itembox} + + +\begin{itembox} +\begin{testbox}[ + no finish, + colupper=red!75!white,coltitle=red!75!white,collower=red!75!white, + finishcomment={9.~text content}] +\lipsum[2] +\tcblower +Lower part +\end{testbox} +\tcblower +\item\refKey{/tcb/colupper}, \refKey{/tcb/collower}, \refKey{/tcb/coltitle} +\item\refKey{/tcb/fontupper}, \refKey{/tcb/fontlower}, \refKey{/tcb/fonttitle} +\item\refKey{/tcb/opacityupper}, \refKey{/tcb/opacitylower}, \refKey{/tcb/opacitytitle} +\end{itembox} + + +\begin{itembox} +\begin{testbox}[ + finishcomment={10.~finish}] +\lipsum[2] +\tcblower +Lower part +\end{testbox} +\tcblower +\item\Vref{subsec:skinfinish} +\end{itembox} + +All together, the box is drawn: +\begin{dispExample} +% \usepackage{lipsum} +\begin{testbox} +\lipsum[2] +\tcblower +Lower part +\end{testbox} +\end{dispExample} + +\egroup + + +\clearpage +\subsection{Color Names}\label{subsec:tech_colornames} +Color settings for a |tcolorbox| are saved into named colors which may be +used inside a box, e.g. for an overlay. +\tcbdocmarginnote{\tcbdocnew{2019-01-18}} +These color names are +\begin{itemize} +\item\docColor{tcbcolframe} set by \refKey{/tcb/colframe} (frame color) +\item\docColor{tcbcolback} set by \refKey{/tcb/colback} (background color) +\item\docColor{tcbcolbacktitle} set by \refKey{/tcb/colbacktitle} (background color of the title) +\item\docColor{tcbcolbacklower} set by \refKey{/tcb/colbacklower} (skin dependend background color + of the lower part; needs \mylib{skins} to be loaded) +\item\docColor{tcbcolupper} set by \refKey{/tcb/colupper} (text color upper part) +\item\docColor{tcbcollower} set by \refKey{/tcb/collower} (text color lower part) +\item\docColor{tcbcoltitle} set by \refKey{/tcb/coltitle} (text color title) +\end{itemize} + +\medskip + +\begin{dispExample} +% \tcbuselibrary{skins} +\begin{tcolorbox}[title=Color names, + colframe=blue!50!black,colback=blue!5, + colbacktitle=blue!50,colupper=red!35!black] + \foreach \name in {tcbcolframe,tcbcolback,tcbcolbacktitle,tcbcolbacklower, + tcbcolupper,tcbcollower,tcbcoltitle} + {\tikz\path[draw,fill=\name] + (0,0) rectangle node[right=4mm,font=\ttfamily]{\name} (0.8,0.8);\par} +\end{tcolorbox} +\end{dispExample} + + + +\clearpage +\subsection{Useful Properties}\label{subsec:tech_properties} + +The following macros describe certain \textit{properties} which may be +used for the drawing scheme, see \Fullref{subsec:tcolorboxdrawing}. +Sometimes, they are even available inside the box content. All of them are +considered to be \textit{read-only} and should never be redefined by the user. + +\begin{docCommand}[doc new=2016-02-16]{tcbheightspace}{} + If the height of a |tcolorbox| is not the natural height, the space + difference between the forced and the natural size is hold by + \refCom{tcbheightspace}. + This macro is not usable inside the box content, but for skins or + inside \refKey{/tcb/underlay}, \refKey{/tcb/overlay}, etc. + + If such a space information is needed inside the box content, see + \refKey{/tcb/space to} instead. +\begin{dispExample} +% \tcbuselibrary{skins} +\newtcolorbox{testbox}[2][]{enhanced,size=fbox, + colframe=blue!75!black,colback=white,height=#2, + underlay={\node[above,inner sep=3pt] at (interior.south){% + \includegraphics[width=\tcbtextwidth,height=\tcbheightspace-3pt]{goldshade.png}}; + }, + #1} +\begin{testbox}{3cm} + This is my box. The space is filled with a picture. +\end{testbox} +\begin{testbox}{2cm} + This is my box. The space is filled with a picture. +\end{testbox} +\end{dispExample} +\end{docCommand} + + +\begin{docCommand}[doc new=2016-02-16]{tcbtextwidth}{} + This property describes the box content width. + \begin{itemize} + \item If there also is a lower part, it describes the width of the upper part. + \item For \refKey{/tcb/sidebyside} boxes, it describes the combined text + width plus segmentation. + \item This property can be used inside the box content text with exception + of \refKey{/tcb/fit} boxes. + \item \refCom{tcbtextwidth} can be used for all box types for skins or + inside \refKey{/tcb/underlay}, \refKey{/tcb/overlay}, etc. + \end{itemize} +\begin{dispExample} +\begin{tcolorbox}[colframe=blue!75!black] + Inside a box: \tcbtextwidth\ (=\the\linewidth). +\end{tcolorbox} +\end{dispExample} +\end{docCommand} + +\pagebreak +\begin{docCommand}[doc new=2016-02-16]{tcbtextheight}{} + This property describes the designated box content height. If the + box is larger than the natural height, the actual content will be smaller + than \refCom{tcbtextheight}. + \begin{itemize} + \item For boxes with a fixed \refKey{/tcb/height}, this property can + be used inside the box content text. For other boxes, it denotes |0pt| + inside the box content. + \item \refCom{tcbtextheight} can be used for all box types for skins or + inside \refKey{/tcb/underlay}, \refKey{/tcb/overlay}, etc. + \end{itemize} + +\begin{dispExample} +% \tcbuselibrary{skins} +\begin{tcolorbox}[enhanced,colframe=blue!75!black, + underlay={\node[left,red] at (frame.east) {Here: \tcbtextheight};}] + Inside a box with natural height: \tcbtextheight. +\end{tcolorbox} +\begin{tcolorbox}[enhanced,colframe=blue!75!black,height=1cm, + underlay={\node[left,red] at (frame.east) {Here: \tcbtextheight};}] + Inside a box with fixed height: \tcbtextheight. +\end{tcolorbox} +\end{dispExample} +\end{docCommand} + + +\begin{docCommand}[doc new=2017-04-25]{tcbsegmentstate}{} + This macro contains |0|, |1|, or |2|. Itis set for every unbroken box and every broken partial box + with the following meaning: + \begin{itemize} + \item\docValue{0}: The current (partial) box contains only an upper part. + \item\docValue{1}: The current (partial) box contains an upper and a lower part. + The segmentation node can be used for positioning. + \item\docValue{2}: The current (partial) box contains only a lower part. + This can only be true for parts of breakable boxes. + \end{itemize} + Skins like \refSkin{bicolor} use this property to paint the (partial) boxes. +\begin{dispExample} +% \tcbuselibrary{skins,raster} +\begin{tcbraster}[raster equal height,enhanced, + watermark text=\tcbsegmentstate] + \begin{tcolorbox}Upper part\end{tcolorbox} + \begin{tcolorbox}Upper part\tcblower Lower part\end{tcolorbox} +\end{tcbraster} +\end{dispExample} +\end{docCommand} |