summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/grayhints
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2017-03-20 23:05:30 +0000
committerKarl Berry <karl@freefriends.org>2017-03-20 23:05:30 +0000
commit3ab396090f30955eb1ece56905cb5bda36e7b22b (patch)
tree8accb43050d4b3f1b19306486e8266b5cdcaf789 /Master/texmf-dist/source/latex/grayhints
parent9629eb95a35b6c79d6d31ff27653d3a006b25b9b (diff)
grayhints (20mar17)
git-svn-id: svn://tug.org/texlive/trunk@43561 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/source/latex/grayhints')
-rw-r--r--Master/texmf-dist/source/latex/grayhints/grayhints.dtx348
-rw-r--r--Master/texmf-dist/source/latex/grayhints/grayhints.ins58
2 files changed, 406 insertions, 0 deletions
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. %%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%</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
diff --git a/Master/texmf-dist/source/latex/grayhints/grayhints.ins b/Master/texmf-dist/source/latex/grayhints/grayhints.ins
new file mode 100644
index 00000000000..064332eb747
--- /dev/null
+++ b/Master/texmf-dist/source/latex/grayhints/grayhints.ins
@@ -0,0 +1,58 @@
+%%
+%% This file will generate fast loadable files and documentation
+%% driver files from the doc files in this package when run through
+%% LaTeX or TeX.
+%%
+%% Copyright 2016 D. P. Story
+%% -------------------------------------------
+%%
+%% It may be distributed under the conditions of the LaTeX Project Public
+%% License, either version 1.2 of this license or (at your option) any
+%% later version. The latest version of this license is in
+%% http://www.latex-project.org/lppl.txt
+%% and version 1.2 or later is part of all distributions of LaTeX
+%% version 1999/12/01 or later.
+%%
+%% --------------- start of docstrip commands ------------------
+%%
+\def\filedate{2016/01/12}
+\def\batchfile{grayhints.ins}
+
+\input docstrip
+\ifx\generate\undefined
+ \Msg{**********************************************}
+ \Msg{*}
+ \Msg{* This installation requires docstrip}
+ \Msg{* version 2.4 or later.}
+ \Msg{*}
+ \Msg{* An older version of docstrip has been input}
+ \Msg{*}
+ \Msg{**********************************************}
+ \errhelp{Move or rename old docstrip.tex and get a newer one.}
+ \errmessage{Old docstrip in input path}
+ \batchmode
+ \csname @@end\endcsname\end
+\fi
+
+\keepsilent
+\askforoverwritefalse
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\preamble
+\endpreamble
+
+\generate
+{%
+ \file{grayhints.sty}{\from{grayhints.dtx}{copyright,package}}
+}
+
+\Msg{***************************************************************}
+\Msg{*}
+\Msg{* \space To finish the installation you have to copy the files }
+\Msg{*}
+\Msg{* \space *.sty, *.cfg and *.def into a directory searched by TeX}
+\Msg{*}
+\Msg{***************************************************************}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\endinput