From a979a969ee8a924408ebeb767035b9e4f48f7efa Mon Sep 17 00:00:00 2001 From: Norbert Preining Date: Mon, 1 Feb 2021 13:14:30 +0900 Subject: acrotex (2021-02-01) --- texmf-dist/doc/latex/acrotex/eformman.tex | 390 +++++++++++++++--------------- 1 file changed, 195 insertions(+), 195 deletions(-) (limited to 'texmf-dist/doc/latex/acrotex/eformman.tex') diff --git a/texmf-dist/doc/latex/acrotex/eformman.tex b/texmf-dist/doc/latex/acrotex/eformman.tex index a07ff1da..881a9f40 100644 --- a/texmf-dist/doc/latex/acrotex/eformman.tex +++ b/texmf-dist/doc/latex/acrotex/eformman.tex @@ -6,10 +6,8 @@ forcolorpaper,latextoc,pro,useui}, exerquiz,aebxmp ]{aeb_pro} -\usepackage{forms16be} \usepackage[dblevel=0]{aeb_mlink} \usepackage[altbullet]{lucidbry} -\usepackage{pifont} %\usepackage{myriadpro} \setlength{\marginparpush}{3pt} @@ -29,6 +27,7 @@ \def\mSTRUT{\makebox[0pt][l]{\phantom{$\frac00$}}} \let\vrbnormal\sffamily \let\uif\sffamily +\let\key\texttt %\makeatletter @@ -80,8 +79,8 @@ email={dpstory@acrotex.net}, subject={Documentation for the eforms and insdljs packages}, talksite={\url{www.acrotex.net}}, - version={2020/03/14}, - prepared={2020/03/14}, + version={2.0}, + prepared={2021/01/20}, preparedLabel={Distribution Dated:}, keywords={LaTeX, hyperref, PDF, exercises, quizzes}, copyrightStatus=True, @@ -163,7 +162,6 @@ \def\AcroTeX{Acro\!\TeX} \def\HTML{HTML}\def\FDF{FDF} \def\PDF{PDF}\def\URL{URL} -\def\DVI{DVI} %\let\amtIndent\leftmargini \edef\amtIndent{\the\parindent} \def\bNH{\begin{NoHyper}}\def\eNH{\end{NoHyper}} @@ -193,7 +191,6 @@ \def\endredpoint{\FitItIn{{\large\ifusebw\color{black}\else\color{red}\fi$\blacktriangleleft$}}} \def\pb{pushbutton} -\def\pbs{pushbuttons} %\advance\marginparwidth16pt @@ -368,10 +365,10 @@ The field can be signed, either by using \app{Acrobat}, or programmatically from a {\LaTeX} source, but you need to use \textsf{aeb\_pro} and to create the PDF using \app{Acrobat} Distiller. -The \pkg{hyperref} Package (Rahtz, Oberdiek \textit{et al}) +The \textsf{hyperref} Package (Rahtz, Oberdiek \textit{et al}) provides support for the same set of form fields; however, not all features of these fields can be accessed through the -\pkg{hyperref} commands. I was determined to write my own set +\textsf{hyperref} commands. I was determined to write my own set of commands which would be sufficiently comprehensive and extendable to suit all the needs of the \cAcroB. All the quiz environments have been modified to use this new set of form @@ -406,7 +403,7 @@ an integral part of \textsf{Exerquiz}. I've now separated the two, making \subsection{Package Requirements} -The \textsf{eforms} package requires \pkg{hyperref} (a newer version) +The \textsf{eforms} package requires \textsf{hyperref} (a newer version) and \textsf{insdljs}, a package that is part of the {\cAcroB}. \subsection{Package Options} @@ -437,31 +434,30 @@ defined in these earlier included packages. I fall down easily. \end{document} \end{Verbatim} -\noindent The \textsf{eforms} package brings in the \pkg{hyperref} package +\noindent The \textsf{eforms} package brings in the \textsf{hyperref} package and passes it the driver, so there is no need to specify -\pkg{hyperref}, usually. If you wish to introduce \pkg{hyperref} +\textsf{hyperref}, usually. If you wish to introduce \textsf{hyperref} yourself with specific options, place it before \textsf{eforms}. If you use the \textsf{exerquiz} package, \textsf{exerquiz} brings in the \textsf{eforms} package and passes the driver to it. -\subsection{The \texttt{preview} option}\label{s:preview} +\subsection{The \texttt{preview} option} %Use the \texttt{preview} option if you use a \texttt{dvi} previewer %to view your document. When the \opt{preview} option is taken, a frame box is drawn around any form field created by \pkg{eforms}, making the position of the field visible in -the {\DVI} previewer or {\PDF} reader. Being able to view the position of a -form element is important to determine whether any additional adjustments in -position is. \emph{Turn off this option} when you build the final version of -the document. - -This option was originally developed for those using a {\DVI} previewer, it -is also useful for those using PDF creators \app{pdflatex}, \app{xelatex}, or -\app{lualatex}. Modern {\LaTeX} users employ quicker {\PDF} readers such as -\app{sumatraPDF} or \app{PDF-Exchange}; these non-conforming {\PDF} readers -may not create form field appearances as \app{Adobe Reader} and \app{Acrobat} +the DVI previewer or {\PDF} viewer. Being see to view the position on a form +element enables you to determine whether any additional adjustments are +needed to the position of the field. \emph{Turn off this option} when you build the +final version of your {\PDF} file. + +This option was originally developed for those using a DVI previewer, it is +also useful for those using PDF creators \app{pdflatex}, \app{xelatex}, or +\app{lualatex}. Modern {\LaTeX} users employ quicker {\PDF} viewers such as \app{sumatraPDF} or +\app{PDF-Exchange}; these PDF viewers do not create form appearances as \app{Adobe Reader} and \app{Acrobat} do; consequently, an outline of the positions of the fields is most welcome. The \texttt{preview} option just sets a switch (\cs{ifpreview}\FmtMP{\cs{ifpreview}}), which can conveniently be @@ -469,9 +465,10 @@ turned off and on using the commands \cs{previewOn}\FmtMP{\cs{previewOn}} and \c within the document itself. Related to \cs{previewOn} and \cs{previewOff}\FmtMP{\cs{previewOff}} is the command \cs{pmpvOn} (poor man's preview), covered in the next paragraph. -\paragraph*{Enhanced preview (Poor man's preview).}\label{para:pmpv} +\paragraph*{Poor man's preview.}\label{para:pmpv} -The \cs{pushButton} command of \pkg{eforms} produces a \pb;\footnote{Pushbuttons are covered in Section~\ref{s:BtnFlds}, beginning on +The \cs{pushButton} command of \pkg{eforms} produces a push +button;\footnote{Push buttons are covered in Section~\ref{s:BtnFlds}, beginning on page~\pageref{ss:Pbs}.} a common key to use is the \cs{CA} key, the value of which captions the button. As a companion to \cs{previewOn}, \pkg{eforms} defines \cs{pmpvOn}\FmtMP{\cs{pmpvOn}} and @@ -483,21 +480,19 @@ the {\pb} preview; for example,\bgroup\makeatletter {\previewOff\pmpvOff\pushButton[\autoCenter{n}\CA{Push Me}]{pbDemoL}{}{13bp}\quad \previewOn\pmpvOn\pushButton[\autoCenter{n}\CA{Push Me}]{pbDemoR}{}{13bp}\hspace{40pt}}}}%\ef@Bbox{\x}{13bp} \begin{Verbatim}[xleftmargin=\amtIndent,fontsize=\small,commandchars=!()] -\previewOn\pmpvOn % <--!textsf(enhanced preview activated) -... !1\pushButton[\CA{Push Me}]{pbDemo}{}{13bp} \end{Verbatim} -The button on the left is the normal appearance of the {\pb} after +The button on the left is the normal appearance of the push button after \app{Reader/Acrobat} has supplied its appearance, the ``button'' on the right is how the button would appear in \app{sumatraPDF}, for example, just after {\PDF} creation using \app{pdflatex}, \app{xelatex}, or \app{lualatex}, or in a DVI previewer after latexing.\egroup -There are enhanced previews for other fields that support a \cs{V} or \cs{CA} -key (\pbs, text fields, list boxes, combo boxes, check boxes and -radio button fields). In each case, the argument of the key is \emph{typeset -into the document} beneath the field when \cs{pmpvOn} is expanded prior. The -arguments of \cs{V} and \cs{CA} recognize a local command +There are `poor man's previews' for other fields that support a \cs{V} or +\cs{CA} key (push buttons, text fields, list boxes, combo boxes, check boxes +and radio button fields). In each case, the argument of the key is +\emph{typeset into the document} beneath the field when \cs{pmpvOn} is +expanded prior. The arguments of \cs{V} and \cs{CA} recognize a local command \cs{tops}\FmtMP{\cs{tops}} (\cs{textorpdfstring}) to offer an alternate string that is typeset: \begin{quote} @@ -519,31 +514,12 @@ declarative command \cs{pmpvMrk\darg{\ameta{mrk}}} that takes one argument \amet to be used. The package declares \verb|\pmpvMrk{X}|, another good choice is \verb|\pmpvMrk{$\checkmark$}|. -\newtopic\indent\textbf{Finer control over enhanced preview.} When enhanced -preview is on (\cs{previewOn}\allowbreak \cs{pmpvOn}), the caption for {\pbs} -may be turned off with \cs{pmpvCAOff}\FmtMP{\cs{pmpvCAOff}} (and may be -turned back on again with \cs{pmpvCAOn}). Enhanced preview for all other -field types is controlled with \cs{pmpvVOff}\FmtMP{\cs{pmpvVOff}} (and -\cs{pmpvVOn}). Turning off enhanced preview may be become an issue when the -preview text is too wide for the preview rectangle -{\previewOn\pmpvOn\textField[\autoCenter{y}\BC{}\Ff{\FfReadOnly}\V{We initialize this field}\DV{We -initialize this field}]{V2Big}{1in}{11bp}}. We can turn off enhanced preview -for this field only by passing \cs{cmd\darg{\cs{pmpvVOff}}} in the optional -argument of the field, or turn it off globally by expanding \cs{pmpvVOff} -prior to expanding the \cs{textField} command. - -\newtopic\textbf{\textcolor{red}{Final Preparation.}} In the modern era of {\LaTeX}, it is customary by some to use -\app{sumatraPDF} or some other non-conforming {\PDF} reader during -development; however, you should always open your final {\PDF} (which was -built with \cs{previewOff}\cs{pmpvOff}) in \app{Adobe Reader DC} (or in -\app{Acrobat}), save it to obtain the correct appearances of the fields -placed in the document. Other suggestions can be found in the -\href{\urlAcroTeXBlog}{\AcroBlog} article cited below. - -%http://www.acrotex.net/blog/?p=1404 -\exAeBBlogPDF{p=1404} Refer to the article titled \textit{\href{\urlAcroTeXBlog/?p=1404}{eforms: Enhanced Previews}} for more technical -details and examples; the article is found on the \href{\urlAcroTeXBlog}{\AcroBlog} website. +\app{sumatraPDF} or some other {\PDF} viewer during development; however, you +should always open your final {\PDF} (which was built with +\cs{previewOff}\cs{pmpvOff}) in \app{Adobe Reader DC} (or in \app{Acrobat}), +save it to obtain the correct appearances of the fields placed in the +document. \subsection{The \texttt{useui} option} @@ -555,10 +531,10 @@ more ``user-friendly'' to use. See \hyperref[useui]{Section~\ref*{useui}}, page~\pageref*{useui}, for a description of these key-value pairs. -\subsection{The \texttt{unicode} option of \texorpdfstring{\protect\pkg}{}{hyperref}} +\subsection{The \texttt{unicode} option of \textsf{hyperref}} The \textsf{eforms} package will obey the \texttt{unicode} option of -\pkg{hyperref}. Whenever this option is taken in hyperref, for +\textsf{hyperref}. Whenever this option is taken in hyperref, for certain keys (namely, \cs{V}, \cs{DV}, \cs{TU}, \cs{CA}, \cs{RC}, and \cs{AC}), standard latex markup may be used to enter the values of these keys, for example, in a text field, you might set @@ -568,15 +544,13 @@ value of ``J\"{u}rgen'' in that text field. \section{Form Fields} -The \pkg{eforms} support for {\PDF} forms defines seven basic (and internal) +The \texttt{eforms} support for {\eForm} defines seven basic (and internal) commands for creating the seven types of form elements. These seven are used as ``building blocks'' for defining all buttons, check boxes, radio buttons and text fields used in the \texttt{exerquiz} quizzes; and for defining seven user-commands: \cs{listBox}, \cs{comboBox}, \cs{pushButton}, \cs{checkBox}, \cs{radioButton}, \cs{textField}, and \cs{sigField}. These user commands are -the topic of the subsequent sections. Note, viewing these form fields outside of -\app{Adobe Reader} or \app{Acrobat} itself may be a problem, please review the paragraphs -on titled \Nameref{s:preview}. +the topic of the subsequent sections. Each of the above listed field commands has an optional first parameter that is used to modify the appearance of the field, @@ -646,14 +620,14 @@ Within the first parameter, these three character can be used freely, without es \subsection{Button Fields}\label{s:BtnFlds} Buttons are form elements that the user interacts with using only a -mouse. There are three types of buttons: {\pbs}, check boxes +mouse. There are three types of buttons: push buttons, check boxes and radio buttons. -\subsubsection{Pushbutton fields}\label{ss:Pbs} +\subsubsection{Push Buttons}\label{ss:Pbs} -The {\pb} is a button field that has no value, it is neither on nor off. -Generally, {\pbs} are used to initiate some action, such as JavaScript -action. +The push button is a button field that has no +value, it is neither on nor off. Generally, push buttons are used +to initiate some action, such as JavaScript action. \settowidth{\aebdimen}{\cs{pushButton[\#1]\darg{\#2}\darg{\#3}\darg{\#4}}} \begin{dCmd}[commandchars=!()]{\aebdimen+2\fboxsep+2\fboxrule} @@ -663,13 +637,13 @@ action. \PD \begin{enumerate} \item[\texttt{\#1}:] optional, used to enter any modification of appearance/actions -\item[\texttt{\#2}:] the title of the button field (also called the field name) +\item[\texttt{\#2}:] the title of the button field \item[\texttt{\#3}:] the width of the bounding rectangle \item[\texttt{\#4}:] the height of the bounding rectangle \end{enumerate} \paragraph*{Default Appearance:} The default appearance of -a {\pb} is determined by the following: +a push button is determined by the following: \begin{Verbatim}[xleftmargin=\amtIndent] \W{1}\S{B}\F{\FPrint}\BC{0 0 0} \H{P}\BG{.7529 .7529 .7529} @@ -705,7 +679,7 @@ width based on the width of the text given by \Cs{CA}, \Cs{RC} and \pushButton[\CA{Push}\AC{Me}\RC{Reset}\A{/S/ResetForm}] {myButton}{}{12bp} \end{Verbatim} -Refer to the \pkg{icon-appr} package to supply icon appearances to {\pbs} created by +Refer to the \pkg{icon-appr} package to supply icon appearances to push buttons created by the \pkg{eforms} package. \subsubsection{Check Boxes}\label{CheckBoxes} @@ -1233,10 +1207,10 @@ places message in the console when the field is signed. \item The \cs{Lock} key can be used to lock various fields when the document is signed. -\begin{Verbatim}[xleftmargin=\amtIndent,numbers=left] +\begin{Verbatim}[xleftmargin=\amtIndent,numbers=left,commandchars=!()] \Lock{/Action/All} -\Lock{/Action/Include/Fields [(field1)(field2)...]} -\Lock{/Action/Exclude/Fields [(field1)(field2)...]} +\Lock{/Action/IncludeFields{!ameta(field!SUB1),!ameta(field!SUB2),...}} +\Lock{/Action/ExcludeFields{!ameta(field!SUB1),!ameta(field!SUB2),...}} \end{Verbatim} \begin{itemize} \item In (1), all fields are locked when the signature field is signed. @@ -1245,7 +1219,7 @@ is signed. \item In (3), all fields, except the ones listed, are locked when the signature field is signed. \end{itemize} -The \texttt{/Fields} key is required when the action is either \texttt{/Include} or \texttt{/Exclude}. +%The \texttt{/Fields} key is required when the action is either \texttt{/Include} or \texttt{/Exclude}. \end{itemize} @@ -1261,7 +1235,7 @@ and can perform a wide range of actions. The borders of the link commands can be controlled through optional parameter, their default appearance follow the same pattern of hyperref: If the \texttt{colorlinks} option is used (in -\pkg{hyperref}) then the border is invisible by default; +\textsf{hyperref}) then the border is invisible by default; otherwise, there is a visible border. When the \texttt{colorlinks} option is chosen (in hyperref), the @@ -1271,7 +1245,7 @@ is a named color. \cs{defaultlinkcolor} has a definition of \newcommand{\defaultlinkcolor}{\@linkcolor} \end{Verbatim} \noindent where \cs{@linkcolor} is a command defined in -\pkg{hyperref}, and is defined to be \texttt{red}. This can be +\textsf{hyperref}, and is defined to be \texttt{red}. This can be redefined as desired.\footnote{The {\Web} package redefines \cs{@linkcolor} to be a flavor of green.} @@ -1292,7 +1266,7 @@ parameter takes key-value pairs to change appearance and define actions. The default appearance of this link is \verb!\S{S}\Border{0 0 0}!, an invisible yet solid border line. (The visibility of the border is actually controlled by the \texttt{colorlinks} option of -\pkg{hyperref}, as explained above.) The second parameter is the +\textsf{hyperref}, as explained above.) The second parameter is the link text. This argument does not have to be text, it can be anything that takes up space, such as a graphic or \cs{parbox}. @@ -2100,7 +2074,7 @@ For example, uptxt={Push Me} } \end{Verbatim} -Later, a {\pb} can use this preset, like so, +Later, a push button can use this preset, like so, \begin{Verbatim}[xleftmargin=\amtIndent] \pushButton[\ui{presets=\myFavFive, js={app.alert("AcroTeX rocks!")}}]{pb1}{}{11bp} @@ -2131,7 +2105,7 @@ border line width to zero \verb!\W{0}!. For forms, this key has no counterpart in the user interface. If this key is not specified, the \textsf{eforms} -follows the rule: If \texttt{colorlinks} option of \pkg{hyperref} is used, the border is invisible; +follows the rule: If \texttt{colorlinks} option of \textsf{hyperref} is used, the border is invisible; otherwise, it is visible (and the default \texttt{linewidth} is 1). Use the border key to override this behavior. @@ -2228,7 +2202,7 @@ values are ``or-ed'' together. Normally, a document author would not specify \texttt{radio}, \texttt{pushbutton} or \texttt{combo}. These properties are used by -\textsf{eforms} to construct a radio button field, a {\pb} and a combo +\textsf{eforms} to construct a radio button field, a push button and a combo box. The others can be used as appropriate. \settowidth{\aebdimen}{\ttfamily maxlength=\anglemeta{num}}% @@ -2311,7 +2285,7 @@ If the \opt{unicode} option of \pkg{hyperref} is in effect, then setting % \texttt{eqforms\_pro.tex} -\newtopic \textbf{Pushbuttons only.} The following list of keys are used for +\newtopic \textbf{Push buttons only.} The following list of keys are used for creating custom appearances on button faces. \app{Acrobat} Distiller required for this set. The example files \marginpar{\mbox{\makebox[0pt][l]{\textcolor{blue}{\Pisymbol{webd}{254}}}\raisebox{-2pt}{\color{red}{{\zqacr @@ -2513,6 +2487,51 @@ that appears in the field when the box is checked. Choices are \texttt{check}, \texttt{circle}, \texttt{cross}, \texttt{diamond}, \texttt{square}, and \texttt{star}. +\settowidth{\aebdimen}{\ttfamily rectW=\ameta{length}}% +\def\1{\llap{\Cs{rectW}\hspace{\marginparsep}}}% +\begin{dCmd}[commandchars=!()]{\aebdimen+2\fboxsep+2\fboxrule} +!1rectW=!ameta(length) +\end{dCmd} +\CmdDescription Resets the width of the field to \ameta{length}. + +\settowidth{\aebdimen}{\ttfamily rectH=\ameta{length}}% +\def\1{\llap{\Cs{rectH}\hspace{\marginparsep}}}% +\begin{dCmd}[commandchars=!()]{\aebdimen+2\fboxsep+2\fboxrule} +!1rectH=!ameta(length) +\end{dCmd} +\CmdDescription Resets the height of the field to \ameta{length}. + +\settowidth{\aebdimen}{\ttfamily width=\ameta{length}}% +\def\1{\llap{\Cs{width}\hspace{\marginparsep}}}% +\begin{dCmd}[commandchars=!()]{\aebdimen+2\fboxsep+2\fboxrule} +!1width=!ameta(length) +\end{dCmd} +\CmdDescription Sets the width of the field to \ameta{length} and +resets the height to maintain the same aspect ratio of the field. For example, +\begin{Verbatim}[fontsize=\small,commandchars=!()] +\pushButton{pb}{.5in}{1in} %!sffamily( width of .5in and height of 1in) +\pushButton[\width{1in}]{pb}{.5in}{1in} %!sffamily( width of 1in and height of 2in) +\pushButton[\ui{width=1in}]{pb}{.5in}{1in} %!sffamily( same as above) +\end{Verbatim} + +\settowidth{\aebdimen}{\ttfamily height=\ameta{length}}% +\def\1{\llap{\Cs{height}\hspace{\marginparsep}}}% +\begin{dCmd}[commandchars=!()]{\aebdimen+2\fboxsep+2\fboxrule} +!1height=!ameta(length) +\end{dCmd} +\CmdDescription Sets the height of the field to \ameta{length} and +resets the width to maintain the same aspect ration of the field. + +\settowidth{\aebdimen}{\ttfamily scalefactor=\ameta{pos-num}}% +\def\1{\llap{\Cs{scalefactor}\hspace{\marginparsep}}}% +\begin{dCmd}[commandchars=!()]{\aebdimen+2\fboxsep+2\fboxrule} +!1scalefactor=!ameta(pos-num) +\end{dCmd} +\CmdDescription Multiplies the width and height of the field by a scale +factor of \ameta{pos-num}. For example, setting \texttt{scalefactor=2} doubles +the length of the width and height of the field. + + \subsection{The Action Tab} @@ -2654,20 +2673,22 @@ JavaScript code (\anglemeta{script}). \settowidth{\aebdimen}{\ttfamily lock=\darg{\anglemeta{PDF KV-pairs}}} \def\1{\llap{\Cs{Lock}\hspace{\marginparsep}}}%Lock \begin{dCmd}[commandchars=!()]{\aebdimen+2\fboxsep+2\fboxrule} -!1lock={!anglemeta(PDF KV-pairs)} +!1lock={!anglemeta(KV-pairs)} \end{dCmd} -\CmdDescription The \texttt{lock} key is used with signature fields, currently, there is - no nice user interface to this key. Typical entries are -\begin{Verbatim}[xleftmargin=\amtIndent] -lock={/Action/All} % lock all fields in the doc -lock={/Action/Include % lock all fields listed in Fields - /Fields [(field1)(field2)...]} -lock={/Action/Exclude % lock all fields not listed in Fields - /Fields [(field1)(field2)...]} +\CmdDescription The \texttt{lock} key is used with signature fields; use the +\key{action} key (with supported values of \texttt{all}, \texttt{include}, and \texttt{exclude}) +and the \key{fields} key to determine the lock action. +\begin{Verbatim}[xleftmargin=\amtIndent,commandchars=!()] +%!sffamily lock all fields in the doc +lock={action=all} +% !sffamily lock all fields listed by !texttt(fields) key +lock={action=include,fields={!ameta(field!SUB1),!ameta(field!SUB2),...}} +% !sffamily lock all fields not listed by !texttt(fields) key +lock={action=exclude,fields={!ameta(field!SUB1),!ameta(field!SUB2),...}} \end{Verbatim} -\newtopic Another option that is included in the Signed tab is titled ``This script executes +\newtopic Another option that is included in the \uif{Signed tab} is titled ``This script executes when field is signed.'' This is an option that, through the user interface, is mutually exclusive from @@ -2857,7 +2878,7 @@ The \hypertarget{\pkg{insdljs}}{insdljsPkg} package provides support to {\LaTeX} for inserting \app{Acrobat} JavaScript into a PDF file created from a \LaTeX{} source. This package works correctly for users of \textsf{pdftex} (and \app{luatex}), \textsf{dvipdfm}, \textsf{dvipdfmx}, and \texttt{xetex}. -For\FmtMP{\app{Acrobat} required for +For\marginpar{\small\raggedleft\app{Acrobat} required for \app{dvips}} those who use either \app{dvips} or \app{dvipsone} to produce a postscript file, which is then distilled, you are required to have \app{Acrobat}~5.0 (or later). @@ -2865,12 +2886,12 @@ required to have \app{Acrobat}~5.0 (or later). \section{Package Options} The \textsf{insdljs} supports five common ``drivers'': \texttt{dvipsone}, -\texttt{dvips}, \texttt{pdftex} (including the executable \textsf{lu(la)tex}), \texttt{dvipdfm}, -\texttt{dvipdfmx}, \texttt{xetex}, and \texttt{tex\-tures}. When using -\texttt{dvipsone} or \texttt{dvips}, \app{Acrobat} Distiller and \app{Acrobat} -(version 5.0 or later) are required to embed the JavaScripts at the -document level. The other drivers have primitives that allow the embedding -of the JavaScripts. +\texttt{dvips}, \texttt{pdftex} (including the executable +\textsf{lu(la)tex}), \texttt{dvipdfm}, \texttt{dvipdfmx}, \texttt{xetex}, and +\texttt{tex\-tures}. When using \texttt{dvips}, \app{Acrobat} Distiller and +\app{Acrobat} (version 5.0 or later) are required to embed the JavaScripts at +the document level. The other drivers have primitives that allow the +embedding of the JavaScripts. \newtopic Other options are discussed in the following paragraphs. \begin{description}\def\NH{\hspace{-\labelsep}} @@ -2878,20 +2899,12 @@ of the JavaScripts. JavaScript. This might be useful, for creating a paper document that is not interactive. For a non-interactive paper document, no JS is needed. -\item\NH\texttt{execJS} is a very useful option/feature if you know how to - use it. Any JavaScript that is written in an \env{execJS} environment - is executed once when the document is first opened in \app{Acrobat}, - then discarded. AeB uses this for post-creation document processing. - The default is that the JavaScript in an \texttt{execJS} environment is - not executed; using this option turns on this feature. Two convenience - commands are also defined: \FmtMP{\cs{execJSOn}} \cs{execJSOn} (the - equivalent of passing the \opt{execJS} option to the \pkg{insdljs} - package) and \FmtMP{\cs{execJSOff}}\cs{execJSOff} (for turning off - JavaScript execution within an \env{execJS} environment). Both have no - effect outside the preamble of the document. - - For information on the \env{execJS} environment, read - Section~\ref{s:execJS} on page~\pageref{s:execJS}. +\item\NH\texttt{execJS} is a very useful option/feature if you know how to use + it. Any JavaScript that is written in an \env{execJS} environment is + executed once when the document is first opened in \app{Acrobat}, then + discarded. AeB uses this for post-distillation document processing. The + default is that the JavaScript in an \texttt{execJS} environment is not + executed; using this option turns on this feature. \end{description} \section{The \texttt{insDLJS} and \texttt{insDLJS*} Environments} @@ -3039,7 +3052,7 @@ the \textsf{eforms} package defines its own \cs{pushButton} command. \Example Here is the same example as above, but with \textsf{dvips} as the driver and using the \textsf{eforms} package, which calls \textsf{insdljs}. Note the use of the optional argument in the -\texttt{insDLJS} environment, and the missing \pkg{hyperref} package +\texttt{insDLJS} environment, and the missing \textsf{hyperref} package statement and \texttt{Form} environment, the \textsf{eforms} package automatically inserts this code. \begin{Verbatim}[xleftmargin=\amtIndent] @@ -3259,20 +3272,8 @@ When \cs{thisPageAction} is executed in the preamble, the \texttt{} argument gets passed to the \cs{OpenAction} command. -\section{The \textsf{execJS} Environment}\label{s:execJS} - -\textbf{Purpose.} The\FmtMP{`\texttt{\eqbs}' and `\texttt{\%}' characters available} \env{execJS} takes JavaScript as content. This -JavaScript is executed the first time the newly created PDF is opened in -\app{Acrobat}. This environment is a variation on \env{insDLJS}; -consequently, -the escape character is `\texttt{\eqbs}' and the comment character is -`\texttt{\%}'. - -\newtopic -\textbf{Requirements.} For the script to be executed, the document must be compiled under -the \opt{execJS} option of \pkg{eforms}. +\section{The \textsf{execJS} Environment} -\newtopic This is an environment useful to PDF developers who want to tap into the power of JavaScript. To use this environment, the developer needs \app{Acrobat}~5.0 or higher. \textsf{pdftex} or \textsf{dvipdfm} can @@ -3280,8 +3281,8 @@ be used to produce the PDF document, but the developer needs the \app{Acrobat} product for this environment to do anything. The \texttt{execJS} is used primarily for post-distillation -processing (post-creation processing, in the case of \textsf{pdflatex} -and \textsf{xelatex}). The \texttt{execJS} environment can be used, +processing (post-creation processing, in the case of \textsf{pdftex} +and \textsf{dvipdfm}). The \texttt{execJS} environment can be used, for example, to automatically import named icons into the document, which can, in turn, be used for an animation. @@ -3295,22 +3296,18 @@ by the \textsf{execJS} environment is imported, and the JavaScript executed. This JavaScript is \emph{not} saved with the document. The syntax of this environment is\dots -\settowidth{\aebdimen}{\ttfamily\string\begin\darg{execJS}[\ameta{\cs{cmd}}]\darg{\meta{name}}} +\settowidth{\aebdimen}{\ttfamily\string\begin\darg{execJS}\darg{\meta{name}}} \begin{dCmd}[commandchars=!()]{\aebdimen+2\fboxsep+2\fboxrule} -\begin{execJS}[!ameta(\cmd)]{!meta(name)} +\begin{execJS}{!meta(name)} .... -!ameta(JavaScript code) +!anglemeta(JavaScript code) .... \end{execJS} \end{dCmd} -\PD The environment takes one required argument (\meta{name}), the base name -of the auxiliary files to be generated. The \env{execJS} environment now has -an optional argument, the optional argument must be a command -\ameta{\cs{cmd}}. The purpose of \ameta{\cs{cmd}} is to make special -definitions at the time the script is expanded. +\PD The environment takes one required argument, the base name of the +auxiliary files to be generated. -\newtopic\indent Many of the more useful JavaScript methods have security restrictions, the developer must create folder JavaScript that can be used to \emph{raise the privilege} of the methods. @@ -3371,31 +3368,6 @@ app.endPriv(); \end{Verbatim} \newtopic AeB Pro, the {Acro\!\TeX} Presentation Bundle and @EASE use these execJS techniques. -\Example In this example, we give a simple example of the use of the optional argument (\ameta{\cs{cmd}}). -We define a command \cs{myDefns} which gives a special meaning to \cs{oct}. This definition -are made within a group so it has no effect outside the environment. -\begin{Verbatim}[xleftmargin=\amtIndent,commandchars={!~@}] -... -\execJSOn -!textbf~\def\myDefns{\let\oct\eqbs}@ -\begin{execJS}[!textbf~\myDefns@]{tst} -var str="Hello J!textbf~\oct@374rgen! \u263A"; // \u already defined -console.show(); -console.println(str); -\end{execJS} -\begin{document} -... -\end{document} -\end{Verbatim} -\defUniStr{myInitValue}{Hello J\u00FCrgen! \u263A}% -%\previewOn\pmpvOn -When the document is first opened, the console window appears and the message, \ding{172} -\begin{quote} -\textField[\cmd{\let\pmpvFmt\footnotesize}\Ff\FfReadOnly\BC{}\V{\tops{Hello J\"{u}rgen! \protect\ding{172}}{\unicodeStr(myInitValue)}} -\DV{\unicodeStr(myInitValue)}]{HJSmiley}{67.68bp}{11bp} -\end{quote} -is written to the console window. - \section{The \textsf{defineJS} Environment}\label{defineJS} When you create a form element (button, text field, etc.), you @@ -3448,12 +3420,12 @@ console.println("Exiting the button area"); \AAMouseExit{\JS{\JSAAX}}} ]{myButton}{30bp}{15bp} \end{dCmd*} -\newtopic The code lines of \cs{JSAAE} and \cs{JSAAX} are so simple, \texttt{defineJS} environment +\newtopic The code lines of \cs{JSAAE} and \cs{JSAAX} are so simple, \env{defineJS} environment was really not needed. \newtopic See \Nameref{lengthyJS} for an additional example of the use of the \texttt{defineJS} environment. -The \pkg{insdljs} package defines two ``silent'' versions of \env{defineJS}, +The \pkg{insdljs} package defines two ``silent'' versions of \env{defineJS}, these are \env{@defineJS} and \env{defineJS*}. \settowidth{\aebdimen}{\ttfamily\string\begin\darg{@defineJS}[\ameta{chngCats}]\darg{\cs{\ameta{cmd}}}} \begin{dCmd}[commandchars=!()]{\aebdimen+2\fboxsep+2\fboxrule} @@ -3516,6 +3488,11 @@ stream; this keeps the declaration local. The \hyperlink{cmd}{\cs{cmd}} key is d \hyperref[supportedKVs]{Appendix~\ref*{supportedKVs}}, titled `\nameref{supportedKVs}', beginning on \pageref*{supportedKVs}; specifically, \cs{cmd} is listed in under the heading \textcolor{blue}{Specialized, non-PDF Spec commands}. +%http://www.acrotex.net/blog/?p=1442 + +\exAeBBlogPDF{p=1442} A comprehensive discussion of the features to the \env{defineJS} +environment is found in the article titled \href{\urlAcroTeXBlog/?p=1442}{\relax{\protect\pkg{insdljs}}: Exploring the {\protect\env{defineJS}} environment} from the {\AcroBlog} +website.\footnote{\url{http://www.acrotex.net/blog/?p=1442}} \newpage %\appendix @@ -3585,7 +3562,7 @@ FfMultiline? & For Multiline text field & text\\ FfPassword? & Password field & text \\ FfNoToggleToOff? & Used with Radio Buttons & Radio only\\ FfRadio? & Radio Button Flag & Radio if set\\ -FfPushButton? & Push Button Flag & Pushbutton\\ +FfPushButton? & Push Button Flag & Push button\\ FfCombo? & Combo Flag & choice\\ FfEdit? & Edit/NoEdit & combo\\ FfSort? & Sort List & choice\\ @@ -3636,6 +3613,15 @@ your system, you can use \emph{named colors} to specify color for the \end{Verbatim} then each of the following is valid: \verb!\textColor{myBlue}! (for specifying text color for text fields), \verb!\BG{myBlue}! (for specifying the background color of a field), \verb!\BC{myBlue}! (for specifying the border color of a field), and \verb!\Color{myBlue}! (for specifying the border color of a link). + +\paragraph*{Setting some defaults.} Before getting to the specification of +the key-values, there are two convenience commands for setting the default +text font and text size. These are +\cs{textFontDefault\darg{\ameta{font-spec}}} +(\cs{textFontDefault\darg{Helv}}) for setting the default text font and +\cs{textSizeDefault\darg{\ameta{size}}} (\cs{textSizeDefault\darg{9}}) for +setting the default text size. + \newpage \begingroup \setlength{\extrarowheight}{3mm}\setlength{\tabcolsep}{3pt} @@ -3697,53 +3683,53 @@ BC?& The boundary color, a list of 0 (transparent), 1 (gray), 3 (RGB) or 4 (CMYK &\verb+\BC{}+\newline(transparent)\\ BG?& Background color. Color specification same as \cs{BC}&\verb+\BG{}+\newline(transparent)\\ CA?& Button fields (push, check, radio) The widget's normal caption; e.g. \verb+\CA{Push}+, - in the case of a {\pb}. For check boxes and radio, the value of + in the case of a push button. For check boxes and radio, the value of \cs{CA} is a code that indicates whether a check, circle, square, star, etc. is used. These codes are introduced through \cs{symbolchoice}. Obeys \texttt{unicode} option.&\verb+\CA{}+\\ -RC?& Pushbutton fields only. The roll over text caption. Obeys \texttt{unicode} option.&\verb+\RC{}+\\ -AC?& Pushbutton fields only. The down button caption. Obeys \texttt{unicode} option.&\verb+\AC{}+\\ +RC?& Push button fields only. The roll over text caption. Obeys \texttt{unicode} option.&\verb+\RC{}+\\ +AC?& Push button fields only. The down button caption. Obeys \texttt{unicode} option.&\verb+\AC{}+\\ mkIns?& A variable for introducing into the \texttt{MK} dictionary any other key-value pairs not listed above. Principle examples are \texttt{I}, \texttt{RI}, \texttt{IX}, \texttt{IF}, \texttt{TP}, which are used for displaying icons on a button field. See an example in the demo file \textsf{eforms.tex} &\verb+\mkIns{}+\\ -I? & ({\pbs} only) an indirect reference to a form XObject defining the buttons's +I? & (push buttons only) an indirect reference to a form XObject defining the buttons's \emph{normal icon}&\verb+\I{nIcon}+\newline(example)\\ -RI? & ({\pbs} only) an indirect reference to a form XObject +RI? & (push buttons only) an indirect reference to a form XObject defining the buttons's \emph{rollover icon}&\verb+\RI{rIcon}+\newline(example)\\ -IX? & ({\pbs} only) an indirect reference to a form XObject +IX? & (push buttons only) an indirect reference to a form XObject defining the buttons's \emph{down icon}&\verb+\I{dIcon}+\newline(example)\\ -importIcons? & ({\pbs} only) a special key to signal that this button is the target +importIcons? & (push buttons only) a special key to signal that this button is the target of JavaScript that will supply the icons faces. Syntax: \cs{importIcons\darg{y|n}}&\verb|\importIcons{n}|\\ -TP? & \texttt{\darg{\ameta{\upshape{0|1|2|3|4|5|6}}}} ({\pbs} only; optional) +TP? &\hskip-2\tabcolsep \texttt{\darg{\ameta{\upshape{0|1|2|3|4|5|6}}}} (push buttons only; optional) A code indicating the \texttt{layout} of the text and icon; these codes are 0~(label only); 1~(icon only); 2~(label below icon); 3~(label above icon); 4~(label to the right of icon); 5~(label to the left of icon); 6~(label overlaid on the icon). The default is 0.&\verb+\TP{0}+\\ -SW? & \texttt{\darg{\ameta{\upshape{A|B|S|N}}}} ({\pbs} only; optional) The \emph{scale when key}. Permissible values are \texttt{A} (always scale), +SW? & \hskip-2\tabcolsep\texttt{\darg{\ameta{\upshape{A|B|S|N}}}} (push buttons only; optional) The \emph{scale when key}. Permissible values are \texttt{A} (always scale), \texttt{B} (scale when icon is too big), \texttt{S} (scale when icon is too small), \texttt{N} (never scale). The default is \texttt{A}. &\verb+\SW{A}+\\ -ST? & \texttt{\darg{\ameta{\upshape{A|P}}}} ({\pbs} only; optional) The \emph{scaling type.} Permissible values are \texttt{A} +ST? &\hskip-2\tabcolsep \texttt{\darg{\ameta{\upshape{A|P}}}} (push buttons only; optional) The \emph{scaling type.} Permissible values are \texttt{A} (anamorphic scaling); \texttt{P} (proportional scaling). The default is \texttt{P}. &\verb+\ST{P}+\\ -PA? & \texttt{\darg{\ameta{num\SUB1\space num\SUB2}}} ({\pbs} only; optional) The \textit{position array.} An array of two numbers, each +PA? &\hskip-2\tabcolsep \texttt{\darg{\ameta{num\SUB1\space num\SUB2}}} (push buttons only; optional) The \textit{position array.} An array of two numbers, each between 0 and 1 indicating the fraction of left-over space to allocate at the left and bottom of the annotation rectangle. The two numbers should be separated by a space. The default value, \verb!\PA{.5 .5}!, centers the icon in the rectangle. & \verb!\PA{.5 .5}!\\ -FB? & \texttt{\darg{true|false}} ({\pbs} only; optional) The \emph{fit bounds} Boolean. If \texttt{true}, the button appearance +FB? & \hskip-2\tabcolsep\texttt{\darg{true|false}} (push buttons only; optional) The \emph{fit bounds} Boolean. If \texttt{true}, the button appearance is scaled to fit fully within the bounds of the annotation without taking into consideration the line width of the border. &\verb+\FB{false}+\\\hline %-------------------------------------------------------------- %\pagebreak \multicolumn{3}{l}{\color{blue}Entries common to fields containing variable text:}\\ -Q? & \texttt{\darg{0|1|2|empty}} Quadding for text fields. Values are \texttt{0} (left-justified), +Q? & \hskip-2\tabcolsep\texttt{\darg{0|1|2|empty}} Quadding for text fields. Values are \texttt{0} (left-justified), \texttt{1} (centered), \texttt{2} (right-justified); e.g., \verb+\Q{1}+. &\verb+Q{}+\newline(left justified)\\ \pagebreak \multicolumn{3}{>{\small\bfseries}l}{Default Appearance (DA)}\\ DA? & Default appearance string of the text in the widget. Normally, you just specify text font, size and color. Can be redefined, advance techniques needed.&\\ -textFont? & \texttt{\darg{\ameta{font-spec}}} Font to be used to display the text &\verb+\textFont{Helv}+\\ -textSize? & \texttt{\darg{\ameta{num}}} The size in points of the text &\verb+\textSize{9}+\\ -textColor?& \texttt{\darg{\ameta{color-spec}}} The color of the text. +textFont? &\hskip-2\tabcolsep \texttt{\darg{\ameta{font-spec}}} Font to be used to display the text &\verb+\textFont{Helv}+\\ +textSize? &\hskip-2\tabcolsep \texttt{\darg{\ameta{num}}} The size in points of the text &\verb+\textSize{9}+\\ +textColor?&\hskip-2\tabcolsep \texttt{\darg{\ameta{color-spec}}} The color of the text. There are several color spaces, including grayscale and RGB; for example, \verb+\textColor{1 0 0 rg}+, gives a red font. Recent advances in parsing this command have eliminated the @@ -3753,9 +3739,9 @@ textColor?& \texttt{\darg{\ameta{color-spec}}} The color of the text. %------------------------------------------------------------------ %\pagebreak \multicolumn{3}{l}{\color{blue}Entries specific to text fields:}\\ -MaxLen? & \texttt{\darg{\ameta{num{\upshape|empty}}}} The maximum length of the text string input into a text field. +MaxLen? &\hskip-2\tabcolsep \texttt{\darg{\ameta{num{\upshape|empty}}}} The maximum length of the text string input into a text field. Used also with comb fields to set the number of combs. - Example, \verb+\MaxLeng{15}+.&\verb+\MaxLen{}+\\\hline + Example, \verb+\MaxLen{15}+.&\verb+\MaxLen{}+\\\hline %------------------------------------------------------------------ \multicolumn{3}{l}{\color{blue}Entries specific to signature fields:}\\ Lock? & This key is used to lock fields after the signature field is @@ -3764,46 +3750,60 @@ Lock? & This key is used to lock fields after the signature field is &\verb+\Lock{}+\\\hline %------------------------------------------------------------------- %\pagebreak +\multicolumn{3}{l}{\color{blue}Entries that change the width and height of a field:}\\ +rectW? & \hskip-2\tabcolsep \texttt{\darg{\ameta{length}}} Set the width of a field to \ameta{length}, + the height is not changed&\cs{rectW\darg{}}\\ +rectH? & \hskip-2\tabcolsep\texttt{\darg{\ameta{length}}} Set the height of a field to \ameta{length}, + the width is not changed&\cs{rectH\darg{}}\\ +width? & \hskip-2\tabcolsep\texttt{\darg{\ameta{length}}} Set the width to \ameta{length} and re-scale the height to keep the same + aspect ratio & \cs{width\darg{}}\\ +height? \hskip-2\tabcolsep& \texttt{\darg{\ameta{length}}} Set the height to \ameta{length} and re-scale the width to keep the same + aspect ratio & \cs{height\darg{}}\\ +scalefactor? & \hskip-2\tabcolsep\texttt{\darg{pos-num}} Re-scales both the width and height by a scale factor of + \ameta{pos-num} & \cs{scalefactor\darg{}}\\ + +%------------------------------------------------------------------- +%\pagebreak \multicolumn{3}{l}{\color{blue}Specialized, non-PDF Spec commands:}\\ -rawPDF? & \texttt{\darg{\ameta{PDF-KVPs}}} If all else fails, you can always introduce key-value pairs +rawPDF? &\hskip-2\tabcolsep \texttt{\darg{\ameta{PDF-KVPs}}} If all else fails, you can always introduce key-value pairs through this variable. &\verb+\rawPDF{}+\\ -autoCenter? &\texttt{\darg{y|n}} There is a centering code that attempts to give a pleasant +autoCenter? &\hskip-2\tabcolsep\texttt{\darg{y|n}} There is a centering code that attempts to give a pleasant placement of the field. \verb+\autoCenter{n}+ turn auto centering off.&\\ -inline? & \texttt{\darg{y|n}} If \mlcs{inline\darg{y}}, an alternate method is used +inline? &\hskip-2\tabcolsep \texttt{\darg{y|n}} If \mlcs{inline\darg{y}}, an alternate method is used get a better vertical positioning. Designed for inline form fields. The default is \mlcs{inline\darg{n}}.\\ -presets? & \texttt{\darg{\ameta{\cs{cmd}}}} This commands takes a macro as its argument, the text of the macro +presets? & \hskip-2\tabcolsep\texttt{\darg{\ameta{\cs{cmd}}}} This commands takes a macro as its argument, the text of the macro are key-value pairs. This is useful for setting up a series of presets for fields. Example, \verb|\presets{\myFavFive}|\\ -symbolchoice? & \texttt{\darg{\ameta{symbol-choice}}} Use this variable to specify what symbol is to be used +symbolchoice? & \hskip-2\tabcolsep\texttt{\darg{\ameta{symbol-choice}}} Use this variable to specify what symbol is to be used with a check box or radio button. Possible values are \texttt{check}, \texttt{circle}, \texttt{cross}, \texttt{diamond}, \texttt{square} and \texttt{star}. Can be used to globally change the symbol choice as well; for example, \verb+\symbolchoice{check}+, which is the default value.\\ -cmd? &\texttt{\darg{\ameta{cmd-args}}} Passes its argument into the key-value parsing stream, refer +cmd? &\hskip-2\tabcolsep\texttt{\darg{\ameta{cmd-args}}} Passes its argument into the key-value parsing stream, refer to page~\pageref{para:defineJSwArgs} for an example.\\ -linktxtcolor? & \texttt{\darg{\ameta{named-color{\upshape|empty}}}} The value of this variable is a named color and is the +linktxtcolor? & \hskip-2\tabcolsep\texttt{\darg{\ameta{named-color{\upshape|empty}}}} The value of this variable is a named color and is the color of the link text. Only recognized in link annotations. A value of \verb!\linktxtcolor{}! paints the text the \cs{normalcolor}.&\cs{linktxtcolor}\newline\verb+ {\@linkcolor}+\\\hline \multicolumn{3}{l}{\color{blue}Special link key-values used by \pkg{aeb\_mlink} and \pkg{annot\_pro}}\\ -mlstrut? & \texttt{\darg{\ameta{strut}}} Adjusts the height of a multi-line link, e.g., \verb!\mlstrut{\large\strut}! +mlstrut? & \hskip-2\tabcolsep\texttt{\darg{\ameta{strut}}} Adjusts the height of a multi-line link, e.g., \verb!\mlstrut{\large\strut}! &\verb~\mlstrut{\strut}~\\ -mlcrackat?& \texttt{\darg{\ameta{num{\upshape|empty}}}} Used to break a multi-line link across a page boundary; +mlcrackat?& \hskip-2\tabcolsep\texttt{\darg{\ameta{num{\upshape|empty}}}} Used to break a multi-line link across a page boundary; specifying \verb~\mlcrackat{3}~ breaks the link after the 3rd syllable. The \pkg{aeb\_mlink} package then creates two links consisting of the text up to and including the crack-at value and the second link consisting of the rest of the hypertext link (or url) string. &\verb~\mlcrackat{}~\\ -mlhyph? & \texttt{\darg{y|n}} A key that takes `y' or `n' as its value. If `y' is passed, then a hyphen is inserted after +mlhyph? & \hskip-2\tabcolsep\texttt{\darg{y|n}} A key that takes `y' or `n' as its value. If `y' is passed, then a hyphen is inserted after the break in a multi-line link that crosses a page boundary. & \cs{mlhyph\darg{n}}\\ -mlignore? &\texttt{\darg{\upshape0|1}} An internal switch used in building multi-line links and text markup annotations +mlignore? & \hskip-2\tabcolsep\texttt{\darg{\upshape0|1}} An internal switch used in building multi-line links and text markup annotations that cross page boundaries. \emph{Do not use}. &\cs{mlignore\darg{0}}\\ -mlcrackinsat? &\texttt{\cs{mlcrackinsat\darg{\ameta{latex-content}}}} This key inserts +mlcrackinsat? &\hskip-2\tabcolsep\texttt{\darg{\ameta{latex-content}}} This key inserts its argument after the hyphen (if there is one) at the point declared by the \cs{crackat} value. & \cs{mlcrackinsat\darg{}} \end{longtable} -- cgit v1.2.3