\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, 2020/06/05}, 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 <> endobj ... 117 0 obj !textbf@<>^ 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}