summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/grayhints/doc/grayhints_man.tex
blob: c5ff2503be14c375c40946058bd51a599c2e3bc6 (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
\documentclass{article}
\usepackage[fleqn]{amsmath}
\usepackage[
    web={centertitlepage,designv,forcolorpaper,tight*,latextoc,pro},
    eforms,aebxmp
]{aeb_pro}
\usepackage{grayhints}\previewOff
\usepackage{graphicx,array,fancyvrb}
\usepackage{aeb_mlink}
%\usepackage{myriadpro}
%\usepackage{calibri}
\usepackage[altbullet]{lucidbry}

\def\hardspace{{\fontfamily{cmtt}\selectfont\symbol{32}}}

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

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


%\def\tutpath{doc/tutorial}
%\def\tutpathi{tutorial}
%\def\expath{../examples}

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


\DeclareDocInfo
{
    university={\AcroTeX.Net},
    title={The \textsf{grayhints} Package},
    author={D. P. Story},
    email={dpstory@acrotex.net},
    subject=Documentation for the grayhints,
    talksite={\url{www.acrotex.net}},
    version={v1.0, 2017/03/02},
    Keywords={LaTeX, form field, hints, 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 grayhints Package";
var manualfilename="Manual_BG_Print_grayhints.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

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


\section{Introduction}

We often see in HTML pages or in compiled executable applications, form
fields (text fields, input fields) that require user input. The untouched
field has text within it informing the user of the nature of the data to be
entered into the field. This, usually, grayed hint immediately disappears
when the user focus the cursor on the field. We illustrate the concept with
an example or two.
\begin{quote}
    \textField[\textColor{\matchGray}
       \TU{Enter your first name so I can get to know you better}
       \AA{\AAFormat{\FmtToGray{First Name}}
       \AAKeystroke{\KeyToGray}
       \AAOnFocus{\JS{\FocusToBlack}}
       \AAOnBlur{\JS{\BlurToBlack}}
    }]{NameFirst1}{2in}{11bp}\vcgBdry[\medskipamount]
    \textField[\textColor{\matchGray}
       \TU{Enter your favorite date, in the indicated format}
       \AA{\AAKeystroke{AFDate_KeystrokeEx("yyyy/mm/dd");\r\KeyToGray}
       \AAFormat{AFDate_FormatEx("yyyy/mm/dd");\r\FmtToGray{yyyy/mm/dd}}
       \AAOnFocus{\JS{\FocusToBlack}}
       \AAOnBlur{\JS{\BlurToBlack}}
    }]{DateField1}{1in}{11bp}\cgBdry[1.5em]
    \pushButton[\CA{Reset}
        \TU{Press to clear to clear all fields.}
        \A{\JS{this.resetForm();}}]{reset}{}{11bp}
\end{quote}
    Of course, the usual tooltips may also be provided.\medskip\noindent

    It is not natural for Adobe form fields to do this, it takes some support
    code for it to work properly; scripts for the Keystroke, Format, OnFocus,
    and OnBlur events are needed.

\section{Package options}

Without passing any options, the \pkg{eforms} package of \AEB, dated
2017/02/27, is required and a document JavaScript function
\texttt{AllowCalc()} is automatically embedded in the document; however there
are options to modify this default setup.
\begin{description}
    \item[\texttt{usehyforms}] By default, this package requires
        \pkg{eforms}, dated 2017/02/27; however, if you are more
        comfortable using the form fields of \pkg{hyperref}, specify the
        option \texttt{usehyforms}.\footnote{\pkg{eforms} and
        \pkg{hyperref} form fields can be used in one document.} When
        \texttt{usehyforms} is specified, \pkg{insdljs} dated 2017/03/02 or
        later is required. This requirement is to support the
        \texttt{usealtadobe}, discussed next.
    \item[\texttt{nocalcs}] If this option is taken, the document
        JavaScript function \texttt{AllowCalc()} is not embedded in the document. The
        implications are that you are not using any calculation fields.
    \item[\texttt{usealtadobe}] If you have the \app{Acrobat} application,
        you can edit form fields. When you write custom formatting scripts
        (as does this package) using Adobe's built-in functions, such as
        \texttt{AFNumber\_Keystroke} and \texttt{AFNumber\_Format}, the
        user-interface for editing the custom script is not available. The
        \texttt{usealtadobe} option is passed to \pkg{insldjs};
        \pkg{insdljs}, in turn, inputs alternate names for the common
        \app{Adobe} built-ins. Refer to
        \hyperref[s:altadobfuncs]{Section~\ref*{s:altadobfuncs}} for more
        information.

    \item[\texttt{nodljs}] When this option is specified, there are no
        requirements placed on this package; that is, neither \pkg{eforms}
        nor \pkg{insdljs} are required.
\end{description}

\paragraph*{Demo file:} \texttt{gh-eforms.tex,\;gh-hyperref.tex}. The latter file
uses the \opt{usehyforms} option (and \pkg{hyperref} form fields), while the former uses the \pkg{eforms} package.

\section{Creating a form field with a gray hint}

In this documentation, we use \pkg{eforms} form fields to illustrate concepts, the demonstration file
\texttt{gh-hyperref.tex} has the form field markup for the case of \pkg{hyperref} forms.

There are two cases: (1) an ordinary variable text form field (this includes
text fields and editable combo boxes) with no calculate script; (2) same as
(1), but the field has a calculate script.

\subsection{Variable text field, no calculate script}

When there is no calculate script, to obtain a gray hint, it is necessary to
supply scripts for the Format, Keystroke, OnFocus, and OnBlur events. The
scripts are all defined in the \pkg{grayhints} package. In addition, the
color of the text in the text field must be appropriate. We illustrate,
\begin{Verbatim}[xleftmargin=\parindent,commandchars=!(),numbers=left,numbersep=3bp,fontsize=\small]
\textField[!color(gray)\TU{Enter your first name so I can get to know you better}
    \textColor{\matchGray}\AA{%
    \AAKeystroke{\KeyToGray}
    \AAFormat{\FmtToGray{First Name}}
    \AAOnFocus{\JS{\FocusToBlack}}
    \AAOnBlur{\JS{\BlurToBlack}}
}]{NameFirst}{2in}{11bp}
\end{Verbatim}
By default, the text color is black and the grayed hint text is light gray.
The tool tip (\cs{TU}) is grayed out, as it is optional. In line~(2) we match
the color for the text to the gray color using the command \cs{matchGray} of
\pkg{grayhints}. Within the argument of \cs{AA}, the \cs{AAFormat},
\cs{AAKeystroke}, \cs{AAOnFocus}, and \cs{AAOnBlur} scripts are inserted.
\begin{quote}
\begin{description}
    \item{Keystroke Script:} In line~(3), \cs{KeyToGray} is placed within
        the argument of \cs{AAKeystroke}. This script changes the color
        of the text to gray when the field is empty.
    \item{Format Script:} The script snippet \cs{FmtToGray} takes a
        single argument, which is the text of the hint. In line~(4)
        the hint is `First Name'.
    \item{OnFocus Script:} The code snippet \cs{FocusToBlack} is inserted
        into the argument of \cs{OnFocus}, as seen in line~(5). When the
        field comes into focus, this script changes the color to the
        normal color (usually black).
    \item{OnBlur Script:} In line~(6), the \cs{BlurToBlack} script is
        placed within the argument of \cs{OnBlur}, in the manner
        indicated. When the field loses focus (is blurred), the script
        changes the color of text to gray if the field is empty or to
        its normal color (usually black), otherwise.
\end{description}
\end{quote}
The \pkg{hyperref} form field counterpart to the above example is,
\begin{Verbatim}[xleftmargin=\parindent,commandchars=!(),numbers=left,numbersep=3bp,fontsize=\small]
\TextField[name={NameFirst},
    height=11bp,width=2in,
    color=\matchGray,
    keystroke=\KeyToGray,
    format=\FmtToGray{First Name},
    onfocus=\FocusToBlack,
    onblur=\BlurToBlack]{}
\end{Verbatim}
The two fields appear side-by-side:
\begin{quote}
\textField[\autoCenter{n}\textColor{\matchGray}
    \TU{Enter your first name so I can get to know you better}
    \AA{\AAFormat{\FmtToGray{First Name}}
        \AAKeystroke{\KeyToGray}
        \AAOnFocus{\JS{\FocusToBlack}}
        \AAOnBlur{\JS{\BlurToBlack}}
}]{NameFirst2}{2in}{11bp}\cgBdry[0.5em]
\TextField[name={NameFirst3},
    height=11bp,width=2in,
    color=\matchGray,
    keystroke=\KeyToGray,
    format=\FmtToGray{First Name},
    onfocus=\FocusToBlack,
    onblur=\BlurToBlack]{}\cgBdry[0.5em]
\pushButton[\CA{Reset}\autoCenter{n}
    \TU{Press to clear to clear all fields.}
    \A{\JS{this.resetForm();}}]{reset}{}{11bp}
\end{quote}
Both fields appear in the `default' appearance.


\subsection{Variable text field, with calculate script}

If you want to make calculations based on entries in other fields, you will need
the code snippet \cs{CalcToGray} as part of your calculate script.
\begin{Verbatim}[xleftmargin=\parindent,commandchars={!~@},numbers=left,numbersep=3bp,fontsize=\small]
\textField[!color~gray@\TU{The total for first and second integers}
    \textColor{\matchGray}\AA{%
    \AAKeystroke{AFNumber_Keystroke(0,1,0,0,"",true);\r\KeyToGray}
    \AAFormat{AFNumber_Format(0,1,0,0,"",true);\r\FmtToGray{Total}}
    \AACalculate{var cArray=new Array("Integer");\r
        if(AllowCalc(cArray))AFSimple_Calculate("SUM", cArray );\r
        \CalcToGray}
    \AAOnFocus{\JS{\FocusToBlack}}
    \AAOnBlur{\JS{\BlurToBlack}}}
]{TotalNumbers}{1in}{11bp}
\end{Verbatim}
The use of \cs{r} is optional, the author uses this to format the script
within the user-interface of \app{Acrobat}. The \cs{textColor} (line~(2)),
\cs{AAOnFocus} (line~(8)), and \cs{AAOnBlur} (line~(8)) are the same as earlier presented.
Several comments are needed for the \cs{AAKeystroke}, \cs{AAFormat} and \cs{AACalculate} lines.
\begin{itemize}
    \item This is a number field, so we use the built-in functions
        \texttt{AFNumber\_Keystroke} and \texttt{AFNumber\_Format} provided
        by the \app{Adobe Acrobat} and \app{Adobe Acrobat Reader}
        distributions. In lines~(3) and~(4), the \cs{KeyToGray} and
        \cs{FmtToGray} code snippets follow the built-ins.\footnote{As a general rule,
        the code snippets \cs{KeyToGray}, \cs{FmtToGray}, and
        \cs{CalcToGray} should inserted after any built-in functions.}
    \item For the Calculate event, special techniques are used. We define
        an array \texttt{cArray} (line~(5)) consisting of the names of all
        the dependent fields we use to calculate the value of this field.
        In line~(6), we make the calculation (\texttt{AFSimple\_Calculate})
        only if the document JavaScript function \texttt{AllowCalc(cArray)}
        returns true. The function returns true only if at least one of the
        fields is not empty. Following the calculation comes the code
        snippet \cs{CalcToGray}; this changes the text color to gray if the
        field is empty and to the normal color (usually black) otherwise.

        The function \texttt{AllowCalc()} is defined for all options except
        for the \opt{nodljs} option.
\end{itemize}
Let's go to the examples. Build three fields (four actually), in the first two
enter integers, the other two fields compute their sum.
\begin{quote}\previewOff
\ding{172}\ \textField[\TU{Enter an integer}
    \textColor{\matchGray}\AA{%
    \AAKeystroke{AFNumber_Keystroke(0,1,0,0,"",true);\r\KeyToGray}
    \AAFormat{AFNumber_Format(0,1,0,0,"",true);\r\FmtToGray{First Integer}}
    \AAOnFocus{\JS{\FocusToBlack}}
    \AAOnBlur{\JS{\BlurToBlack}}}
]{Integer.First}{1in}{11bp}\vcgBdry[3bp]
\ding{173}\ \textField[\TU{Enter an integer}
    \textColor{\matchGray}\AA{%
    \AAKeystroke{AFNumber_Keystroke(0,1,0,0,"",true);\r\KeyToGray}
    \AAFormat{AFNumber_Format(0,1,0,0,"",true);\r\FmtToGray{Second Integer}}
    \AAOnFocus{\JS{\FocusToBlack}}
    \AAOnBlur{\JS{\BlurToBlack}}}
]{Integer.Second}{1in}{11bp}\vcgBdry[3bp]
\ding{174}\ \textField[\TU{The total for first and second integers}
    \textColor{\matchGray}\AA{%
    \AAKeystroke{AFNumber_Keystroke(0,1,0,0,"",true);\KeyToGray}
    \AAFormat{AFNumber_Format(0,1,0,0,"",true);\r\FmtToGray{Total}}
    \AACalculate{var cArray=new Array("Integer");\r
        if (AllowCalc(cArray)) AFSimple_Calculate("SUM", cArray );\r\CalcToGray}
    \AAOnFocus{\JS{\FocusToBlack}}
    \AAOnBlur{\JS{\BlurToBlack}}}
]{TotalNumbers}{1in}{11bp}\vcgBdry[3bp]
\ding{175}\ \textField[\TU{The total for first and second integers}
    \textColor{\matchGray}\AA{%
    \AAKeystroke{AFNumber_Keystroke(0,1,0,0,"",true);\r\KeyToGray}
    \AAFormat{AFNumber_Format(0,1,0,0,"",true);\r\FmtToGray{Total}}
    \AACalculate{var cArray=new Array("Integer");\r
        AFSimple_Calculate("SUM", cArray );\r\CalcToGray}
    \AAOnFocus{\JS{\FocusToBlack}}
    \AAOnBlur{\JS{\BlurToBlack}}}
]{TotalNumbers1}{1in}{11bp}\cgBdry[1em]
\pushButton[\CA{Reset}
    \TU{Press to clear to clear all fields.}
    \A{\JS{this.resetForm();}}]{reset}{}{11bp}
\end{quote}
Enter numbers into the first two text fields (\ding{172} and \ding{173}), the
totals of these two fields appear in the last two fields (\ding{174} and
\ding{175}). Total field \ding{174} uses the recommended script
\texttt{if(AllowCalc(cArray)} (see line~(6) above), whereas field \ding{175}
does not. Initially, they both behave the same way until you press the reset
button. For field \ding{174} the gray hint appears, for field \ding{175} the
number zero (0) appears. This is because the calculation was allowed to go
forward, and the calculated value is zero even through none of the dependent
fields have a value. If you want the gray hint in the total field, you must
use the conditional \texttt{if(AllowCalc(cArray)}.\footnote{Hence, don't use the \opt{nodljs} option.}

\subsection{Changing the colors for gray hints}

For the fields in which the gray hint scripts are used, there are two colors
that are relevant, the normal color (defaults to black) and the gray color
(defaults to light gray). The command
\cs{normalGrayColors\darg{\ameta{normalcolor}}\darg{\ameta{graycolor}}} sets
this pair of colors. The arguments for \cs{normalGrayColors} are JavaScript
colors; they may be in any of the following four forms: (1) a JavaScript
color array \texttt{["RGB",1,0,0]}; (2) a predefined JavaScript color, such
as \texttt{color.red}; (3) a declared (or named) {\LaTeX} color such as
\texttt{red}; or (4) a non-declared {\LaTeX} color such as
\texttt{[rgb]\darg{1,0,0}}. If the package \pkg{xcolor} is not loaded, only
methods (1) and (2) are supported.

The package default is
\cs{normalGrayColors\darg{color.black}\darg{color.ltGray}}. The predefined
JavaScript colors are,
\begin{quote}
%    \setlength\tabcolsep{3pt}
    \setlength{\extrarowheight}{1pt}
    \begin{tabular}{>{\ttfamily}l>{\ttfamily}l>{\ttfamily}l}
    \multicolumn{3}{>{\sffamily}c}{Color Models}\\\hline
    \multicolumn{1}{>{\sffamily}c}{GRAY}&
    \multicolumn{1}{>{\sffamily}c}{RGB}&
    \multicolumn{1}{>{\sffamily}c}{CMYK}\\
    color.black&color.red&color.cyan\\
    color.white&color.green&color.magenta\\
    color.dkGray&color.blue\\
    color.gray\\
    color.ltGray
    \end{tabular}
\end{quote}
All these colors are defined in the {\LaTeX} color packages, except for possibly \texttt{dkGray},
\texttt{gray}, and \texttt{ltGray}. These three are defined in \pkg{grayhints}.

We repeat the `First Name' example with different declared colors. We begin by declaring,
\begin{Verbatim}[xleftmargin=\parindent,fontsize=\small]
\normalGrayColors{blue}{magenta}
\end{Verbatim}
then build a `gray hinted' field,
\begin{quote}\previewOff\normalGrayColors{blue}{magenta}%
    \textField[\textColor{\matchGray}
       \TU{Enter your first name so I can get to know you better}
       \AA{\AAFormat{\FmtToGray{First Name}}
       \AAKeystroke{\KeyToGray}
       \AAOnFocus{\JS{\FocusToBlack}}
       \AAOnBlur{\JS{\BlurToBlack}}
    }]{NameFirst4}{2in}{11bp}\cgBdry[1em]
\pushButton[\CA{Reset}
    \TU{Press to clear to clear all fields.}
    \A{\JS{this.resetForm();}}]{reset}{}{11bp}
\end{quote}

\subsection{Remarks on the
    \texorpdfstring{\protect\opt{usealtadobe}}{usealtadobe} option}\label{s:altadobfuncs}

The \opt{usealtadobe} option is useful for developers who have the
\app{Adobe} application and who wish to develop and test scripts that extend
in the current work. The \opt{usealtadobe} option inputs from \pkg{insdljs} the following
alternate names. As a general rule, all Adobe built-in format, validate, and calculation functions
that begin with `AF' are given alternate names that begin with `EF'. More specifically, the table
below lists the effected functions.
\begin{quote}
\begin{tabular}{>{\ttfamily}l>{\ttfamily}l}
\multicolumn{1}{>{\sffamily\bfseries}l}{Adobe function name}&%
\multicolumn{1}{>{\sffamily\bfseries}l}{Alternate function name}\\
AFNumber\_Keystroke&EFNumber\_Keystroke\\
AFNumber\_Format&EFNumber\_Format\\
AFPercent\_Keystroke&EFPercent\_Keystroke\\
AFPercent\_Format&EFPercent\_Format\\
AFDate\_Format&EFDate\_Format\\
AFDate\_Keystroke&EFDate\_Keystroke\\
AFDate\_FormatEx&EFDate\_FormatEx\\
AFTime\_Keystroke&EFTime\_Keystroke\\
AFTime\_Format&EFTime\_Format\\
AFTime\_FormatEx&EFTime\_FormatEx\\
AFDate\_KeystrokeEx&EFDate\_KeystrokeEx\\
AFSpecial\_Keystroke&EFSpecial\_Keystroke\\
AFSpecial\_Format&EFSpecial\_Format\\
AFSpecial\_KeystrokeEx&EFSpecial\_KeystrokeEx\\
AFRange\_Validate&EFRange\_Validate\\
AFRange\_Validate&EFRange\_Validate\\
AFSimple\_Calculate&EFSimple\_Calculate\\
AFMergeChange&EFMergeChange
\end{tabular}
\end{quote}

\begin{figure}[htb]
\begin{minipage}[t]{.5\linewidth-2.5pt}\kern0pt\centering
%\setlength{\fboxsep}{0pt}%
{\setlength{\fboxsep}{0pt}{\includegraphics[width=\linewidth]{graphics/numFmt-noshowcustom}}}%
\end{minipage}\hfill
\begin{minipage}[t]{.5\linewidth-2.5pt}\kern0pt\centering
{\setlength{\fboxsep}{0pt}{\includegraphics[width=\linewidth]{graphics/numFmt-showcustom}}}%
\end{minipage}\\[3pt]
\makebox[.5\linewidth-2.5pt][c]{(a)\ Using \texttt{AFNumber\_Format}}\hfill
\makebox[.5\linewidth-2.5pt][c]{(b)\ Using \texttt{EFNumber\_Format}}%
\caption{Format tab: `AF' versus `EF' functions}\label{fig:AltAdbFncs}
\end{figure}

\hyperref[fig:AltAdbFncs]{Figure~\ref*{fig:AltAdbFncs}} shows the impact of using the `EF' functions. On the left,
\texttt{AFNumber\_Format} is used to format a number field that uses gray hints using the code
\begin{Verbatim}[xleftmargin=\parindent]
AFNumber_Format(0,1,0,0,"",true)\r\FmtToGray
\end{Verbatim}
As can be seen in sub-figure\,(a), or more accurately not seen, the code is
not seen through the user-interface of \app{Acrobat}. In sub-figure\,(b) the
underlying code is seen (and therefore editable through the user-interface)
because the `EF' version of the function was used:
\begin{Verbatim}[xleftmargin=\parindent]
\try{EFNumber_Format(0,1,0,0,"",true)}catch(e){}\r\FmtToGray
\end{Verbatim}
Note this code is wrapped in a \texttt{try/catch} construct; this is
optional. The \pkg{insdljs} package defines a helper command \cs{dlTC} to do the wrapping for you:
\begin{Verbatim}[xleftmargin=\parindent]
\dlTC{EFNumber_Format(0,1,0,0,"",true)}\r\FmtToGray
\end{Verbatim}
When using \app{pdflatex} or \app{xelatex}, \texttt{try/catch} appears not to
be needed, but when \app{Adobe Distiller} is used, \app{Acrobat} throws an
exception when the file is first created. The \texttt{try/\penalty0catch} suppresses
(catches) the exception.


\section{My retirement}

Now, I simply must get back to it. \dps

\end{document}