\documentclass{article}
\usepackage[fleqn]{amsmath}
\usepackage[
    web={centertitlepage,designv,forcolorpaper,tight*,latextoc,pro},
    eforms,aebxmp
]{aeb_pro}
\usepackage{forms16be}
%\usepackage{graphicx,array,fancyvrb}
%\usepackage{aeb_mlink}
%\usepackage{myriadpro}
%\usepackage{calibri}
\usepackage[altbullet]{lucidbry}

\def\hardspace{{\fontfamily{cmtt}\selectfont\symbol{32}}}

\usepackage{acroman}
\usepackage[active]{srcltx}

\urlstyle{tt}

\def\STRUT{\rule{0pt}{14pt}}

\makeatletter
\newcount\hesheCnt \hesheCnt=-1
\def\heshe{\@ifstar{\heshei}{\global\advance\hesheCnt1\relax\heshei}}
\def\heshei{\ifodd\hesheCnt she\else he\fi}
\def\HeShe{\@ifstar{\HeShei}{\global\advance\hesheCnt1\relax\HeShei}}
\def\HeShei{\ifodd\hesheCnt She\else He\fi}
\def\hisher{\@ifstar{\hisheri}{\global\advance\hesheCnt1\relax\hisheri}}
\def\hisheri{\ifodd\hesheCnt her\else his\fi}
\def\himher{\@ifstar{\himheri}{\global\advance\hesheCnt1\relax\himheri}}
\def\himheri{\ifodd\hesheCnt her\else him\fi}
\makeatother

\DeclareDocInfo
{
    university={\AcroTeX.Net},
    title={The \textsf{forms16be} Package},
    author={D. P. Story},
    email={dpstory@acrotex.net},
    subject=Documentation for the forms16be package,
    talksite={\url{www.acrotex.net}},
    version={1.3, 2019/03/20},
    Keywords={LaTeX, form fields, UTF-16BE, AcroTeX},
    copyrightStatus=True,
    copyrightNotice={Copyright (C) \the\year, D. P. Story},
    copyrightInfoURL={http://www.acrotex.net}
}

\universityLayout{fontsize=Large}
\titleLayout{fontsize=LARGE}
\authorLayout{fontsize=Large}
\tocLayout{fontsize=Large,color=aeb}
\sectionLayout{indent=-62.5pt,fontsize=large,color=aeb}
\subsectionLayout{indent=-31.25pt,color=aeb}
\subsubsectionLayout{indent=0pt,color=aeb}
\subsubDefaultDing{\texorpdfstring{$\bullet$}{\textrm\textbullet}}

\chngDocObjectTo{\newDO}{doc}
\begin{docassembly}
var titleOfManual="The forms16be Package";
var manualfilename="Manual_BG_Print_forms16be.pdf";
var manualtemplate="Manual_BG_Brown.pdf"; // Blue, Green, Brown
var _pathToBlank="C:/Users/Public/Documents/ManualBGs/"+manualtemplate;
var doc;
var buildIt=false;
if ( buildIt ) {
    console.println("Creating new " + manualfilename + " file.");
    doc = \appopenDoc({cPath: _pathToBlank, bHidden: true});
    var _path=this.path;
    var pos=_path.lastIndexOf("/");
    _path=_path.substring(0,pos)+"/"+manualfilename;
    \docSaveAs\newDO ({ cPath: _path });
    doc.closeDoc();
    doc = \appopenDoc({cPath: manualfilename, oDoc:this, bHidden: true});
    f=doc.getField("ManualTitle");
    f.value=titleOfManual;
    doc.flattenPages();
    \docSaveAs\newDO({ cPath: manualfilename });
    doc.closeDoc();
} else {
    console.println("Using the current "+manualfilename+" file.");
}
var _path=this.path;
var pos=_path.lastIndexOf("/");
_path=_path.substring(0,pos)+"/"+manualfilename;
\addWatermarkFromFile({
    bOnTop:false,
    bOnPrint:false,
    cDIPath:_path
});
\executeSave();
\end{docassembly}


\begin{document}

\maketitle

\selectColors{linkColor=black}
\tableofcontents
\selectColors{linkColor=webgreen}


\section{Introduction}

The \pkg{forms16be} package\footnote{The code in this package was extracted
from \pkg{aeb\_pro}. The code itself did not depend on PostScript, it is
useful, therefore, to remove it from \pkg{aeb\_pro} code base and make it
available to {\LaTeX} users with different workflows (\app{pdflatex},
\app{lualatex}, and \app{xelatex}).} provides support for UTF-16BE Unicode
character encoding (called a big-endian character string) for the \emph{text
string type} (PDF Reference, version 1.7, beginning on page 158). Text
strings are used in ``text annotations, bookmark names, article threads,
document information, and so forth'' (to partially quote page~158). The
particular application is to set property values of form fields, at least
those properties that take the text strings as its value. The package
contains support for Basic Latin plus the ability to enter any unicode
character using the notation \cs{uXXXX} or \cs{u(XXXX)}, where `\texttt{XXXX}' are four hex
digits.

The code was originally designed to be used with the \pkg{eforms} package,
but can be used with the form fields generated by \pkg{hyperref}, but
requires some custom modification of the form field commands of
\pkg{hyperref}.

\section{Using the package}

We use the example from \texttt{forms16be-ef.tex} to discuss how to use this package.

First define the unicode string to be used.
\bVerb\takeMeasure{\string\defUniStr\darg{\ameta{name}}\darg{\ameta{string}}}%
\setlength\aebscratch{\bxSize}%
\begin{dCmd}[commandchars=!()]{\bxSize}
\defUniStr{!ameta(name)}{!ameta(string)}
\end{dCmd}
\eVerb Define a unicode string with \cs{defUniStr}. The \ameta{name} is the
name of the unicode string you are defining, it is used later to refer to
this string. The \ameta{string} argument is a combination of Basic Latin
characters and unicode characters (more specifically, expressions of the form
\cs{uXXXX} or \cs{u(XXXX)}, where `\texttt{XXXX}' are hex digits). In the example below, we
declare,
\begin{Verbatim}[xleftmargin=\amtIndent,fontsize=\small]
\defUniStr{VDV}{\u03B1 cos(\u03B8)}
\defUniStr{TU}{Don \u\EURO Story "\u03B1 cos(\u03B8)"}
\end{Verbatim}
The definition file \texttt{uni4basic-latin.def} defines the encoding for the
Basic Latin character set plus a few more definitions, including \cs{EURO}.
See that file for more details.

\defUniStr{VDV}{\u03B1 cos(\u03B8)}%
\defUniStr{TU}{Don \u\EURO Story "\u03B1 cos(\u03B8)"}

After declaring and naming your unicode strings, use \cs{unicodeStr} to set the values
of selected field properties.
\bVerb\takeMeasure{\string\unicodeStr\darg{\ameta{name}}}%
\setlength\aebscratch{\bxSize}%
\begin{dCmd}[commandchars=!()]{\bxSize}
\unicodeStr{!ameta(name)}
\end{dCmd}
\eVerb \cs{unicodeStr\darg{\ameta{name}}} expands to the \ameta{string}
argument associated with \ameta{name}, as declared by the \cs{defUniStr}
command above. For example, \cs{unicodeStr(VDV)}, declared above, expands to
\begin{quote}\ttfamily
\unicodeStr(VDV)
\end{quote}
Notice the first four hex digits, `\texttt{FEFF}', these are `marker digits'.
As the PDF Specification describes, the markers are used to signal the
beginning of a big-endian hex string.

For \pkg{eforms}, incorporating these ideas into field creation is easy:
\begin{Verbatim}[xleftmargin=\amtIndent,fontsize=\small]
\textField[\TU{\unicodeStr(TU)}
  \DV{\unicodeStr(VDV)}\V{\unicodeStr(VDV)}]{tst16be}{1.5in}{11bp}
\end{Verbatim}
The result is \textField[\textSize{8}\TU{\unicodeStr(TU)}
  \DV{\unicodeStr(VDV)}\V{\unicodeStr(VDV)}]{tst16be}{1.5in}{11bp}\!\cgBdry. Pass your mouse over
  the field to see the tool tip as well.

Within the argument of \ameta{string}, backslash, left and right braces are
not defined in the \texttt{uni4basic-latin.def} file. They, therefore,
cannot appear as literals within \ameta{string}. Should you need these
characters, use the following:
\begin{itemize}
  \item \cs{u005C} or \cs{u\cs{BSLASH}} for backslash (\verb~\~).
  \item \cs{u007B} or \cs{u\cs{LBRACE}} for left brace (\texttt{\{});
  \item \cs{u007D} or \cs{u\cs{RBRACE}} for right brace (\texttt{\}});
\end{itemize}
(Other definitions within the \texttt{uni4basic-latin.def} file are
\cs{EURO} and \cs{DQUOTE}.) The introduction of the command versions of
unicode brings up another problem, that of obeying spaces.

Suppose you wanted to initialize a field property with `\cs{LaTeX}'. To obtain
this value we would type `\cs{u\string\BSLASH\space LaTeX}'. But, because \ameta{string} is under the
influence of \cs{obeyspaces}, the specified initialization appears as `\texttt{\string\ LaTeX}', that is,
there is a space that follows the backslash; of course, we cannot specify \cs{u\string\BSLASHLaTeX} as that would
get an undefined command error. The solution is to enclose \cs{BSLASH} in parentheses; if we type
\cs{u(\string\BSLASH)LaTeX} we obtain the desired result:
\begin{Verbatim}[xleftmargin=\amtIndent,fontsize=\small]
\defUniStr{LaTeX}{\u(\BSLASH)LaTeX}
\textField[\V{\unicodeStr(LaTeX)}
  \DV{\unicodeStr(LaTeX)}]{tstLaTeX}{1in}{11bp}
\end{Verbatim}
The above code results in
\defUniStr{LaTeX}{\u(\BSLASH)LaTeX}\textField[\V{\unicodeStr(LaTeX)}\DV{\unicodeStr(LaTeX)}]{tstLaTeX}{1in}{11bp}\cgBdry\!.

\section{List of field properties that take a text string}

The property entries in a form field that support the text string type are
\psf{DV}, \psf{V}, \psf{TU}, \psf{CA}, \psf{RC}, and \psf{AC}. The
\pkg{eforms} key counterparts are \cs{DV}, \cs{V}, \cs{TU}, \cs{CA}, \cs{RC},
and \cs{AC}. When the argument of any of these begins with \cs{unicodeStr},
\pkg{eforms} detects this and passes its argument to the unicode keys
\cs{uDV}, \cs{uV}, \cs{uTU}, \cs{uCA}, \cs{uRC}, and \cs{uAC}. Normally, the
value of \psf{DV}, for example, is \texttt{DV\,(\ameta{text})}, its value is
enclosed in parentheses; when the value consists of hex digits, angle
brackets are required, like so \texttt{DV\,<\ameta{string}>}.

If you enter raw big-endian hex digits, use the special \cs{u\ameta{cmd}} version of the keys, for example,
\begin{Verbatim}[xleftmargin=\amtIndent,fontsize=\small]
\pushButton[\CA{\unicodeStr(263A263C)}]{btn}{.5in}{11bp}
\pushButton[\uCA{FEFF263A263C}]{btn}{.5in}{11bp}
\end{Verbatim}
expands to \pushButton[\CA{\unicodeStr(263A263C)}]{btn}{.5in}{11bp} or
\pushButton[\uCA{FEFF263A263C}]{btn}{.5in}{11bp}\!\cgBdry. The first version
uses \cs{unicodeStr} with raw hex digits, because \cs{unicodeStr} is used,
the unicode is detected and \cs{uCA} is used (with angle brackets). In the
second example, \cs{unicodeStr} is not used, so \cs{uCA} must be explicitly
used; also, the unicode marker \texttt{FEFF} must explicitly appear as well.
(\cs{unicodeStr} automatically inserts the marker.) The results of the markup
forms is the same.

\section{Fonts}

When using unicode to reference glyphs, such as the dings presented above, it
is important that the fonts the PDF viewer uses contains the glyphs. If the
glyph does not exist in the font, the viewer might be successful at
substituting the font. The viewer is not always successful. For example,
\begin{Verbatim}[xleftmargin=\amtIndent,fontsize=\small]
\defUniStr{subS}{x\u209B}
\textField[\V{\unicodeStr(subS)}
  \DV{\unicodeStr(subS)}]{tstsubS}{.5in}{11bp}
\end{Verbatim}
The result is
\defUniStr{subS}{x\u209B}\textField[\V{\unicodeStr(subS)}\DV{\unicodeStr(subS)}]{tstsubS}{.5in}{11bp}\!\cgBdry,
the default value of this field should be $x_S$, is it so? The default font
is \texttt{Helv}. Now, if we change to the \texttt{TiRo} font, we obtain
\textField[\textFont{TiRo}\V{\unicodeStr(subS)}\DV{\unicodeStr(subS)}]{tstsubS}{.5in}{11bp}\!\cgBdry.
A better result! The (newer) \cs{u209B} glyph is not supported for all fonts.
Generally, you'll have to find a font that works and is available to the end
user as well.

\section{A combobox example}

For combo boxes and list boxes, things are slightly more
complicated. In the example below, we define a combo box. First,
define the appearance values of the combo box (the string that is
seen listed in the combo box).
\begin{Verbatim}[xleftmargin=\amtIndent,fontsize=\small]
\defUniStr{myEuro}{\u20AC (Euro)}
\defUniStr{myYen}{\u00A5 (Yen)}
\defUniStr{mySheqel}{\u20AA (Sheqel)}
\defUniStr{myPound}{\u00A3 (Pound)}
\defUniStr{myFranc}{\u20A3 (Franc)}
\end{Verbatim}

\defUniStr{myEuro}{\u20AC (Euro)}
\defUniStr{myYen}{\u00A5 (Yen)}
\defUniStr{mySheqel}{\u20AA (Sheqel)}
\defUniStr{myPound}{\u00A3 (Pound)}
\defUniStr{myFranc}{\u20A3 (Franc)}

Then we can define our combo box.  According to the PDF file format,
unicode strings should be enclosed in angle brackets
\verb!<XXXXXXXXXXXX>!. In initializing the combo box below, the
\cs{unicodeStr} command is used, but this time it is enclosed in
angle brackets. (That is all the ``u'' versions of the keys do above
is to automatically insert the angle brackets for you. Here we have
to do it ourselves. (I suppose one could have a helper command, but
you can handle it.)
\begin{Verbatim}[xleftmargin=\amtIndent,fontsize=\small]
\comboBox[\Ff\FfEdit\DV{Euro}\V{Euro}\textFont{Arial}
\BG{0.98 0.92 0.73}\BC{0 .6 0}]{myCombo}{1in}{11bp}
{*{[(Euro)<\unicodeStr(myEuro)>]%
    [(Yen)<\unicodeStr(myYen)>]%
    [(Sheqel)<\unicodeStr(mySheqel)>]%
    [(Pound)<\unicodeStr(myPound)>]%
    [(Franc)<\unicodeStr(myFranc)>]}
}
\end{Verbatim}
where the \texttt{*} in the position shown above is a token that signals the
passing of a raw form of the value options of a combo or list box; it is
defined in \pkg{eforms}.

\newtopic\noindent
The result is
\comboBox[\Ff\FfEdit\DV{Euro}\V{Euro}\textFont{Arial}
\BG{0.98 0.92 0.73}\BC{0 .6 0}]{myCombo}{1in}{11bp}
{*{[(Euro)<\unicodeStr(myEuro)>]%
    [(Yen)<\unicodeStr(myYen)>]%
    [(Sheqel)<\unicodeStr(mySheqel)>]%
    [(Pound)<\unicodeStr(myPound)>]%
    [(Franc)<\unicodeStr(myFranc)>]}
}\!\cgBdry. Very swave!


\section{Demonstration files}

There are three sample files:
\begin{itemize}
\item \texttt{forms16be-ef.tex} uses the \pkg{eforms} package to create
    form fields and demonstrate how to initialize form fields using
    unicode.
\item \texttt{forms16be-hy.tex} uses form fields created by \pkg{hyperref}.
    \pkg{hyperref} does not support initializing the value of a field, for
    example, with big-endian, so a redefinition is needed.
\item \texttt{forms16be-ap.tex} demonstrates the \pkg{forms16be} with
    \pkg{aeb\_pro} (\app{dvips}/\app{Distiller} workflow required). For consistency with previously
    documented behavior of \pkg{aeb\_pro}, the \opt{linktoattachments} option is used to import \pkg{forms16be}.
    It is not necessary, however, to use \opt{linktoattachments}.
\end{itemize}

\section{My retirement}

Now, I simply must get back to it. \dps

\end{document}
