summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/tcolorbox/tcolorbox.doc.graphics.tex
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
committerNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
commite0c6872cf40896c7be36b11dcc744620f10adf1d (patch)
tree60335e10d2f4354b0674ec22d7b53f0f8abee672 /macros/latex/contrib/tcolorbox/tcolorbox.doc.graphics.tex
Initial commit
Diffstat (limited to 'macros/latex/contrib/tcolorbox/tcolorbox.doc.graphics.tex')
-rw-r--r--macros/latex/contrib/tcolorbox/tcolorbox.doc.graphics.tex198
1 files changed, 198 insertions, 0 deletions
diff --git a/macros/latex/contrib/tcolorbox/tcolorbox.doc.graphics.tex b/macros/latex/contrib/tcolorbox/tcolorbox.doc.graphics.tex
new file mode 100644
index 0000000000..e99c8271b7
--- /dev/null
+++ b/macros/latex/contrib/tcolorbox/tcolorbox.doc.graphics.tex
@@ -0,0 +1,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}
+
+