summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/grayhints/doc/grayhints_man.tex
blob: bb180c0dae16d3c2cd9a52dc820904282c5fca36 (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
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
\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{xbmks}
\DeclareInitView{layoutmag={navitab:UseOutlines}}
\xbmksetup{colors={int=red},styles={intbf}}

\advance\marginparwidth 8pt


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

\def\hardspace{{\fontfamily{cmtt}\selectfont\symbol{32}}}
\let\uif\textsf

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

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

%\AACalculate{\CalcToGray}

%\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={1.2, 2018/26/04},
    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

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

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 ``grayed hint'' immediately disappears
when the user focuses the cursor on the field.\footnote{Focus on the field by
clicking inside the form 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{\DateKeyEx("yyyy/mm/dd");\r\KeyToGray}
       \AAFormat{\DateFmtEx("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 tool tips 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,
    OnBlur, and Calculate events are needed.

The \pkg{grayhints} package works as designed for \app{Adobe Reader} and
\app{PDF-XChange Editor}.\footnote{\app{PDF-XChange Viewer}, which is no longer
supported by \href{https://www.tracker-software.com/}{Tracker Software
Products}, will display the gray hints, but some of the needed JavaScript are not supported.} All {\LaTeX}
workflows for PDF creation are also supported.

\section{Package options}

Without passing any options, the \pkg{eforms} package of \AEB, dated
2017/02/27, is required; the document JavaScript function
\texttt{AllowCalc()} and modified Adobe built-in functions are automatically
embedded in the document. There are options, however, 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. Use this option is you are not
        using any of the Adobe built-in formatting functions.
\end{description}

\paragraph*{Demo files:} \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. The demo files
\texttt{gh-fmt-eforms.tex,\;gh-fmt-hyperref.tex} provided additional examples
of the use of Adobe's built-in formatting functions.

\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} and
\texttt{gh-fmt-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}}
    \AACalculate{\CalcToGray} %!normalfont( required if !app(PDF-XChange Editor) is used)
}]{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 (blurred), the script
        changes the color of text to gray if the field is empty or to
        its normal color (usually black), otherwise.
    \item{Calculate Script:} In line~(7), the Calculate event resets the
        color to gray. This is needed when the user presses the
        \uif{Enter} key rather than exiting the field by tabbing out, or
        clicking or tapping an area outside the field. This script is required
        when (1) there is a possibility that \app{PDF-XChange Editor} is used; or
        (2) a ``totals'' calculation field.
\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,charsize=9bp,
    color={\matchGray},
    keystroke={\KeyToGray},
    format={\FmtToGray{First Name}},
    onfocus={\FocusToBlack},
    onblur={\BlurToBlack},
    calculate={\CalcToGray}  %!normalfont( required if !app(PDF-XChange Editor) is used)
]{}
\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,,charsize=9bp,
    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 their `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
        !textbf~\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} (or \app{PDF-XChange
Editor}).\footnote{The helper commands \cs{r} and \cs{t} are defined in
\pkg{eforms}; if \pkg{eforms} is not loaded, use \cs{jsR} and \cs{jsT}
instead.} The \cs{textColor} (line~(2)), \cs{AAOnFocus} (line~(8)), and
\cs{AAOnBlur} (line~(9)) are the same as earlier presented. Several comments
are needed for the \cs{AAKeystroke}, \cs{AAFormat} and \cs{AACalculate}
lines. The \cs{AACalculate} event above also shows, in general, how to integrate
the gray hint methodology with other scripts; as a general rule, the gray hints commands
should come last.
\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 using Adobe built-in formatting functions}\label{s:altadobfuncs}

The \pkg{grayhints} package (as well as does \pkg{insdljs}) offers
alternating naming of the \app{Adobe} built-in formatting functions. 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, \hyperref[table:builtin]{Table~\ref*{table:builtin}} lists the
Adobe built-in formatting functions and their alternative names. The purpose
of these alternate names is to allow the JavaScript developer to access the
scripts through the \app{Acrobat} user-interface.
\begin{table}[htb]\centering
\begin{tabular}{>{\ttfamily}l>{\ttfamily}ll}
\multicolumn{1}{>{\sffamily\bfseries}l}{Adobe function name}&%
\multicolumn{1}{>{\sffamily\bfseries}l}{Alternate function name}&%
\multicolumn{1}{>{\sffamily\bfseries}l}{\LaTeX{} command\protect\footnotemark}\\
AFNumber\_Keystroke&EFNumber\_Keystroke&\cs{NumKey}\\
AFNumber\_Format&EFNumber\_Format&\cs{NumFmt}\\
AFPercent\_Keystroke&EFPercent\_Keystroke&\cs{PercentKey}\\
AFPercent\_Format&EFPercent\_Format&\cs{PercentFmt}\\
AFDate\_Keystroke&EFDate\_Keystroke&\cs{DateKey}\\
AFDate\_Format&EFDate\_Format&\cs{DateFmt}\\
AFDate\_KeystrokeEx&EFDate\_KeystrokeEx&\cs{DateKeyEx}\\
AFDate\_FormatEx&EFDate\_FormatEx&\cs{DateFmtEx}\\
AFTime\_Keystroke&EFTime\_Keystroke&\cs{TimeKey}\\
AFTime\_Format&EFTime\_Format&\cs{TimeFmt}\\
AFTime\_FormatEx&EFTime\_FormatEx&\cs{TimeFmtEx}\\
AFSpecial\_Keystroke&EFSpecial\_Keystroke&\cs{SpecialKey}\\
AFSpecial\_Format&EFSpecial\_Format&\cs{SpecialFmt}\\
AFSpecial\_KeystrokeEx&EFSpecial\_KeystrokeEx&\cs{SpecialKeyEx}\\
AFRange\_Validate&EFRange\_Validate&\cs{RangeValidate}\\
AFSimple\_Calculate&EFSimple\_Calculate&\cs{SimpleCalc}\\
AFMergeChange&EFMergeChange&\cs{MergeChange}
\end{tabular}
\caption{Built-in formatting commands}\label{table:builtin}
\end{table}

You can learn more about the `AF' versions and their arguments at the
\href{http://blog.acrotex.net}{Acro\negthinspace\TeX\space Blog} web site; in
particular, carefully read the article
\mlurl{http://www.acrotex.net/blog/?p=218}.

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

\leavevmode\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.

\footnotetext{These commands are explained in \hyperref[extendGH]{Section~\ref*{extendGH}}}


\section{Extending the functionality of \texorpdfstring{\protect\pkg{grayhints}}{grayhints}}\label{extendGH}

The `gray hints' technique works well with fields that require special
formatting such as the ones provided by built-in formats of \app{Adobe
Acrobat}, these formats are Number, Percentage, Date, Time, Special, and
Custom. How `gray hints' functions when one of these special formats is used
may be acceptable, but if not, we offer an alternative. We begin by
presenting two date text fields. The one on the left is the default, the one
on the right is `enhanced.'\footnote{The example that follows is taken from
\texttt{gh-fmts-forms.tex} where you will find additional
discussion.}\medbreak

\noindent\hskip-62.5pt\begingroup\advance\linewidth62.5pt
\begin{minipage}[t]{.5\linewidth-15pt}
\textField[\textColor{\matchGray}
    \TU{Enter a date of your choosing}
    \AA{%
      \AAOnFocus{\JS{\FocusToBlack}}
% Using the Adobe Built-in functions directly
      \AAKeystroke{AFDate_KeystrokeEx("yyyy/mm/dd");\r
        \KeyToGray}
      \AAFormat{AFDate_FormatEx("yyyy/mm/dd");\r
        \FmtToGray{yyyy/mm/dd}}
      \AAOnBlur{\JS{\BlurToBlack}}
    \AACalculate{\CalcToGray}
}]{Datefield1}{1in}{11bp}\par\smallskip\noindent
\begin{Verbatim}[xleftmargin=15pt,fontsize=\footnotesize,commandchars={!~@},numbers=left,numbersep=8pt]
\textField[\textColor{\matchGray}
  \TU{Enter a date of your choosing}\AA{%
  \AAOnFocus{\JS{\FocusToBlack}}
% !normalfont~Using the Adobe Built-in functions directly@
  \AAKeystroke{%
    AFDate_KeystrokeEx("yyyy/mm/dd");\r
    \KeyToGray}
  \AAFormat{AFDate_FormatEx("yyyy/mm/dd");\r
    \FmtToGray{yyyy/mm/dd}}
  \AAOnBlur{\JS{\BlurToBlack}}
  \AACalculate{\CalcToGray}
}]{Datefield1}{1in}{11bp}
\end{Verbatim}
\footnotesize\makebox[\linewidth][c]{Figure (a): Using Adobe built-in functions}
\end{minipage}\hfill
\begin{minipage}[t]{.5\linewidth-15pt}
\textField[\textColor{\matchGray}
    \TU{Enter a date of your choosing}\AA{%
    \AAOnFocus{\JS{\FocusToBlack}}
% using a customized version of Adobe built-in functions, with LaTeX access
    \AAKeystroke{\DateKeyEx("yyyy/mm/dd");\r
      \KeyToGray}
    \AAFormat{\DateFmtEx("yyyy/mm/dd");\r
      \FmtToGray{yyyy/mm/dd}}
    \AAOnBlur{\JS{\BlurToBlack}}
    \AACalculate{\CalcToGray}
}]{Datefield2}{1in}{11bp}\par\smallskip\noindent
\begin{Verbatim}[xleftmargin=15pt,fontsize=\footnotesize,commandchars={!~@},numbers=left,numbersep=8pt]
\textField[\textColor{\matchGray}
  \TU{Enter a date of your choosing}\AA{%
  \AAOnFocus{\JS{\FocusToBlack}}
% !normalfont~Using a customized version of Adobe built-in@
% !normalfont~functions, with !LaTeX access@
  \AAKeystroke{!textbf~\DateKeyEx@("yyyy/mm/dd");\r
    \KeyToGray}
  \AAFormat{!textbf~\DateFmtEx@("yyyy/mm/dd");\r
    \FmtToGray{yyyy/mm/dd}}
  \AAOnBlur{\JS{\BlurToBlack}}
  \AACalculate{\CalcToGray}
}]{Datefield2}{1in}{11bp}
\end{Verbatim}
\setlength{\fboxsep}{0pt}%
\footnotesize\makebox[\linewidth][c]{Figure~(b): Using \LaTeX{} format commands}
\end{minipage}
\endgroup\par\medskip\noindent
Try entering a bogus date, such as the number `17'. The two fields operate
identically when you then commit your date by clicking your mouse outside the
fields. However, the behavior of these two fields differ when you commit your
bogus date by pressing the \uif{Enter} key. For Figure~(a), the template
`yyyy/dd/mm' appears in black, whereas, for Figure~(b), the phrase `continue
editing' appears in black. The latter is the `enhanced' behavior of the
fields that use the gray hints code.

\paragraph*{Remarks on the {\LaTeX} format commands.} The difference in the two code snippets
(Figures~(a) and~(b)) is seen in lines~(6) and~(8) of Figure~(b). In these
two lines we use the special \cs{DateKeyEx} and \cs{DateFmtEx} commands that
ultimately call the \app{Adobe} built-in functions, but when these special
commands are used, we can better manage what happens when the \uif{Enter} key
is pressed. The document author is strongly encouraged to use the {\LaTeX}
commands in the last column on the right of
\hyperref[table:builtin]{Table~\ref*{table:builtin}}, instead of using the
Adobe built-ins, as is done in Figure~(a), or their `EF'
counterparts.\footnote{Some of these {\LaTeX} commands use the `AF' built-in
(mostly for the formate events) while others use the `EF' versions of the
built-ins.}

The \pkg{grayhints} now defines \cs{EnterCommitFailEvent} and
\cs{CommitSuccessEvent} to customize the user experience when \uif{Enter} key
is pressed (as opposed to leaving the field by clicking in white space, or
tabbing away from the field). See the sample files \texttt{gh-fmts-eforms}\marginpar{\small\slshape\raggedleft \texttt{gh-fmts-eforms} referenced}
for instructions to use these two commands. We present a final example, where the `Enter' events have been changed.\medskip

\EnterCommitFailEvent{\t
  event.target.strokeColor=color.red;\r\t\t
  event.target.textColor=color.red;\r\t\t
  event.value=("weiter bearbeiten");
%  event.value=(event.target.savevalue);
}
\CommitSuccessEvent{\t\t
  event.target.strokeColor=color.black;
}

%event.value=("weiter bearbeiten");

\noindent
\textField[\textColor{\matchGray}
    \TU{Enter a date of your choosing}\AA{%
    \AAOnFocus{\JS{\FocusToBlack}}
% using a customized version of Adobe built-in functions, with LaTeX access
    \AAKeystroke{\DateKeyEx("yyyy/mm/dd");\r
      \KeyToGray}
    \AAFormat{\DateFmtEx("yyyy/mm/dd");\r
      \FmtToGray{yyyy/mm/dd}}
    \AAOnBlur{\JS{\BlurToBlack}}
    \AACalculate{\CalcToGray}
}]{Datefield3}{1in}{11bp}\qquad(enter `17' then press enter)\medskip

\EnterCommitFailEvent{}\CommitSuccessEvent{}

\noindent This example appears in the \texttt{gh-fmts-eforms.tex} sample file.


\section{My retirement}

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

\end{document}

\begin{minipage}{\linewidth-2in-6bp-1em-6pt}\footnotesize
\textbf{Remark.} The underlying JS function tries hard to make a date from
the input. You can enter a date in most any format as long it is in the order
of the date elements YEAR MONTH DAY (yyyy/mm/dd), as determined by the
formatting template. (For example, try 2018 Jan 10).
\end{minipage}\medskip