summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/grayhints/grayhints.dtx
blob: 9756703cf754a7b474d158329b868c349e26c6e9 (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
%\iffalse
% makeindex -s gglo.ist -o grayhints.gls grayhints.glo
% makeindex -s gind.ist -o grayhints.ind grayhints.idx
%<*copyright>
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% grayhints.sty package,                              %%
%% Copyright (C) 2016        D. P. Story                 %%
%%   dpstory@uakron.edu                                  %%
%%                                                       %%
%% This program can redistributed and/or modified under  %%
%% the terms of the LaTeX Project Public License         %%
%% Distributed from CTAN archives in directory           %%
%% macros/latex/base/lppl.txt; either version 1.2 of the %%
%% License, or (at your option) any later version.       %%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%</copyright>
%<package>\NeedsTeXFormat{LaTeX2e}[1997/12/01]
%<package>\ProvidesPackage{grayhints}
%<package> [2017/03/02 v1.0 grayhints: Create gray hints in text fields]
%<*driver>
\documentclass{ltxdoc}
\usepackage{xcolor}
\usepackage[colorlinks,hyperindex=false]{hyperref}
\usepackage{grayhints}
%\pdfstringdefDisableCommands{\let\\\textbackslash}
\EnableCrossrefs
\CodelineIndex
\RecordChanges
\gdef\brpr#1{\texttt{\char123\relax#1\char125\relax}}
\let\darg\brpr
\let\env\texttt
\let\opt\texttt
\let\app\textsf
\let\pkg\textsf
\def\visispace{\symbol{32}}
\def\ameta#1{\ensuremath{\langle\textit{\texttt{#1}}\rangle}}
\def\meta#1{\textsl{\texttt{#1}}}
\def\SUB#1{\ensuremath{{}_{\mbox{\scriptsize\ttfamily#1}}}}
%\def\cs#1{\texttt{\bslash#1}}
\DeclareRobustCommand{\tmspace}[3]{%
  \ifmmode\mskip#1#2\else\kern#1#3\fi\relax}
\renewcommand{\,}{\tmspace+\thinmuskip{.1667em}}
\let\thinspace\,
\renewcommand{\!}{\tmspace-\thinmuskip{.1667em}}
\let\negthinspace\!
\renewcommand{\:}{\tmspace+\medmuskip{.2222em}}
\let\medspace\:
\newcommand{\negmedspace}{\tmspace-\medmuskip{.2222em}}
\renewcommand{\;}{\tmspace+\thickmuskip{.2777em}}
\let\thickspace\;
\newcommand{\negthickspace}{\tmspace-\thickmuskip{.2777em}}
\makeatletter
\renewcommand{\paragraph}
    {\@startsection{paragraph}{4}{0pt}{6pt}{-3pt}
    {\normalfont\normalsize\bfseries}}
\renewenvironment{quote}[1][]
   {\def\@rgi{#1}\ifx\@rgi\@empty
    \let\rghtm\@empty\else\def\rghtm{\rightmargin\leftmargin}\fi
    \list{}{\rghtm} %{\rightmargin\leftmargin}%
    \item\relax}
   {\endlist}
\makeatother
\InputIfFileExists{aebdocfmt.def}{\PackageInfo{grayhints}{Inputting aebdocfmt.def}}
    {\def\IndexOpt{\DescribeMacro}\def\IndexKey{\DescribeMacro}\let\setupFullwidth\relax
     \PackageInfo{grayhints}{aebdocfmt.def cannot be found}}
\begin{document}
\def\CMD#1{\textbackslash#1}
  \GetFileInfo{grayhints.sty}
  \title{\textsf{grayhints}: Create gray hints in text fields}
  \author{D. P. Story\\
    Email: \texttt{dpstory@acrotex.net}}
  \date{processed \today}
  \maketitle
  \tableofcontents
  \let\Email\texttt
  \DocInput{grayhints.dtx}
\IfFileExists{\jobname.ind}{\newpage\setupFullwidth\par\PrintIndex}{\paragraph*{Index} The index goes here.\\Execute
    \texttt{makeindex -s gind.ist -o grayhints.ind grayhints.idx}\\on the command line and recompile
    \texttt{grayhints.dtx}.}
\IfFileExists{\jobname.gls}{\PrintChanges}{\paragraph*{Change History} The list of changes goes here.\\Execute
    \texttt{makeindex -s gglo.ist -o grayhints.gls grayhints.glo}\\on the command line and recompile
    \texttt{grayhints.dtx}.}
\end{document}
%</driver>
% \fi
% \MakeShortVerb{|}
%
% \InputIfFileExists{aebdonotindex.def}{\PackageInfo{web}{Inputting aebdonotindex.def}}
%    {\PackageInfo{web}{cannot find aebdonotindex.def}}
%
%    \begin{macrocode}
%<*package>
%    \end{macrocode}
%    \section{Description}\previewOff
%    We often see in HTML pages or 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. Lest I be accused of being too obtuse, we
%    illustrate 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}}
%    }]{NameFirst}{2in}{11bp}\vcgBdry[\medskipamount]
%    \textField[\textColor{\matchGray}
%       \TU{Enter your favorite date, in the indicated format}
%       \AA{\AAKeystroke{AFDate_KeystrokeEx("yyyy/mm/dd");\KeyToGray}
%       \AAFormat{AFDate_FormatEx("yyyy/mm/dd");\FmtToGray{yyyy/mm/dd}}
%       \AAOnFocus{\JS{\FocusToBlack}}
%       \AAOnBlur{\JS{\BlurToBlack}}
%    }]{DateField}{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 a lot of support code for
%    it to work properly; the Keystroke, Format, OnFocus, and OnBlur events are needed. The
%    verbatim listing of the first example field above is,
%
%\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}}|\\
%|}]{NameFirst}{2in}{11bp}|
%\end{quote}
%    Code snippets are inserted into the Keystroke, Format,
%    OnFocus, and OnBlur events.
%
%    \paragraph*{Demo files:} \texttt{gh-eforms.tex}, \texttt{hg-hyperref.tex}.
%
%    \section{Documentation and Code}
%    The \pkg{eforms} package is preferred, but you can use the form field macros of \pkg{hyperref}.
%    Any options specified for the \pkg{grayhints} package
%    are passed on to \pkg{insdljs}. One useful option is \opt{usealtadobe}\IndexOpt{usealtadobe}, used for creating
%    custom formatting routines that also use Adobe's built-in formatting functions. The \opt{usealtadobe}
%    option is only useful if the document author has the Adobe application to edit form fields. If the document
%    author does not want to use \pkg{eforms}, he/she can pass the option \opt{usehyforms}\IndexOpt{usehyforms} to use the form
%    fields of \pkg{hyperref}, in this case \pkg{insdljs} is required. For the last option, \opt{nodljs}\IndexOpt{nodljs}
%    is for users of \pkg{hyperref} forms who do not want to use \pkg{insdljs}. In the latter case,
%    the option \opt{usehyforms} should not be used for that will include \pkg{insdljs}.
%    \begin{macrocode}
\DeclareOption{usehyforms}{%
    \def\FormsRequirement{\RequirePackage{insdljs}[2017/03/02]}}
\def\FormsRequirement{\RequirePackage{eforms}[2017/02/27]}
\DeclareOption{nocalcs}{\let\nodljsend\endinput}
\DeclareOption{nodljs}{\let\FormsRequirement\relax
    \let\nodljsend\endinput}
\let\nodljsend\relax
\DeclareOption*{\PassOptionsToPackage{\CurrentOption}{insdljs}}
\ProcessOptions
\FormsRequirement
%    \end{macrocode}
%    We include \texttt{eqcolor.def}, a component of \pkg{exerquiz} to help parse colors,
%    and to match JS colors with PDF colors.
%    \begin{macrocode}
\@ifundefined{jsColor}{\let\eq@YES=y\let\eq@NO=n%
    \InputIfFileExists{eqcolor.def}
    {\PackageInfo{grayhints}{Inputting eqcolor.def from exerquiz}}
    {\PackageError{grayhints}{cannot find eqcolor.def belonging
    to exerquiz}{Refresh your file name database and try again.}}
}{}
%    \end{macrocode}
%
%    \subsection{JavaScript snippets for Field JavaScript}
%    Code snippets are inserted in to the Format, Calculate,
%    OnFocus, and OnBlur events, as illustrated above.
%
%    \begin{macro}{\normalGrayColors}\hspace{-\marginparsep}\thinspace
%    \darg{\ameta{normalcolor}}\darg{\ameta{graycolor}} There are two colors
%    in play, the normal color of the text field (\ameta{normalcolor}) and
%    the color of the ``grayed'' text (\ameta{graycolor}). We set the defaults
%    to \texttt{color.black} and \texttt{color.ltGray}, respectively. The two parameters
%    are JavaScipt colors: array type \texttt{["RGB", 1, 0, 0]}, or predefined type
%    \texttt{color.blue}. The command \cs{jsColor} is used to assign colors (taken from
%    \texttt{eqcolor.def} of \pkg{exerquiz}).
%    \begin{macrocode}
\newcommand{\normalGrayColors}[2]{\def\gh@rgi{#1}\def\gh@rgii{#2}%
    \ifx\gh@rgi\@empty\else
        \jsColor\gh@normalcolor{#1}\gh@chkTr@nsparency\fi
    \ifx\gh@rgii\@empty\else\jsColor\gh@graycolor{#2}\m@tchGray\fi}
\def\gh@normalcolor{}\def\gh@graycolor{}
\AtEndOfPackage{\normalGrayColors{color.black}{color.ltGray}}
%    \end{macrocode}
%    \end{macro}
%    There are several predefined JavaScript colors the user can specify. We need to
%    convert them to PDF color too.
%    \begin{macrocode}
\definecolor{ltGray}{gray}{0.75}
\definecolor{gray}{gray}{.5}
\definecolor{dkGray}{gray}{.25}
\def\gh@pd@transparent{ltGray}\def\gh@transparent{transparent}
\def\gh@pd@black{black}\def\gh@pd@white{white}
\def\gh@pd@dkGray{dkGray}\def\gh@pd@gray{gray}\def\gh@pd@ltGray{ltGray}
\def\gh@pd@red{red}\def\gh@pd@green{green}\def\gh@pd@blue{blue}
\def\gh@pd@cyan{cyan}\def\gh@pd@magenta{magenta}
\def\gh@pd@yellow{yellow}
%    \end{macrocode}
% Convert the JS color for \cs{gh@graycolor} to a matching PDF color that can be
% used by the \cs{textColor} property of a form field. Here, we use commands defined
% in the \texttt{eqcolor.def} file from \pkg{exerquiz}. This command defines the user
% command \DescribeMacro{\matchGray}\cs{matchGray}.
%    \begin{macrocode}
\def\m@tchGray{\eq@checkRawJSColor{\gh@graycolor}%
    \ifx\eqpredefineJSCol\eq@NO
%    \end{macrocode}
%     \cs{gh@graycolor} is a JavaScript array
%    \begin{macrocode}
        \let\matchGray\@empty
        \expandafter\gh@extr@ctJSModelInfo\gh@graycolor\@nil
        \ifx\@rgi\@empty\else\edef\matchGray{\@rgi}\fi
        \ifx\@rgii\@empty\else\edef\matchGray{\matchGray\space\@rgii}\fi
        \ifx\@rgiii\@empty\else
            \edef\matchGray{\matchGray\space\@rgiii}\fi
        \ifx\@rgiv\@empty\else\edef\matchGray{\matchGray\space\@rgiv}\fi
    \else
%    \end{macrocode}
%     \cs{gh@graycolor} is a predefined color (\texttt{color.ltGray})
%    \begin{macrocode}
        \expandafter\gh@getColorFromPrefined\gh@graycolor\@nil
        \@ifundefined{gh@pd@\pd@color}{%
            \def\gh@graycolor{color.ltGray}\def\pd@color{ltGray}%
            \PackageWarning{grayhints}
                {The color.\pd@color\space is undefined,\MessageBreak
                substituting color.ltGray}}{\ifx\pd@color\gh@transparent
            \def\gh@graycolor{color.ltGray}\def\pd@color{ltGray}%
            \PackageWarning{grayhints}
                {A transparent color is not supported,\MessageBreak
                using color.ltGray instead}\fi
        }%
        \edef\matchGray{\@nameuse{gh@pd@\pd@color}}%
    \fi}
\def\gh@chkTr@nsparency{\eq@checkRawJSColor{\gh@normalcolor}%
    \ifx\eqpredefineJSCol\eq@YES
        \expandafter\gh@getColorFromPrefined\gh@normalcolor\@nil
        \@ifundefined{gh@pd@\pd@color}{\def\gh@normalcolor{color.black}%
            \PackageWarning{grayhints}
            {The color.\pd@color\space is undefined,\MessageBreak
            substituting color.black}}{}%
        \ifx\pd@color\gh@transparent\def\gh@normalcolor{color.black}%
        \PackageWarning{grayhints}
            {A transparent color is not supported,\MessageBreak
            using color.black instead}\fi
    \fi
}
%    \end{macrocode}
%    Various supporting macros to extract information.
%    \begin{macrocode}
\def\gh@extr@ctJSModelInfo[#1,#2]\@nil{%
    \gh@getspecv@lues#2,,,,\@nil}%
\def\gh@getspecv@lues#1,#2,#3,#4,#5\@nil{%
    \def\@rgi{#1}\def\@rgii{#2}\def\@rgiii{#3}\def\@rgiv{#4}}
\def\gh@getColorFromPrefined color.#1\@nil{\def\pd@color{#1}}
%    \end{macrocode}
%    \begin{macro}{\FmtToGray}\hspace{-\marginparsep}\thinspace
%    \darg{\ameta{grayhint}} This command is placed in the Format event. It places the hint
%    \ameta{grayhint} as the formatting text string when the field is empty.
%    If a built-in Adobe function is also used, use \cs{FmtToGray} after it; for example,
%    \begin{quote}
%       |\AAFormat{AFNumber_Format(0,1,0,0,"",true);|\\
%       |\FmtToGray{|\ameta{grayhint}|}}|
%    \end{quote}
%    \begin{macrocode}
\newcommand\FmtToGray[1]{if(event.value=="")event.value=("#1");}
%    \end{macrocode}
%    \end{macro}
%    \begin{macro}{\KeyToGray}
%    This command is placed in the Keystroke event. It changes
%    the color to `gray' (\cs{gh@graycolor}) if the field is empty.
%    If a built-in Adobe function is also used, use \cs{KeyToGray} after it; for example,
%    \begin{quote}
%       |\AAFormat{AFNumber_Keystroke(0,1,0,0,"",true);|\\
%       |\KeyToGray}|
%    \end{quote}
%    \begin{macrocode}
\newcommand\KeyToGray{if(event.value=="")%
    event.target.textColor=\gh@graycolor;}
%    \end{macrocode}
%    \end{macro}
%    \begin{macro}{\CalcToGray}
%    The \cs{CalcToGray} is a Calculate script, it is needed only in a form field that performs
%    a calculation. If a built-in Adobe function is also used, use \cs{KeyToGray} after it; for example,
%    \begin{quote}
%       |\AACalculate{var cArray=new Array("Integer");\r|\\
%       |if (AllowCalc(cArray)) AFSimple_Calculate("SUM", cArray );\r|\\
%       |\CalcToGray}|
%    \end{quote}
%    \begin{macrocode}
\newcommand\CalcToGray{event.target.textColor=%
    (event.value=="")?\gh@graycolor:\gh@normalcolor;}
%    \end{macrocode}
%    \end{macro}
%    \begin{macro}{\FocusToBlack}
%    A command placed within the OnFocus event. When the field comes into focus, and
%    the field is empty, the color for the text is turned to black. This can be redefined
%    to another color.
%    \begin{macrocode}
\newcommand\FocusToBlack{if(event.target.valueAsString=="")%
    event.target.textColor=\gh@normalcolor;}
%    \end{macrocode}
%    \end{macro}
%    \begin{macro}{\BlurToBlack}
%    A command placed within the OnBlur event. It sets the text color to gray or black,
%    depending on whether the field is empty or not. My be redefined with different colors.
%    \begin{macrocode}
\newcommand\BlurToBlack{event.target.textColor=%
    (event.target.valueAsString=="")?\gh@graycolor:\gh@normalcolor;}
%    \end{macrocode}
%    \end{macro}
%
%    \subsection{Document JavaScript to support gray hints}
%    Technically speaking, the only lines really required are
%    the ones defining the
%    function \texttt{AllowCalc}, and this is used only when you are
%    creating a series of calculation fields that performs arithmetic operations
%    on the dependent fields.
%    \begin{macrocode}
\nodljsend
\begin{insDLJS}{ghsupport}{grayhints: Support for the Calculate Event}
%    \end{macrocode}
%    In order to get the gray hints to appear in the terminal field of a calculation group,
%    we cannot perform the calculate when all the dependent fields are empty. \texttt{cArray}
%    is an array of all dependent fields involved in the calculation. The use of this function
%    is illustrated in \texttt{grayhints.tex}.
%    \begin{macrocode}
function AllowCalc(cArray) {
    var f,g;
    for (var i=0; i<cArray.length; i++) {
        f=this.getField(cArray[i]);
        g=f.getArray();
        for (var j=0; j<g.length; j++)
            if (g[j].valueAsString!="") return true;
    }
    return false;
}
\end{insDLJS}
%    \end{macrocode}
%    \begin{macrocode}
%</package>
%    \end{macrocode}
\endinput