diff options
Diffstat (limited to 'macros/latex/contrib/tcolorbox/tcolorbox.doc.fitting.tex')
-rw-r--r-- | macros/latex/contrib/tcolorbox/tcolorbox.doc.fitting.tex | 540 |
1 files changed, 540 insertions, 0 deletions
diff --git a/macros/latex/contrib/tcolorbox/tcolorbox.doc.fitting.tex b/macros/latex/contrib/tcolorbox/tcolorbox.doc.fitting.tex new file mode 100644 index 0000000000..8ff8fa0792 --- /dev/null +++ b/macros/latex/contrib/tcolorbox/tcolorbox.doc.fitting.tex @@ -0,0 +1,540 @@ +% !TeX root = tcolorbox.tex +% include file of tcolorbox.tex (manual of the LaTeX package tcolorbox) +\clearpage +\section{Library \mylib{fitting}}\label{sec:fitting}% +\tcbset{external/prefix=external/fitting_}% +The library is loaded by a package option or inside the preamble by: +\begin{dispListing} +\tcbuselibrary{fitting} +\end{dispListing} + +\subsection{Macros of the Library} + +\begin{docCommand}{tcboxfit}{\oarg{options}\marg{box content}} + Creates a colored box where the given \meta{box content} is fitted to + the width and height of the box. A |tcboxfit| has to have a fixed height. + If no fixed height is given, a square box is constructed. + In principle, most \meta{options} for a \refEnv{tcolorbox} + can be used for |\tcboxfit| with some restrictions. A |\tcboxfit| cannot have + a lower part and cannot be broken. + +\enlargethispage*{1cm} +\begin{dispExample} +% \usepackage{lipsum} \tcbuselibrary{raster} +\tcbset{colframe=blue!50!black,colback=red!10!white, + boxsep=0pt,top=1mm,bottom=1mm,left=1mm,right=1mm, + fit algorithm=hybrid*,raster equal skip=1mm} +\begin{tcbraster}[raster columns=3,raster valign=bottom] + \tcboxfit[height=8cm]{\lipsum[1]} + \tcboxfit[height=4cm]{\lipsum[1]} + \tcboxfit[height=2cm]{\lipsum[1]} +\end{tcbraster} +\begin{tcbraster}[colback=green!10!white,boxsep=1mm] + \tcboxfit[height=4cm]{\lipsum[2]} + \tcboxfit[height=4cm,title=With a title]{\lipsum[2]} +\end{tcbraster} +\end{dispExample} +\end{docCommand} + +\clearpage +\begin{marker} +See \Vref{subsec:xparse_tcboxfit} for more +elaborate methods to create new commands. +\end{marker} + +\enlargethispage*{2cm} + +\begin{docCommand}{newtcboxfit}{\oarg{init options}\brackets{\texttt{\textbackslash}\rmfamily\meta{name}}\oarg{number}\oarg{default}\marg{options}} + Creates a new macro \texttt{\textbackslash}\meta{name} based on \refCom{tcboxfit}. + Basically, |\newtcboxfit| operates like |\newcommand|. + The new macro \texttt{\textbackslash}\meta{name} optionally takes \meta{number}$+1$ arguments, where + \meta{default} is the default value for the optional first argument. + The \meta{options} are given to the underlying |tcboxfit|. + The \meta{init options} allow setting up automatic numbering, + see Section \ref{sec:initkeys} from page \pageref{sec:initkeys}. +\begin{dispExample*}{sbs,lefthand ratio=0.6} +\newtcboxfit{\mybox}{colback=red!5!white, + colframe=red!75!black,width=4cm, + height=1.5cm,halign=center} + +\mybox{This is my own box.}\par +\mybox{This is my own box with more text + to be written.} +\end{dispExample*} + +\begin{dispExample*}{sbs,lefthand ratio=0.6} +% \usepackage{lipsum} +\newtcboxfit{\mybox}[2]{colback=red!5!white, + colframe=red!75!black,fonttitle=\bfseries, + boxsep=1mm,left=0mm,right=0mm,top=0mm, + bottom=0mm,halign=center,valign=center, + nobeforeafter,width=#1,height=#2} + +\mybox{2.5cm}{1cm}{First box}% +\mybox{2.5cm}{1cm}{Second box with more text}\\ +\mybox{5cm}{2cm}{Third box with text}\\ +\mybox{5cm}{3cm}{\lipsum[1]} +\end{dispExample*} + +\begin{dispExample*}{sbs,lefthand ratio=0.6} +% \usepackage{lipsum} +\newtcboxfit{\mybox}[2][]{colback=red!5!white, + colframe=red!75!black, + width=#2,height=#2/3*2,#1} + +\mybox[colback=yellow]{5cm}% + {\lipsum[2]} +\end{dispExample*} +\end{docCommand} + + +\begin{docCommand}{renewtcboxfit}{\oarg{init options}\brackets{\texttt{\textbackslash}\rmfamily\meta{name}}\oarg{number}\oarg{default}\marg{options}} + Operates like \refCom{newtcboxfit}, but based on |\renewcommand| instead of |\newcommand|. + An existing macro is redefined. +\end{docCommand} + +\enlargethispage*{1cm} +\begin{docCommand}{tcbfontsize}{\marg{factor}} + Selects a font size inside a tcolorbox which is scaled with the given + \meta{factor} relative to \docAuxCommand{tcbfitdim}.% + %, see Subsection \ref{subsec:fit} from page \pageref{subsec:fit}. + +\begin{dispExample*}{sbs,lefthand ratio=0.6} +\tcbset{colback=red!5!white,colframe=red!75!black} +\begin{tcolorbox}[fit basedim=10pt] + {\tcbfontsize{0.25} Very tiny,}\\ + {\tcbfontsize{0.5} Small,}\\ + {\tcbfontsize{1} Normal,}\\ + {\tcbfontsize{2} Large,}\\ + {\tcbfontsize{4} Huge.} +\end{tcolorbox} +\end{dispExample*} +\end{docCommand} + + +\clearpage +\subsection{Option Keys of the Library}\label{subsec:fit} + +The font size for the content of a box with fixed width and fixed height +can be adjusted automatically. This is called the \emph{fitbox capture mode}. +Note that the fit control algorithm +constructs a series of versions for the box and selects the 'best'. +Therefore, the compilation time is quite longer than for a normal box. +The algorithm will fail, if a different selected font size does not change the +overall size of the box content. +The \refCom{tcboxfit} macro uses this algorithm by default. + +\medskip +\begin{marker} + The fit control keys are only applicable to unbreakable boxes without + a lower part. + The box content should not change counters. +\end{marker} +\medskip + +\enlargethispage*{5mm} +\begin{docTcbKey}{fit}{}{style, initially unset} + Sets the \refKey{/tcb/capture} mode to |fitbox|, i.\,e.\ enables the + font size adjustment algorithm. Thereby, a \refEnv{tcolorbox} acts + like \refCom{tcboxfit} where the given \meta{box content} is fitted to + the width and height of the box. Therefore, the box has to have a fixed height. + If no fixed height is given, a square box is constructed. + The font dimension \docAuxCommand{tcbfitdim} can also be used to adjust + the margins of the box since a box with a tiny font may not need large + margins. The number of constructed boxes is saved to the macro \docAuxCommand{tcbfitsteps} + for analysis. + +\begin{dispExample} +% \usepackage{lipsum} +% \tcbuselibrary{skins} +\newtcolorbox{fitting}[2][]{fit,height=#2,boxsep=1pt,valign=center,opacityupper=0.5, + top=0.4\tcbfitdim,bottom=0.4\tcbfitdim,left=0.75\tcbfitdim,right=0.75\tcbfitdim, + enhanced,watermark text={\tcbfitsteps},colframe=blue!75!black,colback=white,#1} + +\begin{fitting}{4cm} +\lipsum[1] +\end{fitting} + +\begin{fitting}{2cm} +\lipsum[2] +\end{fitting} + +\begin{fitting}{1cm} +\lipsum[3] +\end{fitting} +\end{dispExample} +\end{docTcbKey} + + +\clearpage +\begin{docTcbKey}{fit to}{=\meta{width} and \meta{height}}{style, initially unset} + Shortcut for using \refKey{/tcb/fit} and setting the \meta{width} and \meta{height} values + separately. +\begin{dispExample*}{sbs,lefthand ratio=0.6} +\tcbset{colback=red!5!white,colframe=red!75!black} + +\begin{tcolorbox}[fit to=3cm and 2cm] + This box content is fitted to the given + dimensions. +\end{tcolorbox} +\end{dispExample*} +\end{docTcbKey} + + +\begin{docTcbKey}{fit to height}{=\meta{height}}{style, initially unset} + Shortcut for using \refKey{/tcb/fit} and setting the \meta{height} value separately. +\begin{dispExample*}{sbs,lefthand ratio=0.6} +\tcbset{colback=red!5!white,colframe=red!75!black} + +\begin{tcolorbox}[fit to height=2cm] + This box content is fitted to the given + height. +\end{tcolorbox} +\end{dispExample*} +\end{docTcbKey} + +\begin{docTcbKey}{fit basedim}{=\meta{length}}{no default, initially |10pt|} + Sets the starting font dimension for the font size adjustment algorithm + to \meta{length}. The algorithm never enlarges this dimension. + +\begin{dispExample*}{sbs,lefthand ratio=0.6} +\tcbset{colback=red!5!white,colframe=red!75!black} + +\begin{tcolorbox}[fit to=4cm and 2cm] + Too few words for the box. +\end{tcolorbox} + +\begin{tcolorbox}[fit to=4cm and 2cm, + fit basedim=50pt] + Enough words for the box. +\end{tcolorbox} +\end{dispExample*} +\end{docTcbKey} + + +\begin{docTcbKey}{fit skip}{=\meta{real value}}{no default, initially |1.2|} + Sets the skip value of the selected font to \meta{real value} times \docAuxCommand{tcbfitdim}. + +\begin{dispExample*}{sbs,lefthand ratio=0.6} +% \usepackage{lipsum} +\tcbset{colback=red!5!white, + colframe=red!75!black,left=1mm, + right=1mm,boxsep=0mm} + +\begin{tcolorbox}[fit to=5cm and 4cm, + fit skip=1.0 ] + \lipsum[1] +\end{tcolorbox} +\end{dispExample*} +\end{docTcbKey} + + + +\clearpage +\begin{docTcbKey}{fit fontsize macros}{}{style, initially unset} + Redefines the standard \LaTeX\ font size macros + |\tiny|, |\scriptsize|, |\footnotesize|, |\small|, |\normalsize|, + |\large|, |\Large|, |\LARGE|, |\huge|, and |\Huge|, + to set font sizes relative to + the current \docAuxCommand{tcbfitdim}. Note that the display skip values for + mathematical formulas are respected by the redefined macros. + +\begin{dispExample*}{sbs,lefthand ratio=0.6} +% \usepackage{lipsum} +\tcbset{colback=red!5!white, + colframe=red!75!black,left=1mm, + right=1mm,boxsep=0mm} + +\begin{tcolorbox}[fit to height=4cm] + {\Large\bfseries This text is + not adapted:\par} + \lipsum[2] +\end{tcolorbox} + +\begin{tcolorbox}[fit to height=4cm, + fit fontsize macros ] + {\Large\bfseries This text is adapted:\par} + \lipsum[2] +\end{tcolorbox} +\end{dispExample*} + +\begin{dispExample*}{sbs,lefthand ratio=0.6} +\tcbset{colback=red!5!white, + colframe=red!75!black,left=1mm, + right=1mm,boxsep=0mm} + +\let\realHuge=\Huge + +\begin{tcolorbox}[fit basedim=7pt, + fontupper=\normalsize, + fit fontsize macros] +The relative relative font size macros +are also usable without the +\textit{fit} algorithm.\par +{\Huge Adapted Huge} --- +{\realHuge Original Huge} +\end{tcolorbox} + +\end{dispExample*} + + +\begin{dispExample*}{sbs,lefthand ratio=0.6} +\tcbset{size=fbox,colback=red!5!white, + colframe=red!75!black} + +\tcboxfit[height=5cm, + fit fontsize macros, + fonttitle=\normalsize\bfseries, + title=Adapted title] +{\lipsum[2]} + +\end{dispExample*} +\end{docTcbKey} + + +\clearpage +\begin{docTcbKey}{fit height plus}{=\meta{dimension}}{no default, initially |0pt|} + The box is allowed to enlarge the fixed height up to the given \meta{dimension}, + before a font size fit is applied. An optional \refKey{/tcb/fit width plus} + is tried after the height adaption. +\begin{dispExample} +% \usepackage{lipsum} +\tcbset{colback=red!5!white,colframe=red!75!black,left=1mm,top=1mm,bottom=1mm, + right=1mm,boxsep=0mm,width=3cm,height=3cm,nobeforeafter} + +\begin{tcolorbox}[fit] +This is a tcolorbox. +\end{tcolorbox} +\begin{tcolorbox}[fit,fit height plus=1cm] +This is a tcolorbox. +\end{tcolorbox} +\begin{tcolorbox}[fit] +\lipsum[2] +\end{tcolorbox} +\begin{tcolorbox}[fit,fit height plus=1cm] +\lipsum[2] +\end{tcolorbox} +\end{dispExample} +\end{docTcbKey} + + +\begin{docTcbKey}{fit width plus}{=\meta{dimension}}{no default, initially |0pt|} + The box is allowed to enlarge the fixed width up to the given \meta{dimension}, + before a font size fit is applied. An optional \refKey{/tcb/fit height plus} + is tried before the width adaption. + \enlargethispage*{1cm} +\begin{dispExample} +% \usepackage{lipsum} +\tcbset{colback=red!5!white,colframe=red!75!black,left=1mm,top=1mm,bottom=1mm, + right=1mm,boxsep=0mm,width=3cm,height=3cm,nobeforeafter} + +\begin{tcolorbox}[fit] +This is a tcolorbox. +\end{tcolorbox} +\begin{tcolorbox}[fit,fit width plus=1cm] +This is a tcolorbox. +\end{tcolorbox} +\begin{tcolorbox}[fit] +\lipsum[2] +\end{tcolorbox} +\begin{tcolorbox}[fit,fit width plus=1cm] +\lipsum[2] +\end{tcolorbox} +\end{dispExample} +\end{docTcbKey} + + +\begin{marker} +Typically but not necessarily, the optional title of a |tcolorbox| is not part of the fit operation. +If a \refKey{/tcb/fit width plus} is applied, the title is also adapted to +the new width. If counters are increased inside the title text, they may be +increased more than one time. +To avoid this, you are encouraged to use \refKey{/tcb/phantom} or \refKey{/tcb/step and label} +to set counters or use automatic numbering, see Subsection \ref{sec:numberedboxes} +from page \pageref{sec:numberedboxes}. +\end{marker} + + +\begin{docTcbKey}{fit width from}{=\meta{min} \texttt{to} \meta{max}}{style, no default} + Sets the box width to \meta{min} and allows the width to grow up to \meta{max}. +\begin{dispExample} +% \usepackage{lipsum} +\tcbset{colback=red!5!white,colframe=red!75!black,left=1mm,top=1mm,bottom=1mm, + right=1mm,boxsep=0mm,height=4cm} + +\begin{tcolorbox}[fit,width=\linewidth/2] +\lipsum[2] +\end{tcolorbox}\par +\begin{tcolorbox}[fit width from=\linewidth/2 to \linewidth] +\lipsum[2] +\end{tcolorbox}\par +\end{dispExample} +\end{docTcbKey} + +\clearpage +\begin{docTcbKey}{fit height from}{=\meta{min} \texttt{to} \meta{max}}{style, no default} + Sets the box height to \meta{min} and allows the height to grow up to \meta{max}. +\begin{dispExample} +% \usepackage{lipsum} +\newtcolorbox{mybox}{colback=red!5!white,colframe=red!75!black,left=1mm,top=1mm, + bottom=1mm,right=1mm,boxsep=0mm,width=4cm,nobeforeafter, + fit height from=1cm to 8cm} + +\begin{mybox} +This is a tcolorbox. +\end{mybox} +\begin{mybox} +This is a tcolorbox. This is a tcolorbox. This is a tcolorbox. +\end{mybox} +\begin{mybox} +\lipsum[2] +\end{mybox} +\end{dispExample} +\end{docTcbKey} + +\clearpage +\begin{docTcbKey}{fit algorithm}{=\meta{name}}{no default, initially |fontsize|} +Sets the algorithm for the fitting process \emph{after} optionally width and height +are adapted. + Feasible values for \meta{name} are: + \begin{itemize} + \item\docValue{fontsize} (initial): + The algorithm is a bisection method that adapts the font size until + certain stop conditions are fulfilled. This is the most time-consuming + method but it is robust and gives pleasant results. + \begin{marker} + The used font has to be freely scalable for this method! + Other content than text is not scaled down. + The aspect ratio is fully garanteed. + \end{marker} + \item\docValue{fontsize*}:\tcbdocmarginnote{\tcbdocnew{2014-10-29}} + First, the \docValue{fontsize} algorithm is applied. If the font was scaled down + and the resulting height is too small, the box is squeezed to fit the area. + \begin{marker} + The used font has to be freely scalable for this method! + Other content than text may be slightly rescaled. + The aspect ratio cannot be fully garanteed. + \end{marker} + \item\docValue{areasize}: + The algorithm calculates the area size for the text without scaling the font. + The text box is shaped for the needed aspect ratio in one or two + steps. Finally, it is scaled down with a standard |\resizebox| macro. + \begin{marker} + The used font has not to be scalable. Every box content is scaled down. + The aspect ratio cannot be fully garanteed. + \end{marker} + \item\docValue{areasize*}:\tcbdocmarginnote{\tcbdocnew{2014-10-29}} + The \docValue{areasize} algorithm is applied, but if the content was scaled + down and the resulting height is too small, the box is squeezed to fit the area. + \begin{marker} + The used font has not to be scalable. Every box content is scaled down. + The aspect ratio cannot be fully garanteed. + \end{marker} + \item\docValue{hybrid}: + First, this algorithm estimates the needed font size in one or two steps. + Then an \docValue{areasize} fitting as above is a applied. + \begin{marker} + The used font has to be freely scalable for this method! + Other content than text may be slightly rescaled. + The aspect ratio cannot be fully garanteed. + \end{marker} + \item\docValue{hybrid*}:\tcbdocmarginnote{\tcbdocnew{2014-10-29}} + First, this algorithm estimates the needed font size in one or two steps. + Then an \docValue{areasize*} fitting as above is a applied. + \begin{marker} + The used font has to be freely scalable for this method! + Other content than text may be slightly rescaled. + The aspect ratio cannot be fully garanteed. + \end{marker} + \item\docValue{squeeze}: + The text box is brutally scaled down to fit. + \begin{marker} + The aspect ratio is very likely to be horrible. + You should not use this method for final documents. + \end{marker} +\end{itemize} + + +\end{docTcbKey} +\begin{dispExample} +% \usepackage{lipsum} +\newtcboxfit{mybox}[1]{colback=red!5!white,colframe=red!75!black,left=1mm,top=1mm, + bottom=1mm,right=1mm,boxsep=0mm,width=3.5cm,height=7cm,nobeforeafter, + before upper=\textcolor{blue}{\rule{5mm}{5mm}}\ , + enhanced,watermark text={\tcbfitsteps}, + fonttitle=\bfseries,adjusted title=#1,fit algorithm=#1} + +\mybox{fontsize}{\lipsum[2]}\hfill +\mybox{hybrid}{\lipsum[2]}\hfill +\mybox{areasize}{\lipsum[2]}\hfill +\mybox{squeeze}{\lipsum[2]} + +Quality \dotfill versus \dotfill Speed +\end{dispExample} + + +\begin{dispExample} +% \usepackage{lipsum} +\newtcboxfit{mybox}[2]{colback=red!5!white,colframe=red!75!black,left=1mm,top=1mm, + size=tight,width=7.2cm,height=5cm,nobeforeafter, + before upper=\textcolor{blue}{\rule{5mm}{5mm}}\ , + enhanced,fonttitle=\bfseries,adjusted title=#2,fit algorithm=#1} + +\mybox{hybrid}{hybrid (possible gap at end)}{\lipsum[1]}\hfill +\mybox{hybrid*}{hybrid* (no gap but possibly squeezed)}{\lipsum[1]} +\end{dispExample} + + +\clearpage +\begin{marker} +The following options set control parameters for the fit algorithm. +Mainly, they apply to the |fontsize| variant, see \refKey{/tcb/fit algorithm}. +The options should be seen as experimental and are likely to change in future versions, +if necessary. +\end{marker} + +\begin{docTcbKey}{fit maxstep}{=\meta{number}}{no default, initially |20|} + Sets the maximal step size for the font size adjustment algorithm. + In normal situations, the algorithm stops before reaching the intial value of 20 steps. + If the box content does not shrink, this value prevents an endless loop. +\end{docTcbKey} + + +\begin{docTcbKey}{fit maxfontdiff}{=\meta{dimension}}{no default, initially |0.1pt|} + The algorithm stops, if the font size is determined within a deviation of + \meta{dimension}. +\end{docTcbKey} + + +\begin{docTcbKey}{fit maxfontdiffgap}{=\meta{dimension}}{no default, initially |1pt|} + The algorithm stops, if the number of lines is determined and the font size is + determined within a deviation of \meta{dimension}. +\end{docTcbKey} + + +\begin{docTcbKey}{fit maxwidthdiff}{=\meta{dimension}}{no default, initially |1pt|} + The algorithm stops, if the (optionally) flexible box width + is determined within a deviation of \meta{dimension}. +\end{docTcbKey} + + +\begin{docTcbKey}{fit maxwidthdiffgap}{=\meta{dimension}}{no default, initially |10pt|} + The algorithm stops, if the number of lines is determined and the (optionally) flexible box width + is determined within a deviation of \meta{dimension}. +\end{docTcbKey} + + +\begin{docTcbKey}{fit warning}{=\meta{value}}{no default, initially |off|} + Typically, the fit control algorithm constructs several auxiliary boxes + to determine the optimal one. If not switched off, the construction of + the auxiliary boxes may produce many |hbox| warnings. This option key + changes the |\hbadness| value. + \begin{itemize} + \item\docValue{off}: Most of |'Underfull \hbox'| and |'Overfull \hbox'| warnings are + switched off (including the ones for the finally used box). + \item\docValue{on}: All warnings for all auxiliary boxes are displayed. + \item\docValue{final}: Only warnings for the finally used box are displayed. + Note that an additional box has to be contructed for theses messages. + \end{itemize} +\end{docTcbKey} + |