summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/tcolorbox/tcolorbox.doc.graphics.tex
blob: e99c8271b797c1a98f4404ac5b30bf3d5bc34251 (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
% !TeX root = tcolorbox.tex
% include file of tcolorbox.tex (manual of the LaTeX package tcolorbox)
\clearpage
\section{Inclusion of Boxed Image Files}\label{sec:includegraphics}%
\tcbset{external/prefix=external/graphics_}%
The \mylib{skins} library adds some commands to conveniently include
boxed image files.
For the following macros and options, the \mylib{skins} library has to be loaded
by a package option or inside the preamble by:
\begin{dispListing}
\tcbuselibrary{skins}
\end{dispListing}

See \Vref{sec:skins} for the documentation of all other options of the \mylib{skins} library.

\subsection{Macros}

\begin{docCommand}[doc new and updated={2014-11-14}{2016-07-13}]{tcbincludegraphics}{\oarg{options}\marg{file name}}
  In principle, this macro includes an image file denoted by \meta{file name}
  using the standard |\includegraphics| and puts it into a \refEnv{tcolorbox}.
  The \meta{options} are |tcolorbox| keys to set up the colored box.
  Use \refKey{/tcb/graphics options} to specify options for the underlying
  |\includegraphics|.
  Some |tcolorbox| option keys are automatically set, namely \refKey{/tcb/enhanced} and
  options to center the image inside the box.

  The sizing of the included image is done depending on the following:
  \begin{itemize}
  \item If a \refKey{/tcb/width} is specified, but no fixed \refKey{/tcb/height},
    the image is sized to fill the inner width of the box. The height of the
    box adapts to the image.
  \item If a fixed \refKey{/tcb/height} is specified, the image is sized to fill
    the fixed inner area of the box.
  \item If the \refKey{/tcb/capture} mode \refKey{/tcb/hbox} is specified,
    the image is sized according to given |\includegraphics| options only.
    The box adapts to the image.
  \end{itemize}

\begin{dispExample}
% \tcbuselibrary{raster}
\begin{tcbraster}[raster columns=3,raster force size=false,size=fbox,
    colframe=red!50!black,colback=red!20!black,
    fonttitle=\bfseries,center title,drop fuzzy shadow]
  \tcbincludegraphics[title=Normal]{goldshade.png}
  \tcbincludegraphics[title=Fixed height,height=3cm]{goldshade.png}
  \tcbincludegraphics[title=hbox mode,hbox,graphics options={width=3cm}]
    {goldshade.png}
\end{tcbraster}
\end{dispExample}

\clearpage
The auxiliary macro \docAuxCommand{imagename} may be used inside
\refCom{tcbincludegraphics} to display the name of the file.
\docAuxCommand{imagename} is already partially detokenized and is allowed to
contain special characters like the underscore. Note that an appropriate
font is required to display such characters.
%\docAuxCommand{imagepath}%

\begin{dispExample}
% \tcbuselibrary{raster}
\begin{tcbraster}[size=fbox,
    colframe=red!50!black,colback=red!20!black,
    fonttitle=\bfseries\ttfamily,center title,drop fuzzy shadow]
  \tcbincludegraphics[title=\imagename]{goldshade.png}
  \tcbincludegraphics[finish={
    \node[fill=white,fill opacity=0.5,text opacity=1]
    at (frame.center) {\bfseries\ttfamily\imagename};}]{blueshade.png}
\end{tcbraster}
\end{dispExample}
\end{docCommand}

\clearpage
\begin{docCommand}[doc new=2014-11-14]{tcbincludepdf}{\oarg{options}\marg{file name}}
This is a generalized version of \refCom{tcbincludegraphics} which allows
to include a complete PDF file denoted by \meta{file name}.
Every page is boxed into an own \refEnv{tcolorbox} customized by the
given \meta{options}. It is reasonable to put such a series of boxes
inside a \refEnv{tcbraster} for alignment.

Use \refKey{/tcb/graphics pages} to use a selection of pages instead of
using the whole file.

The auxiliary macro \docAuxCommand{imagepage} may be used inside
\refCom{tcbincludepdf} to display the current page number.
\end{docCommand}


\begin{dispListing}
% \tcbuselibrary{raster}
\begin{tcbraster}[raster columns=3,colframe=blue,colback=white,
  colbacktitle=blue!50!white,fonttitle=\small\bfseries\ttfamily,
  left=0pt,right=0pt,top=0pt,bottom=0pt,boxsep=0pt,boxrule=0.6pt,
  toptitle=1mm,bottomtitle=1mm,drop lifted shadow,center title,
  graphics pages={1,...,6},title={\imagename\ [\imagepage]}]
\tcbincludepdf{tcolorbox-example.pdf}
\end{tcbraster}
\end{dispListing}
{\tcbusetemp}


\clearpage
\subsection{Option Keys}

\begin{docTcbKey}[][doc new and updated={2014-11-14}{2018-03-18}]{graphics options}{=\meta{options}}{no default, initially empty}
Used for \refCom{tcbincludegraphics} and \refCom{tcbincludepdf} to
specify |\includegraphics| \meta{options}.

\begin{dispExample}
% \tcbuselibrary{raster}
\begin{tcbraster}[raster columns=3,size=fbox,raster equal height,
    colframe=red!50!black,colback=red!20!black,drop fuzzy shadow]
  \tcbincludegraphics{goldshade.png}
  \newcommand{\myangle}{angle=20}%
  \tcbincludegraphics[graphics options=\myangle]{goldshade.png}
  \tcbincludegraphics[graphics options={viewport=0cm 0cm 8cm 4cm,clip}]
    {goldshade.png}
\end{tcbraster}
\end{dispExample}
\end{docTcbKey}


\begin{docTcbKey}[][doc new=2014-11-14]{graphics directory}{=\meta{directory}}{no default, initially empty}
Used for \refCom{tcbincludegraphics} and \refCom{tcbincludepdf} to
specify a file system \meta{directory} where the image files are located.
\begin{dispListing}
\tcbset{
  graphics directory={.},
  graphics directory={examples},
  graphics directory={../../pictures},
}
\end{dispListing}
\smallskip
\begin{marker}
The |\graphicspath| macro from the |graphics| package is superior to this option.
\refKey{/tcb/graphics directory} may be used especially for
\refCom{tcbincludepdf}.
\end{marker}
\end{docTcbKey}

\begin{docTcbKey}[][doc new=2014-11-14]{graphics pages}{=\meta{selection}}{no default, initially |1,...,|\cs{pdfpages}}
Used for \refCom{tcbincludepdf} to specify a \meta{selection} of pages to be included.
The largest page number is accessible by \docAuxCommand{pdfpages}.
The \meta{selection} has to be given using the |\foreach| syntax of \tikzname.
\begin{dispListing}
\tcbset{
  graphics pages={1,3,7},
  graphics pages={1,...,10},
  graphics pages={1,3,...,18},
  graphics pages={100,...,\pdfpages},
}
\end{dispListing}
\end{docTcbKey}

\clearpage


\begin{docTcbKey}[][doc new=2018-03-21]{graphics orientation}{=\meta{orientation}}{no default, initially |as-is|}
  Used for \refCom{tcbincludegraphics} and \refCom{tcbincludepdf} to
  guarantee a certain \meta{orientation} of the included image.
  After all other options for the image are processed, the result is possibly
  rotated to be in landscape or portrait mode.

  Feasible values for \meta{orientation} are:
  \begin{itemize}
  \item\docValue{as-is}: no rotation of the processed image.
  \item\docValue{landscape}:
    the processed image is possibly rotated by 90 degrees
    to ensure that the final width is not smaller than the final height.
  \item\docValue{landscape*}:
    the processed image is possibly rotated by -90 degrees
    to ensure that the final width is not smaller than the final height.
  \item\docValue{portrait}:
    the processed image is possibly rotated by 90 degrees
    to ensure that the final height is not smaller than the final width.
  \item\docValue{portrait*}:
    the processed image is possibly rotated by -90 degrees
    to ensure that the final height is not smaller than the final width.
  \end{itemize}

\begin{dispExample}
% \tcbuselibrary{raster}
\begin{tcbraster}[raster columns=6,size=fbox,raster equal height,
    colframe=red!50!black,colback=red!20!black,drop fuzzy shadow]
  \tcbincludegraphics{Basilica_5.png}
  \tcbincludegraphics[graphics orientation=landscape]{Basilica_5.png}
  \tcbincludegraphics[graphics orientation=portrait]{Basilica_5.png}
  \tcbincludegraphics[graphics orientation=portrait*]{Basilica_5.png}
  \tcbincludegraphics[graphics options={viewport=0cm 0cm 2cm 3cm,clip}]
    {goldshade.png}
  \tcbincludegraphics[graphics options={viewport=0cm 0cm 2cm 3cm,clip},
    graphics orientation=landscape]{goldshade.png}
\end{tcbraster}
\end{dispExample}


\end{docTcbKey}