%\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. %% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % %\NeedsTeXFormat{LaTeX2e}[1997/12/01] %\ProvidesPackage{grayhints} % [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} % % \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 % \end{macrocode} \endinput