summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/icon-appr/docs/iconappr-man.tex
blob: 4d27694b786ce2663dcce169b6156061e4c97006 (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
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
\documentclass{article}
\usepackage[fleqn]{amsmath}
\usepackage[
    web={centertitlepage,designv,forcolorpaper,tight*,latextoc,pro},
    eforms={req=2018/11/10},aebxmp
]{aeb_pro}
\usepackage{icon-appr}\previewOff
\usepackage{array,fancyvrb}
\usepackage[showembeds,!draft]{graphicxsp}
\usepackage{aeb_mlink}
\usepackage{icon-appr}

\usepackage{xbmks}
\DeclareInitView{layoutmag={navitab:UseOutlines}}
\xbmksetup{colors={int=red},styles={intbf}}

\advance\marginparwidth 14pt

\begin{embedding}
\embedEPS[hiresbb,name=mani]{../examples/graphics/man1}
\embedEPS[hiresbb,name=girl]{../examples/graphics/girl}
\embedEPS[hiresbb,name=scot]{../examples/graphics/scot}
\end{embedding}

%\usepackage{myriadpro}
%\usepackage{calibri}
\usepackage[altbullet]{lucidbry}

\def\hardspace{{\fontfamily{cmtt}\selectfont\symbol{32}}}
\let\uif\textsf
\def\psf#1{\textsf{\textbf{#1}}}
\def\mpFmt{\raggedleft\itshape\small}

\usepackage{acroman}
\usepackage[active]{srcltx}

\urlstyle{tt}
%\renewcommand\LayoutTextField[2]{#2}

\def\STRUT{\rule{0pt}{14pt}}

\DeclareDocInfo
{
    university={\AcroTeX.Net},
    title={The \textsf{icon-appr} Package},
    author={D. P. Story},
    email={dpstory@acrotex.net},
    subject=Documentation for the icon-appr package,
    talksite={\url{www.acrotex.net}},
    version={1.2.1, 2020/06/13},
    Keywords={LaTeX, form field, icon appearances, AcroTeX},
    copyrightStatus=True,
    copyrightNotice={Copyright (C) \the\year, D. P. Story},
    copyrightInfoURL={http://www.acrotex.net}
}

\universityLayout{fontsize=Large}
\titleLayout{fontsize=LARGE}
\authorLayout{fontsize=Large}
\tocLayout{fontsize=Large,color=aeb}
\sectionLayout{indent=-62.5pt,fontsize=large,color=aeb}
\subsectionLayout{indent=-31.25pt,color=aeb}
\subsubsectionLayout{indent=0pt,color=aeb}
\subsubDefaultDing{\texorpdfstring{$\bullet$}{\textrm\textbullet}}

\chngDocObjectTo{\newDO}{doc}
\begin{docassembly}
var titleOfManual="The icon-appr Package";
var manualfilename="Manual_BG_Print_iconappr.pdf";
var manualtemplate="Manual_BG_Brown.pdf"; // Blue, Green, Brown
var _pathToBlank="C:/Users/Public/Documents/ManualBGs/"+manualtemplate;
var doc;
var buildIt=false;
if ( buildIt ) {
    console.println("Creating new " + manualfilename + " file.");
    doc = \appopenDoc({cPath: _pathToBlank, bHidden: true});
    var _path=this.path;
    var pos=_path.lastIndexOf("/");
    _path=_path.substring(0,pos)+"/"+manualfilename;
    \docSaveAs\newDO ({ cPath: _path });
    doc.closeDoc();
    doc = \appopenDoc({cPath: manualfilename, oDoc:this, bHidden: true});
    f=doc.getField("ManualTitle");
    f.value=titleOfManual;
    doc.flattenPages();
    \docSaveAs\newDO({ cPath: manualfilename });
    doc.closeDoc();
} else {
    console.println("Using the current "+manualfilename+" file.");
}
var _path=this.path;
var pos=_path.lastIndexOf("/");
_path=_path.substring(0,pos)+"/"+manualfilename;
\addWatermarkFromFile({
    bOnTop:false,
    bOnPrint:false,
    cDIPath:_path
});
\executeSave();
\end{docassembly}


\begin{document}

\maketitle

\pdfbookmarkx[1]{Title Page}[action={\Named{FirstPage}}]{TitlePage}
\pdfbookmarkx[1]{Links to AcroTeX.Net}[action={/S/GoTo/D(undefined)},%
  color=magenta,style={bf}]{acrotex}
\belowpdfbookmarkx{http://www.acrotex.net}[action={\URI{http://www.acrotex.net}},%
  color=magenta,style={bf}]{home}
\belowpdfbookmarkx{http://blog.acrotex.net}[action={\URI{http://blog.acrotex.net}},%
  color=magenta,style={bf}]{blog}

\selectColors{linkColor=black}
\tableofcontents
\selectColors{linkColor=webgreen}

\section{Introduction}\label{intro}

In this package, we provide commands and methods for creating icon
appearances for form field buttons, which includes push buttons, check box
buttons, and radio buttons. Below are examples of the three types of buttons
having icon appearances, rather than their customary appearances:
\begin{flushleft}
\hskip15pt
\pushButton[\BC{}\BG{}\autoCenter{y}
%  \A{\JS{app.alert("AcroTeX rocks!")}}
  \TP{1}\BG{}\S{S}
  \I{\mani}
  \RI{\girl}
  \IX{\scot}
]{myButton}{50bp}{50bp}\qquad
%
\checkBox[\BC{}\BG{}
    \V{Off}\DV{Off}\AS{Off}\H{N}\autoCenter{y}
    \AP{/N << \On{Man}{\mani} \Off{\girl} >> }
    ]{myCkBx}{22bp}{22bp}{Man}\qquad %(Girl is `off', Man is `on')\hfill
%
\radioButton[\BC{}\BG{}
  \V{Off}\DV{Off}\AS{Off}\H{N}\autoCenter{y}
  \AP{/N << \On{Man}{\mani} \Off{\girl} >> }
  ]{myRadBtn}{22bp}{22bp}{Man}\quad
\radioButton[\BC{}\BG{}
  \V{Off}\DV{Off}\AS{Off}\H{N}\autoCenter{y}
  \AP{/N << \On{Man}{\mani} \Off{\girl} >> }
  ]{myRadBtn}{22bp}{22bp}{Man}\quad
\radioButton[\BC{}\BG{}
  \V{Off}\DV{Off}\AS{Off}\H{N}\autoCenter{y}
  \AP{/N << \On{Man}{\mani} \Off{\girl} >> }
  ]{myRadBtn}{22bp}{22bp}{Man}\qquad %(Girl is `off', Man is `on')\hfill
%
\pushButton[\CA{Reset}\A{\JS{this.resetForm();}}]{reset}{.5in}{11bp}\hfill
\parbox{1.5in}{\footnotesize For the check box and radio buttons, the Girl is `off'
and the Man is `on'}%
\\[3pt]\hglue15pt
\bgroup\fboxsep0pt\relax\footnotesize
\makebox[52bp][c]{\hss Push button\hss}\qquad
\makebox[24bp][c]{\hss Check box\hss}\qquad
\makebox[66bp+2bp+2em][c]{\hss Radio buttons\hss}\\[3pt]
\makebox[52bp][c]{\hfill}\qquad
\egroup
\end{flushleft}
The two sections that follow document the environment, commands, and methods for producing the
above results. The above buttons are used in the demo files, these are found in the
\textsf{examples} folder:
\begin{itemize}
\item \texttt{examples/icon-appr.exmpl.tex}
\item \texttt{examples/pdfmark-drivers/icon-appr-pb.tex}
\item \texttt{examples/pdfmark-drivers/icon-appr-eps.tex}
\item \texttt{examples/pdfmark-drivers/icon-appr-eps-transp.tex}.
\end{itemize}
The first one listed above is for the \app{pdflatex}, \app{lualatex}, and
\app{xelatex} drivers (applications), the latter three are designed for users
of the \app{dvips\,->\,distiller} workflow.

\newtopic\noindent
The \pkg{eforms}\marginpar{\mpFmt\pkg{eforms} package
required} package, dated 2018/11/10 or later, is required to create buttons
with icon appearances, this is because, as of this writing, the form fields
produced by \pkg{hyperref} do not support the necessary markup to produce
icon appearances.

\subsection{What new: Version 1.2 (2020/06/05)}

The basic functionality of this package is unchanged, as documented in
subsequent sections. In this version, the \textbf{\textsf{AP}} entry is added
to the \textbf{\textsf{Names}} dictionary of the PDF catalog. For this manual,
the following code appears, new bits are highlighted in bold. The second line
is the \textbf{\textsf{Names}} dictionary.
\begin{Verbatim}[commandchars={!@^}]
124 0 obj
<<!textbf@/AP 117 0 R^/Dests 85 0 R/JavaScript 125 0 R>>
endobj
...
117 0 obj
!textbf@<</Names[(girl)151 0 R(mani)137 0 R(scot)162 0 0 R]>>^
endobj
\end{Verbatim}
The \textbf{\textsf{AP}} entry
references the indirect object \textbf{\textsf{Names}} dictionary consisting
of the icon names and their indirect references. The tricky part is that
the names in this \textbf{\textsf{Names}} array must be listed in alphabetical
order. The \pkg{datatool} package is used for this purpose.\footnote{\url{https://ctan.org/pkg/datatool}}

This means that the names of the icons imported in the \env{embedding}
environment are known to \app{Acrobat/Adobe Reader}. It also allows the icons
to be manipulated using JavaScript methods; for example, use the button below
to cycle through all icons in this document.

\begin{defineJS}{\cycleJS}
if (typeof indexIcon == "undefined") var indexIcon=0;
var oIconName=this.icons[indexIcon].name;
var f=this.getField("iconContainer");
var oIcon=this.getIcon(oIconName);
f.buttonPosition=position.iconTextV;
f.buttonSetIcon(oIcon);
f.buttonSetCaption(oIconName);
indexIcon = (indexIcon+1) \% (this.icons.length);
\end{defineJS}

% the display as before.
\begin{defineJS}{\clearJS}
f=this.getField("iconContainer")
// save
var sv=f.buttonPosition;
var cptn=f.buttonGetCaption();
// clear
f.buttonPosition=position.textOnly;
f.buttonSetCaption("");
\end{defineJS}


\begin{center} %\previewOn\pmpvOn
\pushButton[\BG{}\autoCenter{n}
  \TP{2}\I{}\S{S}]{iconContainer}{100bp}{100bp}\vcgBdry[6bp]
\pushButton[\CA{Show me the icons!}\AAmouseup{\cycleJS}]{cycleBtn}{}{11bp}\olBdry
\pushButton[\CA{Clr}\TU{Clear the display}\AAmouseup{\clearJS}]{clearBtn}{}{11bp}
\end{center}

\noindent
The underlying JavaScript of the push button uses the \texttt{this.getIcon(\ameta{icon-name})} method.
To use this method, the icons must be known, and now they are! All icons appearing in this document
are EPS files, BION,\footnote{Believe it or not} yet we can still manipulate their images using JavaScript.
\app{Adobe Reader} supports \texttt{\meta{Doc}.getIcon(\ameta{icon-name})}. \mlsetLink[\A{\JS{%
console.clear();\r console.show();\r console.println("this.icons");}}]{Open the JavaScript console}, place
your cursor on \textsf{this.icons}, and press \textsf{Ctrl+Enter}, \app{Acrobat/Reader} gives a readout of
the icons known to this document. The above example is reproduced in \texttt{icon-appr-exmpl.tex} and
\texttt{icon-appr-eps.tex}.

\section{Methods for non-\textsf{pdfmark} drivers}\label{nPdfmark}

The supported `non-\psf{pdfmark}' drivers are \app{pdflatex}, \app{lualatex}, and
\app{xelatex}\marginpar{\mpFmt\app{pdflatex}\\ \app{lualatex}\\ \app{xelatex}}. To create icon appearances, embed the icon files with the
\cs{embedIcon} command from within the \env{embedding} environment. This
occurs in the preamble of the document.
\bVerb\takeMeasure{\string\embedIcon[\ameta{KV-pairs]\darg{\ameta{path}}}} %
\begin{dCmd}[commandchars=!()]{\bxSize}
\begin{embedding}
\embedIcon[!ameta(KV-pairs)]{!ameta(path)}
...
\end{embedding}
\end{dCmd}
\eVerb The \cs{embedIcon} embeds the icon file (\ameta{path}) in the
document; it can then be referenced multiple times without significantly
increasing the file size. The two relevant key-values (\ameta{KV-pairs}) are
\texttt{name=\ameta{name}}\marginpar{\mpFmt The \texttt{name} key} and
\texttt{hyopts=\darg{\ameta{various}}}. Internally, \ameta{name} is made into
a control sequence (\cs{\ameta{name}}) which is used to reference the
embedded icon file in the form field markup. Normally, \ameta{name} consists
of letters, no active characters allowed; if \ameta{name} contains
non-letters, its name may be referenced using the \cs{csOf}\marginpar{\mpFmt
The \cs{csOf} cmd} command (\cs{csOf\darg{\ameta{name}}}). The other
key-value pair is \texttt{hyopts=\darg{\ameta{various}}}\marginpar{\mpFmt The
\texttt{hyopts} key}, the value \ameta{various} are key-values of the
\cs{includegraphics} command, which is used in the background. Passing any
key-value through to \cs{includegraphics} may or may not have an effect. One
useful key is the \texttt{page} key; when \ameta{path} leads to a multi-page
PDF file, and \app{xelatex} is \emph{not being used},
\texttt{page=\ameta{num}} retrieves page~\ameta{num} from the PDF document.

\paragraph*{Example.} We reproduce part of the file \texttt{icon-app-exmpl.tex}. First, in the preamble,
embed all icon files to be used.
\begin{Verbatim}[xleftmargin=\parindent,fontsize=\small]
\begin{embedding}
\embedIcon[name=mani]{graphics/man1.pdf}
\embedIcon[name=girl]{graphics/girl.pdf}
\embedIcon[name=scot]{graphics/scot.pdf}
\end{embedding}
\end{Verbatim}
From these declarations, the commands \cs{mani}, \cs{girl}, and \cs{scot} are
defined. Now in the body of the document, we create a push button:
\begin{Verbatim}[xleftmargin=\parindent,commandchars=!(),fontsize=\small]
\pushButton[%
  \TP{1}\BG{}\S{S}
  \I{\csOf{mani}}  %!normalfont( normal appearance, where we use !texttt(\csOf) to demonstrate its use)
  \RI{\girl}       %!normalfont( rollover appearance, here, we reference the icon using !texttt(\girl))
  \IX{\scot}       %!normalfont( down appearance, we reference the icon using !texttt(\scot))
]{myButton}{50bp}{50bp}
\end{Verbatim}
The same techniques work for choice boxes and radio button fields. Refer to sample file \texttt{icon-appr-exmpl.tex}
for a working example.

\section{Methods for \textsf{pdfmark} drivers}

For the \psf{pdfmark} driver \app{dvips}\marginpar{\mpFmt\sffamily dvips}, there
are two techniques that have been developed. These techniques were developed because
EPS files are the only graphics files \app{dvips} work with.
\begin{itemize}
   \item \textbf{JavaScript approach:} Acrobat JavaScript has a method for
       embedding a number of graphics file formats as icons, which can then
       be used as icon appearance faces. This method requires the
       \app{Acrobat} application to open the newly created PDF file, after
       \app{Distiller} (or \app{ps2pdf}) has created the PDF file. Any
       supported graphics file format can be used. The method is explained
       in detail in \hyperref[s:JSMethods]{Section~\ref*{s:JSMethods}}.

   \item \textbf{Purely EPS approach:} We can use exclusively EPS files for
       icon appearances; in fact, the examples given in the
       \textbf{Introduction} section on page~\pageref{intro} were created by this
       method. Details are found in \hyperref[s:EPSMethods]{Section~\ref*{s:EPSMethods}}.
\end{itemize}

\subsection{The JavaScript approach}\label{s:JSMethods}

\textbf{Requirements:} The {\LaTeX} package
\pkg{aeb\_pro}\marginpar{\mpFmt\pkg{aeb\_pro} package} is
required as it supplies the JavaScript code.
\app{Distiller}\marginpar{\mpFmt \app{Distiller} or
\app{ps2pdf}, and \app{Acrobat}} or \app{ps2pdf} is used to create the PDF.
Open the file in \app{Acrobat} where the JavaScript is executed to embed
referenced files as icon objects and associate icon files with push button
appearances.

This method only applies to push buttons\marginpar{\mpFmt
push buttons only}, not to check box or radio button fields. Again, the
basic elements to use are the \env{embedding} environment in the preamble and
the \cs{embedIcon} command.
\bVerb\takeMeasure{\string\embedIcon[\ameta{KV-pairs]\darg{\ameta{path}}}} %
\begin{dCmd}[commandchars=!()]{\bxSize}
\begin{embedding}
\embedIcon[!ameta(KV-pairs)]{!ameta(path)}
...
\end{embedding}
\end{dCmd}
\eVerb The set of key-value pairs (\ameta{KV-pairs}) of \cs{embedIcon} is a
little different than the ones listed in
\hyperref[nPdfmark]{Section~\ref*{nPdfmark}}, these are (1) the
\texttt{placement}\marginpar{\mpFmt
\texttt{placement} key} key informs the underlying JavaScript where to place
the icon file; (2) the \texttt{page}\marginpar{\mpFmt
\texttt{page} key} key can be used for multi-page PDF icons files to specify
the number of the page to be used, this is a 0-based page number.

\subparagraph{Syntax for the value of the \texttt{placement} key:} The
\texttt{placement} key ``places'' the image on the button faces of the field
names listed (\texttt{myButton}). A push button has three appearance faces:
normal appearance, rollover appearance, and down appearance. As a result of
this, there is an optional argument that precedes the field name that
determines the face of the button the icon is to appear on; the values are
\texttt{[0]} (default, normal icon);\footnote{When no optional argument
precedes the field name, it is understood to be the normal appearance.}
\texttt{[1]} (down icon); and \texttt{[2]} (rollover icon). The optional
argument precedes the field name, and is shown in the example below. There
must be no space between the optional argument and the field name; if you
type `\texttt{[2]\hardspace myButton}', for example, the field name is
interpreted as `\texttt{\hardspace myButton}', which is incorrect.

\paragraph*{Example.} This is a modified version of the example that appears
in the sample file \texttt{icon-appr-pb.tex}. We begin by embedding the icon
files in the document. The target field has name `\texttt{myButton}' and we
place the images on it: \texttt{man1.pdf} is the normal appearance;
\texttt{scot.gif} is the down appearance; and\texttt{ girl.png} is the
rollover appearance.
\begin{Verbatim}[xleftmargin=\parindent,fontsize=\small]
\begin{embedding}
\embedIcon[placement=myButton]{graphics/man1.pdf}
\embedIcon[placement={[1]myButton}]{graphics/scot.gif}
\embedIcon[placement={[2]myButton}]{graphics/girl.png}
\end{embedding}
\end{Verbatim}
Note the variety of icon file formats used.

In the body of the document, we create a push button. At the time
the button is created, the icon files have not been imported or embedded,
but we indicate that this button uses icon appearances by passing
\verb~\importIcons{y}~ as an optional argument, \emph{this is
important}.\marginpar{\mpFmt Important!}
\begin{Verbatim}[xleftmargin=\parindent,fontsize=\small,commandchars=!()]
\pushButton[\BC{}\BG{}\S{S}!textbf(\importIcons{y})
  \FB{true}\TP{1}]{myButton}{50bp}{50bp}
\end{Verbatim}
When the newly created PDF is first opened in \app{Acrobat} some JavaScript
will execute and embed the icon files in the PDF, then populate the specified
button faces with the specified icons.

By the way, a single \cs{embedIcon} command can provide multiple push buttons with
its icon; the value of \texttt{placement} can be a comma-delimited list of
field names (with optional argument preceding). For example,
\begin{Verbatim}[xleftmargin=\parindent,fontsize=\small]
\begin{embedding}
\embedIcon[placement={myButton,[1]myOtherButton}]{graphics/man1.pdf}
...
\end{embedding}
\end{Verbatim}
Refer to \texttt{icon-appr-pb.tex} for a working example.


\subsection{The purely EPS approach}\label{s:EPSMethods}

\textbf{Requirements.} The EPS method requires the use of the
\pkg{graphicxsp}\marginpar{\mpFmt \pkg{graphicxsp}
required} package, dated 2018/11/20 or later. \app{Distiller} or \app{ps2pdf}
can be used to produce the PDF file; \app{Acrobat} is \emph{not required}
(unless another package requires it). It is strongly recommended that when
creating check boxes or radio button fields that the newly created PDF be
opened in \app{Adobe Reader DC} (or, optionally \app{Acrobat} itself) and
\emph{saved}\marginpar{\mpFmt save the PDF!}. This will
enable users of \app{PDF-XChange Viewer/Editor} to view these buttons
correctly.

The technique is similar to that of the non-\psf{pdfmark}
drivers. Again, we use the \env{embedding} environment in the preamble, but
the \cs{embedEPS} command within the environment is used instead of
\cs{embedIcon}.
\bVerb\takeMeasure{\string\embedEPS[\ameta{KV-pairs]\darg{\ameta{path}}}} %
\begin{dCmd}[commandchars=!()]{\bxSize}
\begin{embedding}
\embedEPS[!ameta(KV-pairs)]{!ameta(path)}
...
\end{embedding}
\end{dCmd}
\eVerb Where \ameta{path} points to an EPS file. The
\texttt{name=\ameta{name}}\marginpar{\mpFmt\texttt{name}
key required} key-value is required in the optional argument
\ameta{KV-pairs}, other key-value pairs are passed to \cs{includegraphics}.

Internally, \ameta{name} is made into a control sequence (\cs{\ameta{name}})
which is used to reference the embedded icon file in the form field markup.
Normally, \ameta{name} consists of letters, no active characters; if
\ameta{name} contains non-letters, its name may be referenced using the
\cs{csOf}\marginpar{\mpFmt The \cs{csOf} cmd} command
(\cs{csOf\darg{\ameta{name}}}).

\paragraph*{Example.} This is a modified version of the example that appears in the sample
file \texttt{icon-appr-eps.tex}.
\begin{Verbatim}[xleftmargin=\parindent,fontsize=\small]
\begin{embedding}
\embedEPS[hiresbb,name=mani]{graphics/man1}
\embedEPS[hiresbb,name=girl]{graphics/girl}
\embedEPS[hiresbb,name=scot]{graphics/scot}
\end{embedding}
\end{Verbatim}
Here, we pass the \texttt{hiresbb} key to \cs{includegraphics}.
From this declarations, the command \cs{mani}, \cs{girl}, and \cs{scot} are
defined. Now in the body of the document, we create a push button:
\begin{Verbatim}[xleftmargin=\parindent,commandchars=!(),fontsize=\small]
\pushButton[%
  \TP{1}\BG{}\S{S}
  \I{\csOf{mani}}  %!normalfont( normal appearance, where we use !texttt(\csOf) to demonstrate its use)
  \RI{\girl}       %!normalfont( rollover appearance, here, we reference the icon using !texttt(\girl))
  \IX{\scot}       %!normalfont( down appearance, we reference the icon using !texttt(\scot))
]{myButton}{50bp}{50bp}
\end{Verbatim}
Note that this is the same markup as was presented in \hyperref[nPdfmark]{Section~\ref*{nPdfmark}}.
The same techniques work for choice boxes and radio button fields. Refer to sample file \texttt{icon-appr-eps.tex}
for a working example.

When EPS methods are used, the Adobe transparency model can be used (\app{Distiller} required). See
the sample file \texttt{icon-appr-eps-transp.tex}.

\section{Parameters controlling the icon appearance for push buttons}\label{parameters}

The \textbf{MK} entry is used to provide an \emph{appearance characteristic
dictionary} containing additional information for constructing the
annotation's appearance. The \pkg{eforms} package has key-value pairs that
populates the \textbf{MK} dictionary; we describe the entries in the
dictionary, these entries are entered through the optional argument of a
\cs{pushButton} command. In the listing below, we give the key-value pairs,
the first is the original key scheme, the second is the more user-friendly
key. Additional details can be found in \texttt{eformman.pdf}, the documentation
of the \pkg{eform} package.

\begin{itemize}
  \item [\textbf{I}] Indirect reference to the normal appearance of an icon. The keys
  used by eforms are \cs{I} and \texttt{normalappr}.
  \item [\textbf{RI}] Indirect reference to the rollover appearance of an icon. The keys
  are \cs{RI} and \texttt{rollappr}.
  \item [\textbf{IX}] Indirect reference to the down appearance of an icon. The keys
  are \cs{IX} and \texttt{downappr}.
\end{itemize}
\textbf{Note.} When importing icon appearances using JavaScript
(\hyperref[s:JSMethods]{Section~\ref*{s:JSMethods}}), the above three keys
are not used explicitly (JavaScript sets these key-value entries); use
instead the key-value pair \verb~\importIcons{y}~, as seen in the example
given in \hyperref[s:JSMethods]{Section~\ref*{s:JSMethods}}.
\begin{itemize}
  \item [\textbf{IF}] The \emph{icon fit dictionary}. The entries of the \textbf{IF} follow:
  \begin{itemize}
    \item [\textbf{SW}] (name; optional) The circumstances under which the icon should be scaled inside
    the annot rectangle. The key is either \cs{SW} or \texttt{scalewhen}.
    \begin{itemize}
      \item [\textbf{A}] always scale (the default value).\\KVP: \verb!\SW{A}! or \texttt{scalewhen=always}.
      \item [\textbf{B}] Scale only when the icon is bigger than the annotation rectangle.\\KVP: \verb!\SW{B}!
      of \texttt{scalewhen=iconbig}.
      \item [\textbf{S}] Scale only when the icon is smaller than the rectangle.\\KVP: \verb!\SW{S}!
      or \texttt{scalewhen=iconsmall}.
      \item [\textbf{N}] Never Scale.\\KVP: \verb!\SW{N}! or \texttt{\texttt{scalewhen=never}}.
    \end{itemize}
    \item [\textbf{S}] (name; optional) The type of scaling to use
    the annot rectangle. The key to use is \cs{ST} or \texttt{scale}.
    \begin{itemize}
        \item [\textbf{A}] \emph{Anamorphic scaling:} Scale the icon to fill the annotation exactly, without
              regard to the original aspect ratio.\\KVP: \verb!\ST{A}! or \texttt{scale=nonproportional}.
        \item [\textbf{P}] \emph{Proportional scaling:} Scale the icon to fit the width or height
        of the rectangle while maintaining the icon's original aspect ratio (ratio width to height)
        (the default).\\KVP: \verb!\ST{P}! or \texttt{scale=proportional}.
    \end{itemize}

    \item [\textbf{A}] (array; optional) An array of two numbers between $0.0$ and $1.0$ indicating the fraction of the left
    over space to allocate at the left and bottom of the icon. A value of $[\,0.0\ 0.0\,]$ positions the icon
    at the bottom-left corner; a value of $[\,0.5\ 0.5\,]$ centers it within the rectangle. This entry is only used
    of the icon is scaled proportionally. The default is $[\,0.5\ 0.5\,]$
    the \texttt{annot} rectangle. The key is either \cs{PA} or \texttt{position}.
    The default is \verb!\PA{.5 .5}! (no comma between numbers), in the user friendly style
    \verb!position={.5 .5}! (no comma between numbers).

  \item [\textbf{FB}] (Boolean; optional) If \texttt{true}, indicates that the button appearance should be scaled to fit
  fully within the bounds of the annotation  without taking into consideration the line width of the border.
  The default is \texttt{false}. The key is \cs{FB} or  \texttt{fitbounds}; the default
  is \verb!\FB{false}! or \verb!fitbounds=false!.
  \end{itemize}
  \item [\textbf{TP}] a code indicating position of text relative to icon. The key is either
  \cs{TP} or \texttt{layout}.
  \begin{itemize}
    \item[0] No icon; caption only. KVP: \verb!\TP{0}! or \texttt{layout=labelonly}.
    \item[1] No caption; icon only. KVP: \verb!\TP{1}! or \texttt{layout=icononly}.
    \item[2] Caption below icon. KVP: \verb!\TP{2}! or \texttt{layout=icontop}.
    \item[3] Caption above icon. KVP: \verb!\TP{3}! or \texttt{layout=iconbottom}.
    \item[4] Caption to the right of icon. KVP: \verb!\TP{4}! or \texttt{layout=iconleft}.
    \item[5] Caption to the left of icon. KVP: \verb!\TP{5}! or \texttt{layout=iconright}.
    \item[6] Caption overlaid on the icon. KVP: \verb!\TP{6}! or \texttt{layout=labelover}.
  \end{itemize}
\end{itemize}


\medskip\noindent That's it, now, back to my retirement!



\end{document}