1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
|
% !TeX root = tcolorbox.tex
% include file of tcolorbox.tex (manual of the LaTeX package tcolorbox)
\clearpage
\section{Library \mylib{fitting}}\label{sec: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 principal, 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}
\tcbset{colframe=blue!50!black,colback=red!10!white,
boxsep=0pt,top=1mm,bottom=1mm,left=1mm,right=1mm,
nobeforeafter,width=(\linewidth-2mm)/3}
\tcboxfit[height=8cm]{\lipsum[1]}\hfill
\tcboxfit[height=4cm]{\lipsum[1]}\hfill
\tcboxfit[height=2cm]{\lipsum[1]}
\medskip
\tcbset{width=(\linewidth-2mm)/2,colback=green!10!white,boxsep=1mm}
\tcboxfit[height=4cm]{\lipsum[2]}\hfill
\tcboxfit[height=4cm,title=With a title]{\lipsum[2]}
\end{dispExample}
\end{docCommand}
\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 to set 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,center upper}
\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,center upper,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*}
\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, 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{marker}
The following options set control parameters for the fit algorithm.
The algorithms is a bisection method which stops if certain stop conditions
are fulfilled.
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 |off|: Most of |'Underfull \hbox'| and |'Overfull \hbox'| warnings are
switched off (including the ones for the finally used box).
\item |on|: All warnings for all auxiliary boxes are displayed.
\item |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}
|