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