summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/graphicxbox/graphicxbox.dtx
blob: cc544604192fa630f086fa3bd6d657aa9ec6dcc7 (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
% \iffalse
%<*copyright>
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% aeb_envelope.sty package,          2014-01-10        %%
%% Copyright (C) 2014  D. P. Story                      %%
%%   dpstory@acrotex.net                                %%
%%   storyd@owc.edu                                     %%
%%                                                      %%
%% This program can redistributed and/or modified under %%
%% the terms of the LaTeX Project Public License        %%
%% Distributed from CTAN archives in directory          %%
%% macros/latex/base/lppl.txt; either version 1 of the  %%
%% License, or (at your option) any later version.      %%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%</copyright>
%<package>\NeedsTeXFormat{LaTeX2e}
%<package>\ProvidesPackage{graphicxbox}
%<package> [2014/01/10 v1.0 Provides graphic backgrounds for parboxes (dps)]
%<*driver>
\documentclass{ltxdoc}
\usepackage[colorlinks,hyperindex]{hyperref}
\pdfstringdefDisableCommands{\let\\\textbackslash}%
\EnableCrossrefs \CodelineIndex
\OnlyDescription  % comment out for implementation details
\begin{document}
  \GetFileInfo{graphicxbox.sty}
  \title{The \textsf{graphicxbox} Package}
  \author{D. P. Story\\
    Email: \texttt{dpstory@acrotex.net}}
  \date{processed \today}
  \maketitle
  \tableofcontents
  \let\Email\texttt
  \DocInput{graphicxbox.dtx}
  \PrintIndex
\end{document}
%</driver>
% \fi
%    \begin{macrocode}
%<*package>
%    \end{macrocode}
%\section{Introduction}
% This is a short package that provides two new commands \cs{graphicxbox} and \cs{fgraphicxbox}, which
% are companion commands to \cs{colorbox} and \cs{fcolorbox} of \textsf{color.dtx}, by D. P. Carlisle.
% The \cs{graphicxbox} inserts a graphical image as a background rather than a background color,
% while \cs{fgraphcxbox} does the same thing, but also draws a colored frame around the box.
%
% This package requires either \textsf{graphicx} or \textsf{graphicxsp} package (the latter calls the first).
% The \textsf{graphicxsp} allows you to embed graphic images once and use them many times, this is ideal for
% this current package. Either of these commands should be loaded before this package.  If you are using the
% \textsf{web} package and want to use \textsf{graphicxsp}, you should load \textsf{graphicxsp} before
% the \textsf{web} package. I will not use the \cs{RequirePackage} command to require either of these
% graphics packages, the reason for this is that \textsf{graphicxsp} contains options the user might
% want to access and I don't want to make this package unduly complicated by adding options to this
% package only to pass them to another.
%
%\section{Example files} We provide three sample files with this distribution.
%\begin{enumerate}
%\item \texttt{grfxbox\_tst.tex} illustrates the basic features available to
%    all users of \textsf{dvips}, \textsf{dvipsone}, \textsf{pdflatex}, and \textsf{xelatex}.
%\item \texttt{grfxbox\_tst\_sp.tex} same as \texttt{grfxbox\_tst.tex}, but uses \texttt{graphicxsp}.
% The drivers \textsf{dvips} or \textsf{dvipsone} are required, and \textsf{Adobe Distiller} required as the PDF creator.
%\item \texttt{grfxbox\_tst\_indians.tex} uses \texttt{graphicxsp} again, but illustrates transparency.
% Distill the file with \texttt{Standard\_transparency.joboptions} which accompanie the \texttt{graphicsp} package.
%\end{enumerate}
% Though we don't have a \cs{RequirePackage} for the required graphics package, we will test for their
% presence and emit a package error.
%    \begin{macrocode}
\@ifpackageloaded{graphicxsp}{}
    {%
        \@ifpackageloaded{graphicx}{}
        {%
            \PackageError{graphicxbox}{%
             Neither the graphicx nor graphicxsp packages are loaded.}%
            {Load the graphicx or graphicxsp package before this one.}%
        }%
    }
%    \end{macrocode}
%\section{Definitions of the two main commands}
%    \begin{macro}{\graphicxbox}
% This command provides a background graphic for a box, similar to \cs{colorbox}.
% The syntax is
%\begin{verbatim}
%   \graphicxbox[<Graphicx(SP)options>]{<graphic>}{<box content>}
%\end{verbatim}
% When \textsf{graphicx} is loaded (and not \textsf{graphicxsp}) the syntax, in example
% form is
%\begin{verbatim}
%   \graphicxbox{mycoolgraphic}{\Huge Hello World!}
%\end{verbatim}
% The first parameter is optional and is passed to the \cs{includegraphics}
% command. Do not use the \texttt{scale}, \texttt{width} or \texttt{height} parameters of
% \cs{includegraphics}. This package uses \texttt{width} and \texttt{height} to set the dimensions
% of the graphic to fit the box.
%
% When \textsf{graphicxsp} (distiller required) is loaded, the optional parameter is used to specify
% the name of the embedded graphic to be used, in this case, the second argument \verb!{<graphic>}!
% is not used. For example,
% \begin{verbatim}
%   \embedEPS{indianblanket}{IndianBlnkt}
%   ...
%   ...
%   \graphicxbox[name=indianblanket]{}{\Huge Hello World!}
%\end{verbatim}
% The \texttt{indianblanket} graphic can be used and reused many time without increasing the file size
% significantly.  The other advantage of using the \textsf{graphicxsp} package is that it supports
% transparency. See the demo files that accompany this package.
%    \begin{macrocode}
\newcommand{\graphicxbox}[2][]{\graphicx@b@x\relax{#1}{#2}}
%    \end{macrocode}
%    \end{macro}
%    \begin{macro}{\fgraphicxbox}
% This command does the same as \cs{graphicxbox}, but additionally, adds a colored
% rule framing the box, similar to what \cs{fcolorbox} does. The syntax is
%\begin{verbatim}
%   \fgraphicxbox[<model>]{<specification>}[<Graphicx(SP)options>]
%       {<graphic>}{<box content>}
%\end{verbatim}
% The first two parameters are the same ones used by \cs{fcolorbox}, the color specification.
% The next three parameters are the same as \cs{graphicxbox}. The comments made above
% for the \cs{graphicxbox} hold here as well.
%
% Here is an example for the \textsf{graphicxsp} package:
%\begin{verbatim}
%   \graphicxbox{blue}[name=indianblanket]{}{\Huge Hello World!}
%\end{verbatim}
%
% As with \cs{colorbox} and \cs{fcolorbox}, the lengths \cs{fboxsep} and \cs{fboxrule}. For example,
% if we set
% \begin{verbatim}
%   \setlength{\fboxsep}{10pt}
%   \setlength{\fboxrule}{2pt}
%   \graphicxbox{blue}[name=indianblanket]{}{\Huge Hello World!}
%\end{verbatim}
% we would make the separation between the content and the frame of
% the to be \texttt{10pt} and the rule with to be \texttt{2pt}.
%    \begin{macrocode}
\newcommand{\fgraphicxbox}[2][]{\fgraphicx@box{#1}{#2}}
%    \end{macrocode}
%    \end{macro}
%\section{Internal, supporting commands}
%\DescribeMacro{\fgraphicx@box} continues the flow from \cs{fgraphicxbox}.
% The parameters of \cs{fgraphicx@@box} are
%\begin{verbatim}
%   \fgraphicx@box{model}{color spec}[options for graphicx(sp)]{filename}
%\end{verbatim}
%    \begin{macrocode}
\def\fgraphicx@box#1#2{\@ifnextchar[{\fgraphicx@@box{#1}{#2}}%
    {\fgraphicx@@box{#1}{#2}[]}}
%    \end{macrocode}
%    \begin{macrocode}
\def\fgraphicx@@box#1#2[#3]#4{%
    \graphicx@b@x{\fboxsep\z@\color#1{#2}\fbox}{#3}{#4}}
%    \end{macrocode}
% \DescribeMacro{\graphicx@b@x}\cs{graphicx@b@x} is the low-level command that does all the work
% now that the parameters have been set. This code is a modification
% of \cs{color@b@x} from the \textsf{color.dtx} package.
%    \begin{macrocode}
\long\def\graphicx@b@x#1#2#3#4{\leavevmode
    \setbox\z@\hbox{\kern\fboxsep{\set@color#4}\kern\fboxsep}%
    \dimen@\ht\z@\advance\dimen@\fboxsep\ht\z@\dimen@
    \dimen@\dp\z@\advance\dimen@\fboxsep\dp\z@\dimen@
    {%\color@block{\wd\z@}{\ht\z@}{\dp\z@}%
%    \dimen@ii\dp\z@\advance\dimen@ii\ht\z@
    \dimen@\dp\z@\advance\dimen@\ht\z@
    \edef\gfxb@totalheight{\the\dimen@}%
    {#1{\lower\dp\z@\rlap{%
        \includegraphics[#2,width=\wd\z@,height=\gfxb@totalheight]{#3}}%
     \box\z@}}}%
}
%</package>
%    \end{macrocode}
%  \Finale
\endinput