summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/tcolorbox/tcolorbox.doc.hooks.tex
blob: 351808329788cfb441862a1c7f9296954da09646 (plain)
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
% !TeX root = tcolorbox.tex
% include file of tcolorbox.tex (manual of the LaTeX package tcolorbox)
\clearpage
\section{Library \mylib{hooks}}\label{sec:hooks}
The library is loaded by a package option or inside the preamble by:
\begin{dispListing}
\tcbuselibrary{hooks}
\end{dispListing}

For the skin related options, the library \mylib{skins} has to be loaded
separately.


\subsection{Concept of Hooks}
A hook is a placeholder in some \LaTeX\ code where additional code
can be added. For example, the \LaTeX\ macro |\AtBeginDocument| adds code to a
hook which is placed at the begin of every document.

Several option keys of |tcolorbox| allow to provide some code which is
added to specific places of a colored box. For example, \refKey{/tcb/before upper}
places code before the content of the upper part. A following usage of this
key overwrites any prior settings.

The library \mylib{hooks} extends \refKey{/tcb/before upper} and several more
existing keys to 'hookable' versions, e.\,g.\ 
\refKey{/tcb/before upper app} and \refKey{/tcb/before upper pre}.
The 'hookable' keys don't overwrite prior settings but either \emph{app}end
or \emph{pre}pend the newly given code to the existing code.

The general naming convention (with some small exceptions) is:
\begin{itemize}
\item \meta{option key} |app|: works like \meta{option key} but
  \emph{app}ends its code to the existing code.
\item \meta{option key} |pre|: works like \meta{option key} but
  \emph{pre}pends its code to the existing code.
\end{itemize}
If the original \meta{option key} is used (again), all code will be overwritten.
Therefore, the order of the option key usage is crucial.



\begin{dispExample}
% \usepackage{array,tabularx}
\newcolumntype{Y}{>{\raggedleft\arraybackslash}X}% see tabularx
\tcbset{enhanced,fonttitle=\bfseries\large,fontupper=\normalsize\sffamily,
  colback=yellow!10!white,colframe=red!50!black,colbacktitle=Salmon!30!white,
  coltitle=black,center title,
  tabularx={X||Y|Y|Y|Y||Y},% this sets 'before upper' and 'after upper'
  before upper app={Group & One & Two & Three & Four & Sum\\\hline\hline}  }

\begin{tcolorbox}[title=My table]
Red   & 1000.00 & 2000.00 &  3000.00 &  4000.00 & 10000.00\\\hline
Green & 2000.00 & 3000.00 &  4000.00 &  5000.00 & 14000.00\\\hline
Blue  & 3000.00 & 4000.00 &  5000.00 &  6000.00 & 18000.00\\\hline\hline
Sum   & 6000.00 & 9000.00 & 12000.00 & 15000.00 & 42000.00
\end{tcolorbox}
\end{dispExample}



\clearpage
\subsection{Box Content Additions}\label{subsec:hookscontentadditions}
The following option keys extend the options given in Subsection \ref{subsec:contentadditions}
from page \pageref{subsec:contentadditions}.

\begin{docTcbKey}{before title app}{=\meta{code}}{no default}
  Appends the given \meta{code} to \refKey{/tcb/before title} \emph{after} the color and font settings
  and \emph{before} the content of the title.
\end{docTcbKey}

\begin{docTcbKey}{before title pre}{=\meta{code}}{no default}
  Prepends the given \meta{code} to \refKey{/tcb/before title} \emph{after} the color and font settings
  and \emph{before} the content of the title.
\end{docTcbKey}

\begin{docTcbKey}{after title app}{=\meta{code}}{no default}
  Appends the given \meta{code} to \refKey{/tcb/after title} \emph{after} the content of the title.
\end{docTcbKey}

\begin{docTcbKey}{after title pre}{=\meta{code}}{no default}
  Prepends the given \meta{code} to \refKey{/tcb/after title} \emph{after} the content of the title.
\end{docTcbKey}

\begin{docTcbKey}{before upper app}{=\meta{code}}{no default}
  Appends the given \meta{code} to \refKey{/tcb/before upper} \emph{after} the color and font settings
  and \emph{before} the content of the upper part.
\end{docTcbKey}

\begin{docTcbKey}{before upper pre}{=\meta{code}}{no default}
  Prepends the given \meta{code} to \refKey{/tcb/before upper} \emph{after} the color and font settings
  and \emph{before} the content of the upper part.
\end{docTcbKey}

\begin{docTcbKey}{after upper app}{=\meta{code}}{no default}
  Appends the given \meta{code} to \refKey{/tcb/after upper} \emph{after} the content of the upper part.
\end{docTcbKey}

\begin{docTcbKey}{after upper pre}{=\meta{code}}{no default}
  Prepends the given \meta{code} to \refKey{/tcb/after upper} \emph{after} the content of the upper part.
\begin{dispExample}
% \tcbuselibrary{theorems}
\tcbset{ams align,%  this sets 'before upper' and 'after upper'
  colback=yellow!10!white,colframe=red!50!black,
  before upper app={\frac{2}{\sqrt{2}}&=\sqrt{2}.\\},
  after upper pre={\\\sin\left(\frac{\pi}{2}\right)&=1.},
}

\begin{tcolorbox}
  \sum\limits_{n=1}^{\infty} \frac{1}{n} &= \infty.\\
  \int x^2 ~\text{d}x &= \frac13 x^3 + c.
\end{tcolorbox}
\end{dispExample}
\end{docTcbKey}

\clearpage
\begin{docTcbKey}{before lower app}{=\meta{code}}{no default}
  Appends the given \meta{code} to \refKey{/tcb/before lower} \emph{after} the color and font settings
  and \emph{before} the content of the lower part.
\end{docTcbKey}

\begin{docTcbKey}{before lower pre}{=\meta{code}}{no default}
  Prepends the given \meta{code} to \refKey{/tcb/before lower} \emph{after} the color and font settings
  and \emph{before} the content of the lower part.
\end{docTcbKey}

\begin{docTcbKey}{after lower app}{=\meta{code}}{no default}
  Appends the given \meta{code} to \refKey{/tcb/after lower} \emph{after} the content of the lower part.
\end{docTcbKey}

\begin{docTcbKey}{after lower pre}{=\meta{code}}{no default}
  Prepends the given \meta{code} to \refKey{/tcb/after lower} \emph{after} the content of the lower part.
\end{docTcbKey}


\subsection{Embedding into the Surroundings}
The following option keys extend the options given in Subsection \ref{subsec:surroundings}
from page \pageref{subsec:surroundings}.

\begin{marker}
The 'hookable' versions are usable inside the document.
In the preamble, they can only be used after explicit setting of
\refKey{/tcb/before} and \refKey{/tcb/after} or by e.\,g.\ \refKey{/tcb/parskip}.
\end{marker}

\begin{docTcbKey}{before app}{=\meta{code}}{no default}
  Appends the given \meta{code} to \refKey{/tcb/before} before the colored box.
\end{docTcbKey}

\begin{docTcbKey}{before pre}{=\meta{code}}{no default}
  Prepends the given \meta{code} to \refKey{/tcb/before} before the colored box.
\end{docTcbKey}

\begin{docTcbKey}{after app}{=\meta{code}}{no default}
  Appends the given \meta{code} to \refKey{/tcb/after} after the colored box.
\end{docTcbKey}

\begin{docTcbKey}{after pre}{=\meta{code}}{no default}
  Prepends the given \meta{code} to \refKey{/tcb/after} after the colored box.
\end{docTcbKey}

\begin{dispExample}
\tcbset{colback=red!5!white,colframe=red!75!black,fonttitle=\bfseries}

\begin{tcolorbox}[title=My title,before app={The box follows:\\[4pt]},
  after app={This is the end.}]
This is a \textbf{tcolorbox}.
\end{tcolorbox}
\end{dispExample}


\clearpage
\subsection{Overlays}
The following option keys extend the options given in Subsection \ref{subsec:overlays}
from page \pageref{subsec:overlays}.

\begin{docTcbKey}{overlay app}{=\meta{graphical code}}{no default}
  Appends the given \meta{graphical code} to \refKey{/tcb/overlay}.


\begin{dispExample}
% \usetikzlibrary{patterns} % preamble
% \tcbuselibrary{skins} % preamble
\tcbset{frogbox/.style={enhanced,colback=green!10,colframe=green!65!black,
  enlarge top by=5.5mm,
  overlay={\foreach \x in {2cm,3.5cm} {
    \begin{scope}[shift={([xshift=\x]frame.north west)}]
      \path[draw=green!65!black,fill=green!10,line width=1mm] (0,0) arc (0:180:5mm);
      \path[fill=black] (-0.2,0) arc (0:180:1mm);
    \end{scope}}}]}}
\tcbset{ribbon/.style={overlay app={%
  \path[fill=blue!75!white,draw=blue,double=white!85!blue,
    preaction={opacity=0.6,fill=blue!75!white},
    line width=0.1mm,double distance=0.2mm,
    pattern=fivepointed stars,pattern color=white!75!blue]
    ([xshift=-0.2mm,yshift=-1.02cm]frame.north east)
    -- ++(-1,1) -- ++(-0.5,0) -- ++(1.5,-1.5) -- cycle;}}}

\begin{tcolorbox}[frogbox,title=My title]
This is a \textbf{tcolorbox}.
\end{tcolorbox}

\begin{tcolorbox}[frogbox,ribbon,title=My title]
This is a \textbf{tcolorbox}.\par
Here, we apply a second overlay.
\end{tcolorbox}
\end{dispExample}
\end{docTcbKey}

\begin{docTcbKey}{overlay pre}{=\meta{graphical code}}{no default}
  Prepends the given \meta{graphical code} to \refKey{/tcb/overlay}.
\end{docTcbKey}

\begin{docTcbKey}{overlay unbroken app}{=\meta{graphical code}}{no default}
  Appends the given \meta{graphical code} to \refKey{/tcb/overlay unbroken}.
\end{docTcbKey}

\begin{docTcbKey}{overlay unbroken pre}{=\meta{graphical code}}{no default}
  Prepends the given \meta{graphical code} to \refKey{/tcb/overlay unbroken}.
\end{docTcbKey}

\begin{docTcbKey}{overlay first app}{=\meta{graphical code}}{no default}
  Appends the given \meta{graphical code} to \refKey{/tcb/overlay first}.
\end{docTcbKey}

\begin{docTcbKey}{overlay first pre}{=\meta{graphical code}}{no default}
  Prepends the given \meta{graphical code} to \refKey{/tcb/overlay first}.
\end{docTcbKey}

\clearpage
\begin{docTcbKey}{overlay middle app}{=\meta{graphical code}}{no default}
  Appends the given \meta{graphical code} to \refKey{/tcb/overlay middle}.
\end{docTcbKey}

\begin{docTcbKey}{overlay middle pre}{=\meta{graphical code}}{no default}
  Prepends the given \meta{graphical code} to \refKey{/tcb/overlay middle}.
\end{docTcbKey}

\begin{docTcbKey}{overlay last app}{=\meta{graphical code}}{no default}
  Appends the given \meta{graphical code} to \refKey{/tcb/overlay last}.
\end{docTcbKey}

\begin{docTcbKey}{overlay last pre}{=\meta{graphical code}}{no default}
  Prepends the given \meta{graphical code} to \refKey{/tcb/overlay last}.
\end{docTcbKey}


\begin{docTcbKey}{overlay broken app}{=\meta{graphical code}}{no default}
  Appends the given \meta{graphical code} to \refKey{/tcb/overlay broken}.
\end{docTcbKey}

\begin{docTcbKey}{overlay broken pre}{=\meta{graphical code}}{no default}
  Prepends the given \meta{graphical code} to \refKey{/tcb/overlay broken}.
\end{docTcbKey}

\begin{docTcbKey}{overlay unbroken and first app}{=\meta{graphical code}}{no default}
  Appends the given \meta{graphical code} to \refKey{/tcb/overlay unbroken and first}.
\end{docTcbKey}

\begin{docTcbKey}{overlay unbroken and first pre}{=\meta{graphical code}}{no default}
  Prepends the given \meta{graphical code} to \refKey{/tcb/overlay unbroken and first}.
\end{docTcbKey}

\begin{docTcbKey}{overlay middle and last app}{=\meta{graphical code}}{no default}
  Appends the given \meta{graphical code} to \refKey{/tcb/overlay middle and last}.
\end{docTcbKey}

\begin{docTcbKey}{overlay middle and last pre}{=\meta{graphical code}}{no default}
  Prepends the given \meta{graphical code} to \refKey{/tcb/overlay middle and last}.
\end{docTcbKey}

\clearpage
\subsection{Watermarks}
The following option keys extend the options given in Subsection \ref{subsec:watermarks}
from page \pageref{subsec:watermarks}.

\begin{marker}
Watermarks are special overlays. The \mylib{hooks} library allows the combination
of several watermarks and overlays.
\end{marker}

\begin{docTcbKey}{watermark text app}{=\meta{text}}{no default}
  Appends a \refKey{/tcb/watermark text} to the colored box.
\begin{dispExample}
\tcbset{colback=red!5!white,colframe=red!75!black,fonttitle=\bfseries}

\begin{tcolorbox}[enhanced,title=My title,watermark graphics=Basilica_5.png,
  watermark opacity=0.25,
  watermark text app=Basilica,watermark color=Navy
  ]
\lipsum[1-2]
\tcblower
This example uses a public domain picture from\\
\url{http://commons.wikimedia.org/wiki/File:Basilica_5.png}
\end{tcolorbox}
\end{dispExample}
\end{docTcbKey}

\begin{docTcbKey}{watermark text pre}{=\meta{text}}{no default}
  Prepends a \refKey{/tcb/watermark text} to the colored box.
\end{docTcbKey}

\begin{docTcbKey}{watermark text app on}{=\meta{part} is \meta{text}}{no default}
  Appends a \refKey{/tcb/watermark text on} the named \meta{part} of a break sequence.
\end{docTcbKey}

\begin{docTcbKey}{watermark text pre on}{=\meta{part} is \meta{text}}{no default}
  Prepends a \refKey{/tcb/watermark text on} the named \meta{part} of a break sequence.
\end{docTcbKey}

\clearpage
\begin{docTcbKey}{watermark graphics app}{=\meta{file name}}{no default}
  Appends a \refKey{/tcb/watermark graphics} referenced by \meta{file name} to the colored box.
\end{docTcbKey}

\begin{docTcbKey}{watermark graphics pre}{=\meta{file name}}{no default}
  Prepends a \refKey{/tcb/watermark graphics} referenced by \meta{file name} to the colored box.
\end{docTcbKey}

\begin{docTcbKey}{watermark graphics app on}{=\meta{part} is \meta{file name}}{no default}
  Appends a \refKey{/tcb/watermark graphics on} the named \meta{part} of a break sequence.
  The picture is referenced by \meta{file name}.
\end{docTcbKey}


\begin{docTcbKey}{watermark graphics pre on}{=\meta{part} is \meta{file name}}{no default}
  Prepends a \refKey{/tcb/watermark graphics on} the named \meta{part} of a break sequence.
  The picture is referenced by \meta{file name}.
\end{docTcbKey}


\begin{docTcbKey}{watermark tikz app}{=\meta{graphical code}}{no default}
  Appends a \refKey{/tcb/watermark tikz} with the  given |tikz| \meta{graphical code} to the colored box.
\end{docTcbKey}

\begin{docTcbKey}{watermark tikz pre}{=\meta{graphical code}}{no default}
  Prepends a \refKey{/tcb/watermark tikz} with the  given |tikz| \meta{graphical code} to the colored box.

\begin{dispExample}
% \usepackage{tikz}
\tcbset{colback=red!5!white,colframe=red!75!black,fonttitle=\bfseries,
  watermark color=Navy,watermark opacity=0.25,
  smiley/.style={watermark tikz pre={%
    \path[fill=yellow,draw=yellow!75!red] (0,0) circle (1cm);
    \fill[red] (45:5mm) circle (1mm);
    \fill[red] (135:5mm) circle (1mm);
    \draw[line width=1mm,red] (215:5mm) arc (215:325:5mm);}}}

\begin{tcolorbox}[enhanced,title=My title, watermark text=Watermark,
  smiley]
\lipsum[1-2]
\end{tcolorbox}
\end{dispExample}
\end{docTcbKey}

\begin{docTcbKey}{watermark tikz app on}{=\meta{part} is \meta{graphical code}}{no default}
  Appends a \refKey{/tcb/watermark tikz on} the named \meta{part} of a break sequence.
\end{docTcbKey}

\begin{docTcbKey}{watermark tikz pre on}{=\meta{part} is \meta{graphical code}}{no default}
  Prepends a \refKey{/tcb/watermark tikz on} the named \meta{part} of a break sequence.
\end{docTcbKey}


\subsection{Skin Code}
The following option keys extend the options given in Subsection \ref{subsec:addcodeoptions}
from page \pageref{subsec:addcodeoptions}.

\begin{marker}
The following code options are applicable only for skins which
use engines of type |freelance|. If you intend to add only a few things
to an existing skin, you should consider using overlays instead.
\end{marker}

\begin{docTcbKey}{frame code app}{=\meta{graphical code}}{no default}
  Appends the given \meta{graphical code} to \refKey{/tcb/frame code}.
\end{docTcbKey}

\begin{docTcbKey}{frame code pre}{=\meta{graphical code}}{no default}
  Prepends the given \meta{graphical code} to \refKey{/tcb/frame code}.
\end{docTcbKey}

\begin{docTcbKey}{interior titled code app}{=\meta{graphical code}}{no default}
  Appends the given \meta{graphical code} to \refKey{/tcb/interior titled code}.
\begin{dispExample}
\begin{tcolorbox}[title=My title,freelance,colframe=Navy,
  frame code app={\draw[yellow,line width=1cm] (
    frame.south west)--(frame.north east);},
  interior titled code app={\draw[red,line width=1cm]
    (frame.north west)--(frame.south east);},
  ]
\lipsum[1]
\end{tcolorbox}
\end{dispExample}
\end{docTcbKey}

\begin{docTcbKey}{interior titled code pre}{=\meta{graphical code}}{no default}
  Prepends the given \meta{graphical code} to \refKey{/tcb/interior titled code}.
\end{docTcbKey}

\begin{docTcbKey}{interior code app}{=\meta{graphical code}}{no default}
  Appends the given \meta{graphical code} to \refKey{/tcb/interior code}.
\end{docTcbKey}

\begin{docTcbKey}{interior code pre}{=\meta{graphical code}}{no default}
  Prepends the given \meta{graphical code} to \refKey{/tcb/interior code}.
\end{docTcbKey}

\begin{docTcbKey}{segmentation code app}{=\meta{graphical code}}{no default}
  Appends the given \meta{graphical code} to \refKey{/tcb/segmentation code}.
\end{docTcbKey}

\begin{docTcbKey}{segmentation code pre}{=\meta{graphical code}}{no default}
  Prepends the given \meta{graphical code} to \refKey{/tcb/segmentation code}.
\end{docTcbKey}


\begin{docTcbKey}{title code app}{=\meta{graphical code}}{no default}
  Appends the given \meta{graphical code} to \refKey{/tcb/title code}.
\end{docTcbKey}

\begin{docTcbKey}{title code pre}{=\meta{graphical code}}{no default}
  Prepends the given \meta{graphical code} to \refKey{/tcb/title code}.
\end{docTcbKey}