% !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 \zvref{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}.
Note that \meta{options} will be fully expanded.

\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 \refPkg{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}