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