From 3ab396090f30955eb1ece56905cb5bda36e7b22b Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Mon, 20 Mar 2017 23:05:30 +0000 Subject: grayhints (20mar17) git-svn-id: svn://tug.org/texlive/trunk@43561 c570f23f-e606-0410-a88d-b1316a301751 --- .../source/latex/grayhints/grayhints.dtx | 348 +++++++++++++++++++++ 1 file changed, 348 insertions(+) create mode 100644 Master/texmf-dist/source/latex/grayhints/grayhints.dtx (limited to 'Master/texmf-dist/source/latex/grayhints/grayhints.dtx') diff --git a/Master/texmf-dist/source/latex/grayhints/grayhints.dtx b/Master/texmf-dist/source/latex/grayhints/grayhints.dtx new file mode 100644 index 00000000000..9756703cf75 --- /dev/null +++ b/Master/texmf-dist/source/latex/grayhints/grayhints.dtx @@ -0,0 +1,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. %% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% +%\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 -- cgit v1.2.3