%
% http://www.adobe.com/devnet/acrobat/pdfs/PDF32000_2008.pdf
%
% makeindex < aebpro_man.idx > aebpro_man.ind
\documentclass[12pt]{article}
\usepackage[fleqn]{amsmath}
\usepackage[
    web={centertitlepage,designv,tight*,
        forcolorpaper,latextoc,extended},
        aebxmp,eforms,graphicxsp={showembeds}
]{aeb_pro}
\usepackage{array}
\usepackage{aeb_mlink}
%\usepackage{myriadpro} %[usecmtt]
\usepackage[altbullet]{lucidbry}
\usepackage{annot_pro}
\usepackage{richtext}

\DeclareInitView
{%
    layoutmag={mag=100},
%    windowoptions={fit}
}

%\useAAXdimtrue

\usepackage{makeidx}
\makeindex
\usepackage{acroman}

\usepackage[active]{srcltx}

\def\expath{../examples}

\urlstyle{rm}
\def\pkg{\textsf}
\let\app\textsf
\let\opt\texttt
\let\uif\textsf
\let\env\texttt
\def\meta#1{\textit{\texttt{#1}}}
\def\ameta#1{$\langle\textit{\texttt{#1}}\rangle$}
\newdimen\aebdimen \aebdimen6pt %\partopsep \advance\aebdimen\partopsep
\newcommand\bVerb[1][]{\begingroup#1\vskip\aebdimen\parindent0pt}%
\def\eVerb{\vskip\aebdimen\endgroup\noindent}
\def\SUB#1{\ensuremath{{}_{\text{#1}}}}

\def\darg#1{\texttt{\{#1\}}}
\def\takeMeasure{\bgroup\obeyspaces\takeMeasurei}
\def\takeMeasurei#1{\global\setbox\webtempboxi\hbox{\ttfamily#1}\egroup}
\def\bxSize{\wd\webtempboxi+2\fboxsep+2\fboxrule}
\let\amtIndent\leftmargini

%\def\tutpath{doc/tutorial}
%\def\tutpathi{tutorial}

\DeclareDocInfo
{
    university={\AcroTeX.Net},
    title={The \texorpdfstring{\textsf{annot\_pro} Package\\[1em]}{annot\textunderscore pro Package: }
        Text, Stamp, File Attachment, and Text Box Annotations},
    author={D. P. Story},
    email={dpstory@acrotex.net},
    subject={Documentation for annot\textunderscore pro from AcroTeX},
    talksite={\url{www.acrotex.net}},
    version={1.1b, 2016/10/18},
    keywords={sticky notes, stamps, file attachment text box, free text, annotations},
    copyrightStatus=True,
    copyrightNotice={Copyright (C) \the\year, D. P. Story},
    copyrightInfoURL={http://www.acrotex.net}
}

\def\dps{$\hbox{$\mathfrak D$\kern-.3em\hbox{$\mathfrak P$}%
   \kern-.6em \hbox{$\mathcal S$}}$}

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

\embedEPS[hiresbb,transparencyGroup]{AdobeDon}{../examples/graphics/AdobeDon}

\makeStamp{0.0 0.0 20.0 20.0}{AdobeDon}{%
    [ 20 \widthOf{AdobeDon} div 20 \widthOf{AdobeDon} div scale {AdobeDon} /SP pdfmark
}

\makeatletter
\def\setDisplayNumber#1#2{\kern0pt
    \setlength\abovedisplayshortskip{0pt}%
    \setlength\belowdisplayshortskip{0pt}%
    \setlength\abovedisplayskip{0pt}%
    \setlength\belowdisplayskip{0pt}%
    \begin{equation}\label{#2}\end{equation}\kern0pt
}
\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}
\renewcommand*\descriptionlabel[1]{\hspace\labelsep
    \normalfont #1}
\setcounter{secnumdepth}{4}
\setcounter{tocdepth}{5}
\renewcommand*{\theparagraph}{\texorpdfstring{\protect\P\protect\ }{\textparagraph}}
\renewcommand{\paragraph}
    {\renewcommand{\@seccntformat}[1]{\theparagraph}%
    \@startsection{paragraph}{4}{0pt}{6pt}{-3pt}{\color{\aeb@subsubsectioncolor}\bfseries}}
\renewcommand*\l@paragraph{\@dottedtocline{4}{5.0em}{1em}} %{7.0em}{4.1em}}
\def\chgCurrLblName#1{\def\@currentlabelname{#1}}
\def\echgCurrLblName#1{\edef\@currentlabelname{#1}}
\makeatother


\setAnnotOptions{subject={AcroTeX Communiqu\'e},title={D.P. Story}}

%\pagestyle{empty}
%\parindent0pt\parskip\medskipamount

\chngDocObjectTo{\newDO}{doc}
\begin{docassembly}
var titleOfManual="The annot_pro MANUAL";
var manualfilename="Manual_BG_Print_annotpro.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}

This package is used to create text, stamp, and file attachment
annotations using \textbf{Adobe Distiller}, these annotations can be
viewed in Adobe Reader. For users of \textsf{pdf(la)tex}, use the
\textsf{pdfcomment} package by Josef Kleber.\footnote{Available at \href{http://ctan.org/pkg/pdfcomment}{ctan.org/pkg/pdfcomment}}

The package primarily in support of my \href{http://www.math.uakron.edu/~dpstory}
{{Acro\negthinspace\TeX} PDF Blog}. I plan to use sticky notes, file attachments, and
custom stamps to make side-comments, and to provide source files.

\section{Requirements}

The requirements for your {\LaTeX} system, and well as any other
software, is highlighted in this section.

\subsection{{\LaTeX} Package Requirements}

The following packages, in addition to the standard {\LaTeX}
distribution, are required:
\begin{enumerate}
  \item The \textsf{xkeyval} package is used to set up the key-value
      pairs of the \cs{annot\-pro} command. Get a recent version.
  \item The \textsf{xcolor} package is strongly recommended.
  \item The \textsf{hyperref} package, a recent version.
  \item If you want to create custom stamps (on the fly) using the techniques
      developed for that purpose, the \textsf{graphicxsp} Package is required.\footnote
      {Available at \href{http://ctan.org/pkg/graphicxsp}{ctan.org/pkg/graphicxsp}}
\end{enumerate}
The \textsf{annot\_pro} package is part of the \textcolor{blue}{AeB
Pro} family, which means \textbf{Adobe Distiller} is required. The
components of \textcolor{blue}{AeB} and \textcolor{blue}{AeB Pro}
are not required.\footnote{AeB: \href{http://ctan.org/pkg/acrotex}{ctan.org/pkg/acrotex}}${}^{,}$\footnote{AeB Pro:
\href{http://ctan.org/pkg/aeb-pro}{ctan.org/pkg/aeb-pro}}

\subsection{PDF Creator Requirements}

The \textsf{annot\_pro} package requires \textbf{Acrobat Distiller 5.0} (or
later) as the PDF creator. The document author typically uses dvips (or dvipsone) to
produce a PostScript file, which is then distilled to obtain a PDF.

If you wish to use (dynamically) created stamps that have opacity less than 1,
you need to distill using \textbf{Standard\_transparancy.joboptions} with distiller,
in this case, \textbf{Acrobat Distiller 6.0} (or later) is required; otherwise, this
distiller job options file is not needed.

The \textbf{Standard\_transparancy.joboptions} file is supplied with the \textsf{graphicxsp}
package; the documentation of the \textsf{graphicxsp} package includes installation instructions.

\section{Installation}

The installation is simple enough. Unzip \texttt{annot\_pro.zip} in a
folder that is on your {\LaTeX} search path.  Refresh your filename
database, if appropriate.

\begin{defineJS}{\winedtDist}
Run(|"c:\\Program Files\\Adobe\\Acrobat 9.0\\Acrobat\\acrodist.exe" -F "%P\\%N.ps"|,'%P',0,0,'%N.ps - Distiller',1,1);
\end{defineJS}

\paragraph*{\textcolor{red}{Important:}} When creating a file attachment annotation,
you must specify a path to the file to be attached, and distiller must embed
this file.  In recent versions of Acrobat,
security restrictions have been put in place to prevent
\textbf{Distiller} from reading files (the PostScript \textbf{file}
operator does not work). Fortunately, Distiller has a switch that
turns off this particular restriction. To successfully use this
package, therefore, you need to run Distiller by using the
\texttt{-F} command line switch.


Those using \app{Windows OS} can create a shortcut on the desktop, for example,
that starts \app{Distiller} with the \texttt{-F} switch. The \uif{Target} of the shortcut might read
\begin{Verbatim}[xleftmargin=\leftmargini,fontsize=\small]
"C:\Program Files (x86)\Adobe\
    Acrobat 9.0\Acrobat\acrodist.exe" -F
\end{Verbatim}
where we have wrapped the path to the next line to fit within the margins.
Once \app{Distiller} is started with \texttt{-F}, the switch remains in effect
until \app{Distiller} is closed.

If this package is used to create file attachment annotations without the
\texttt{-F} switch, you typically get the following error message in
the Distiller log file
\begin{Verbatim}[xleftmargin=\leftmargini,fontsize=\small]
%%[ Error: undefinedfilename; OffendingCommand: file ]%%
\end{Verbatim}
This tells you that either you have not started Distiller with the
\texttt{-F} command line switch, or Distiller can't find one of the
files that the \textbf{file} operator was trying to read.



\newtopic \textbf{Mac OS Users.} The above comments on the \texttt{-F} command line switch
is for Windows users, Mac OS users must choose the \texttt{AllowPSFileOps} user preference, this is located
in the \texttt{plist}, possibly located at
\begin{Verbatim}[fontsize=\small]
/Users/[User]/Library/Preferences/com.adobe.distiller9.plist
\end{Verbatim}
You can also use Spotlight, the search utility on Mac, to search for the string \texttt{com.adobe.distiller};
the result might be
\begin{quote}
\texttt{com.adobe.distiller9.plist}.\footnote{In the case of Adobe Distiller, version 9.0}
\end{quote}
Clicking on this find,
Spotlight opens \texttt{com.adobe.distiller9.plist} in the \texttt{plist} editor, see \hyperref[plist]{Figure~\ref*{plist}}.
If necessary, click on the arrow next to the Root to expand the
choices, then click the up and down arrows at the far
right in the \texttt{AllowPSFileOps} row to select Yes as the value.
\begin{figure}[hbt]\setlength{\fboxsep}{0pt}
\begin{center}
\fbox{\includegraphics[width=.75\linewidth]{plistEditor}}
\caption{com.adobe.distiller9.plist}\label{plist}
\end{center}
\end{figure}

\section{The \texorpdfstring{\protect\cs{annotpro}}{\CMD{annotpro}} Command}

The main command of this package is \Com{annotpro}; the command is controlled by
its optional parameters. The same command can create a text annotation (sticky note),
a stamp annotation, a file attachment or a Free Text (Text Box) annotation. The syntax of this command is
\bVerb\takeMeasure{\string\annotpro[\ameta{KV-pairs}]\darg{\ameta{text}}}%
\begin{minipage}{\linewidth}
\begin{minipage}{\bxSize}
\xdef\panelWidth{\the\linewidth}%
\begin{Verbatim}[frame=single,commandchars=!()]
\annotpro[!ameta(KV-pairs)]{!ameta(text)}
\end{Verbatim}
\end{minipage}\hfill
\begin{minipage}{\linewidth-\panelWidth}
\setDisplayNumber\label{display:arbproCmd}
\end{minipage}\end{minipage}\eVerb
\PD The optional argument is one or more key-value pairs that describe the
annotation; the required argument, \ameta{text}, is the ``contents'' of the
annotation; for the text and stamp annotation, \ameta{text} becomes the
contents of the popup annotation, for a file attachment annotation, which has
not associated pop-up, it is the description of the file attachment that
appears in the file attachment panel of Adobe Reader. In the latter case, the
value of \ameta{text} should be rather short. The key-value pairs (\ameta{KV-pairs}) are
described over the next few sections.

\paragraph*{\color{red}Sample files.} The sample files \texttt{annots.tex} and \texttt{textbox.tex} illustrate the features
of the \pkg{annotpro} package.

\subsection{Key-values common to all annotations}\label{s:CommonKeys}

The following are key-value pairs common to all annotations.

\begin{itemize}
  \item \texttt{type=\ameta{\upshape{text|stamp|fileattachment|textbox}}} The \texttt{type} key determines the type of annotation to be produced;
        permissible values are \texttt{text}, \texttt{stamp}, and \texttt{fileattachment}. This
        key is optional, if not present, \texttt{type=text} is assumed.
  \item \texttt{name=\ameta{name}} The name of the icon to use for the declared \texttt{type}. Permissible
        values are dependent on the \texttt{type}, and are discussed in subsequent sections.
  \item \texttt{title=\ameta{text}} Text to be displayed in the title bar of the annotation's pop-up window
        when open and active. By convention, this entry identifies the user who made the annotation,
        though any (short) text may be used. You can use \cs{setAnnotOptions} to globally set
        the title of each annotation, perhaps using your name.
\begin{Verbatim}[fontsize=\small]
    \setAnnotOptions{title={D. P. Story}}
\end{Verbatim}
  \item \texttt{subject=\ameta{text}} Text representing a short description of the subject of the annotation.
    You can use \cs{setAnnotOptions} to globally set the subject of each annotation,
\begin{Verbatim}[fontsize=\small]
    \setAnnotOptions{title={D. P. Story},
        subject={AcroTeX Communiqu\'e}}
\end{Verbatim}
  \item \texttt{color}: The color of the title bar of the pop-up window of the annotation.
  \item \texttt{readonly=\ameta{\upshape{true|false}}} Set the annotation to readonly. The user can click on the annot to
    see the popup, but the user, if using Acrobat, cannot move the annotation around on the page.
    The popup window can still be move by the user. (This property makes no difference to the
    user of Adobe Reader.)
  \item \texttt{opacity=\ameta{dec}}: The opacity value ($
          \text0\le\text{\ameta{dec}}\le\text1$) to be used in painting the (icon of
          the) annotation, but does apply to the pop-up window. The default
          is 1.0.
  \item[] Adobe Distiller handles the opacity for us in all cases except when we create a (dynamic) stamp.
        If an opacity value less than 1 is desired, special techniques are needed, and the file needs to
        be distilled using the \textbf{Standard\_tranparency} job options.

\end{itemize}
The following key-values are {\LaTeX} based concerning placement of the annotation in the margin.
\begin{itemize}
  \item \texttt{margin}: Use this key (it has no value), to declare that you want the annotation
        to appear in the margin. The \cs{marginpar} command from core {\LaTeX} is used, the placement
        of the annotation follows the rules set down by {\LaTeX}.  You can reverse the placement of the
        annotation by using the {\LaTeX} command \cs{reversemarginpar} (annots placed in the right margin, and now placed in the left);
        you can return to the default by using \cs{normalmarginpar}.

  \item[] Given that you have use the \texttt{margin} key, there is an associated key that can be used, as well
          as a command.
  \begin{itemize}
        \item \texttt{margintext}: The value of this key is text that will be typeset just below the annotation icon.
        \item \cs{marginpartextformat}: A {\LaTeX} command for
                formatting the text in the margin, the default definition is\smallskip
\begin{Verbatim}
\margintextformat{\bfseries\tiny\color{blue}}
\end{Verbatim}
    \end{itemize}
    \item[] For an annotation placed in the margin with margin text, you might want to use the \texttt{readonly}
        key, this prevents the user---even one using Acrobat---from moving the annotation away from its caption.
\end{itemize}
The following key-value is for your convenience.
\begin{itemize}
  \item \texttt{presets}: A key to allow the introduction of pre-defined options, for example,
    you might like all your comment annotations to be red, so you can define
\begin{verbatim}
   \def\myComments{type=text,name=Comment,color=red}
\end{verbatim}
then say
\begin{verbatim}
   \annotpro[presets=\myComment]{Way to go!}
\end{verbatim}
Additional options may be included,
\begin{verbatim}
   \annotpro[presets=\myComment,margin]{Way to go!}
\end{verbatim}
for example.

\end{itemize}

\subsection{Key-values for text annotations}

The position of the annotation is determined by its bounding rectangle; for the
text annotation, an icon is placed so that its upper left corner is at the upper
left corner of the bounding rectangle. The icons themselves have certain dimensions
that have been recorded within the \texttt{annot\_pro} package, so you need not worry
about leaving space for them.

An important fact about the icons used by text annotation is that they \emph{do not zoom in or out} as the page
magnification is changed; furthermore, the graphics commands \cs{scalebox} and \cs{resizebox} do not rescale
the icons as expected.

The following are options specific to the text annotation. Recall, the text annotation
is of \texttt{type=text}.
\begin{itemize}
    \item \texttt{name}: The name of the icon to use when displaying this annotation in closed form (no pop-up window visible).
    Possible values---as specified in the \textsl{PDF Reference}---are
    \texttt{Comment}, \texttt{Key}, \texttt{Note}, \texttt{Help},
    \texttt{NewParagraph}, \texttt{Paragraph}, and \texttt{Insert}.
    Additional icons that are available in recent versions of Adobe
    Reader are
\begin{quote}\raggedright
    \texttt{Check}, \texttt{Circle}, \texttt{Cross}, \texttt{Star}, \texttt{RightArrow}, \texttt{RightPointer},
    \texttt{UpArrow}, \texttt{UpLeftArrow}
\end{quote}
        If you are using comments in your document, and your audience have
        older versions of Adobe Reader, it is best to use only the seven
        listed in the \textsl{PDF Reference}.

    \item \texttt{open}: A Boolean value that determines whether the pop-up
        window is open or not. When \texttt{true} the pop-up is open. The
        package default is \texttt{false}. You can use \cs{setAnnotOptions}
        to set this option globally.

    \item \texttt{nohspace}, \texttt{novspace}, \texttt{nospace}: The
        presence of these commands zeroes out the dimension(s) of the
        bounding rectangle. Specifying \texttt{nohspace} as an option
        causes the icon to take up no horizontal space as the page is
        latexed. Here\annotpro[nohspace]{This a sticky note with the
        nospace option} is an example of a sticky note with the
        \texttt{nohspace} option. Without any of these three keys, the text
        annotation \annotpro[type=text,name=Key]{A sticky note that takes
        up TeX space. If you put the document into 100\% magnification,
        you'll see the note fits precisely into the allotted space.} fits
        exactly into the allotted space at
        \setLinkText[\A{\JS{this.zoom=100;}}\Color{0 .6 0}]{100\%
        magnification}, try it.

    When the icon takes up no {\TeX} space, it may cover content on
        the page, as it does above. Acrobat users can move the icon
        around, but AR users cannot move the icon. The pop-up window is
        movable and scalable, but the icon cannot be moved. Therefore,
        you must be careful about placement.

    Additional positioning of the icons can be made using standard {\LaTeX}
    commands such as \cs{raisebox} and \cs{smash}. For example,\smash{\raisebox{1in}{\annotpro[nospace,color=blue,opacity=.25]{I've raised this annot by 1in.
    I've also used the nospace key, the icon does not take up any TeX space.}}} the blue icon above was created by
\begin{Verbatim}[fontsize=\footnotesize]
    For example,\smash{\raisebox{1in}\raisebox{1in}{%
        \annotpro[nospace,color=blue,
            opacity=.25]{...clever message...}}}
\end{Verbatim}
Note that I've set the \texttt{opacity} to .25.

\end{itemize}


\subsection{Key-values for stamp annotations}

A stamp annotation is similar to a text annotation in the sense that
it has a pop-up window in which the contents of the message is
displayed; however, unlike the text annotation icons, the stamp
appearance by be re-scaled using \cs{scalebox} and \cs{resizebox} of
the graphics package; however, the keys \texttt{scale},
\texttt{widthTo}, and \texttt{heightTo}, as described below, are the
recommended methods of re-scaling a stamp.

The following are the key-values associated with this annotation type.

\begin{itemize}

\begingroup\raggedright

    \item \texttt{name}: The stamps listed in the \textsl{PDF
    Reference} are \texttt{Approved}, \texttt{AsIs},
    \texttt{Confidential}, \texttt{Departmental}, \texttt{Draft},
    \texttt{Experimental}, \texttt{Expired}, \texttt{Final},
    \texttt{ForComment}, \texttt{ForPublicRelease},
    \texttt{NotApproved}, \texttt{NotForPublicRelease},
    \texttt{Sold}, and \texttt{TopSecret}. If \texttt{name}
    is not specified, \texttt{Draft} is the default.\par\endgroup

    \item[] There are other stamps, not listed in the \textsl{PDF
    Reference}, but available in more recent versions of Acrobat.
    The file \texttt{stamps.pdf} lists all the stamps that I have
    access to. The names of these other stamps are recognized by the
    \texttt{name} key.

    \item[] The dimensions of the stamps listed above are all the
    same, they are \texttt{150bp} width and \texttt{40bp} high.

    \item[] Additional stamps are shipped by Acrobat, a listing of these
    appears in the file \texttt{stamps.pdf} (\texttt{stamps.tex}).

    \item\texttt{width}, \texttt{height}: If the value of
    \texttt{name} key is something other than one of the stamps
    listed above (one of the stamps listed in the file
    \texttt{stamps.pdf}), the width and height are not known to
    \textsf{annot\_pro}. In this case, use the \texttt{height} and \texttt{width} keys
    to set the dimensions of the bounding box. Adobe Distiller will
    resize the stamp to the stamp is the largest one that can fit in
    the bounding box, the stamp will be centered vertically and
    horizontally within the bounding box.

    \item[] Here are a couple of examples, the bounding box is should as a black \cs{fbox}.

\begin{itemize}

\previewtrue

        \item This one \annotpro[type=stamp,name=SBApproved,widthTo=106bp,color=webbrown]{This package just got better!}
        fits more or less exactly.  I determined the dimensions of this stamp through some controls of the user interface.
        Contrast this this stamp
        \annotpro[type=stamp,width=50bp,height=50bp,name=SBApproved,color=webbrown]{This package just got better!}
        obtained by setting \texttt{width=50bp} and \texttt{height=50bp}. Notice the ``best fit,'' and that the bounding
        box takes up space. We can use \cs{smash} to smash its vertical height, let's see how that looks,
        \smash{\annotpro[type=stamp,width=50bp,height=50bp,name=SBApproved,color=webbrown]{This package just got better!}}

\smallskip

\begin{defineJS}{\annotstampi}
Exact fit:
\\annotpro[type=stamp,name=SBApproved,color=webbrown]{This package just got better!}
\end{defineJS}
\begin{defineJS}{\annotstampii}
Bad rectangle, but stamp fits the best it can:
\\annotpro[type=stamp,name=SBApproved,color=webbrown]{This package just got better!}
\end{defineJS}

\previewfalse

        \item[] The code for producing these stamps are given in the margins.
        \annotpro[margin,readonly,margintext={\centering Good Fit}]{\annotstampi}%
        \annotpro[margin,readonly,margintext={\centering Bad Fit}]{\annotstampii}%

\begin{defineJS}{\annotstampiii}
Resize using \\resizebox. \\raisebox was used to lift the same up a little:
\\raisebox{4pt}{\\resizebox{.5in}{!}{\\annotpro[type=stamp,name=SBApproved,color=webbrown]{This package just got better!}}}
\end{defineJS}

    \item[] You can resize these stamps using \cs{scalebox} and \cs{resizebox}, like so.
    \raisebox{4pt}{\resizebox{.5in}{!}{\annotpro[type=stamp,name=SBApproved,color=webbrown]{This package just got better!}}}
    \enspace The code for producing this stamp are given here \annotpro{\annotstampiii}.

\begin{defineJS}{\annotstampiv}
\smash{\makebox[0pt][l]{\annotpro[type=stamp,name=Approved,color=blue]{I give my stamp of approval!}}}
\end{defineJS}

\item To create a stamp\smash{\makebox[0pt][l]{\annotpro[type=stamp,name=Approved,color=blue]{I give my stamp of approval!}}} that takes up no space, it is easiest to use \cs{smash} and \verb!\makebox[0pt][l]{text}!;
    here is one of the standard stamps as listed in the \textsl{PDF Reference}. The code for this stamp is given
    in this note \annotpro{\annotstampiv}.
\end{itemize}

\item[] Try changing the magnification of the page, you'll see that stamps are re-scaled as you zoom in or out, while
the text annotations are not. I don't like text annotations for this reason.

\begin{defineJS}{\annotstampv}
\\annotpro[type=stamp,customStamp=MyDPSImage,ap=AdobeDon,color=webbrown]{This is the best picture of me ever taken. Akron, about 2005.}
\end{defineJS}

\item\texttt{rotate}: Stamps can be rotated, use this key to enter an angle of rotation, for example,
    \texttt{rotate=30} rotates the stamp $\text{30}^\circ$ counter clock-wise.

\item[\textcolor{red}{\ding{043}}] Do not use the \cs{rotatebox} command of \textsf{graphics} package,
this command \emph{does not rotate} the stamp.

\item \texttt{scale}: Use this key to re-scale the stamp; the value of this key is a number between
    0 and 1. For example, \texttt{scale=.5} reduces both width and height in half.
\item \texttt{widthTo}: This key resizes the stamp so that the width is the value of this key; for example,
    \texttt{widthTo=2in} re-scales the stamp to have a 2in width.
\item\texttt{heightTo}: This key resizes the stamp so that the height is the value of this key; for example,
    \texttt{heightTo=2in} re-scales the stamp to have a 2in height.

\item[] Only one of the keys \texttt{scale}, \texttt{widthTo}, and \texttt{heightTo} are recognized
    for any stamp annotation. If all three are specified, only \texttt{scale} is used. If
    \texttt{widthTo} and \texttt{heightTo} are both specified, then \texttt{widthTo} is used.

\item[\textcolor{red}{\ding{043}}] The use of these keys is the recommend way of re-scaling
a stamp. These methods are compatible with the \texttt{rotate} key.

\item \texttt{customStamp}: You can create a custom stamp from any
    image you wish to use, here is
    \annotpro[type=stamp,customStamp=MyDPSImage,ap=AdobeDon,color=webbrown]{This
    is the best picture of me ever taken. Akron, about 2005.} one such
    example. The code for the above stamp is given here
    \annotpro{\annotstampv}.

\item \texttt{ap}: When the \texttt{\texttt{customStamp}} key is
    used, you have to supply an indirect reference to the appearance of
    the stamp. This reference is made through the \texttt{ap} key. The
    example above demonstrates the use of the \texttt{ap} key.
\end{itemize}
\textbf{\textcolor{red}{Important:}} When using the stamps of
\app{Acrobat} always perform a \uif{SaveAs} on the file when you have finished
building the file. This imports the appearances of the stamps into
the document and saves them.

\redpoint The creation of a custom stamp requires detailed list of steps, at
some point I'll write a white paper on the subject.\footnote{Use the \pkg{mkstmp} package
(\href{http://ctan.org/pkg/mkstmp}{ctan.org/pkg/mkstmp}),
details of how to create custom stamps are included in the documentation.}

\begin{defineJS}{\approvedStmp}
\\annotpro[type=stamp,name=Approved,widthTo=2in,rotate=30]{...}
\end{defineJS}

\newtopic
Here's an example of the keys \texttt{rotate} and \texttt{widthTo}:
\begin{center}
            \annotpro[type=stamp,name=Approved,widthTo=2in,rotate=30]{The source for this
            stamp is ...\string\r\approvedStmp}
\end{center}

\subsection{Key-values file attachment annotations}

The file attachment annotation has no pop-up window, the value of the required parameter is used as a description
of the attached file, and appears in the file attachment window.

The key-value pairs special to this type of annotation are as follows.

\begin{itemize}
    \item\texttt{name}: The name of the icon to use, permitted values are
    \texttt{Graph}, \texttt{Paperclip}, \texttt{PushPin}, and \texttt{Tag}. If the value of name is not
    specified, the default is \texttt{PushPin}. The annot\_pro package knows the dimensions of each of these
    icons, so you need not worry about them. They can be re-scale using standard commands from the graphics package,
    though, there may be little need of doing so.
    \item \texttt{file}: The value of the file key is the \emph{absolute path} to the file to be attached. I've
    devised a helper command \Com{defineAPath} that can be used to define the path to your file. For example, we can
    define a path to wherever the files are, like so
\begin{Verbatim}[fontsize=\footnotesize]
  \defineAPath{\graphicsPath}
    {C:/Users/Public/Documents/My TeX Files/%
        tex/latex/aeb/aebpro/annot_pro/examples/graphics}
\end{Verbatim}
\item[] The command takes two arguments, the name of the command to be defined, and the path.

\defineAPath{\graphicsPath}{C:/Users/Public/Documents/My TeX Files/tex/latex/aeb/aebpro/annot_pro/examples/graphics}

\begin{defineJS}{\fa}
\\annotpro[type=fileattachment,file={\graphicsPath/AdobeDon.pdf},name=Paperclip]{The author of annot\_pro (ho, ho).}
\end{defineJS}

\item[] We can create a file attachment
    \annotpro[type=fileattachment,file={\graphicsPath/AdobeDon.pdf},name=Paperclip]{The
    author of annot\_pro (ho, ho).} like so, ho, ho. Here is the code
    for this file attachment \annotpro[name=Star]{\fa}. Clicking the
    file attachment icon will open the file, in recent versions of
    Acrobat, the file is listed in the file attachments panel. Open it
    using the user interface, and you'll see the file listed, as well
    as a description, as passed to the annot as the second argument of
    \cs{annotpro}.
\end{itemize}

The file attachment icons can be resized using any of the graphics commands, \cs{scalebox} or \cs{resizebox}.

\subsection{The \texorpdfstring{\protect\uif{Text Box}}{Text Box}
    (\texorpdfstring{\protect\uif{Free Text}}{Free Text}) annotation}

A \uif{Text Box} annotation is a rectangular region in which the user can
enter rich text. The annotation may be created and `pre-populated' with rich text from a
{\LaTeX} source through the \pkg{annot\_pro} package.

The \uif{Text Box} annotation, as implemented by this package, requires the
\pkg{richtex} package, dated 2016/09/30 or later. A one simple method for
introducing \pkg{richtext} is through the \opt{useTextBox} option of
\pkg{annot\_pro}. Placing the following line in the preamble:
\begin{Verbatim}[xleftmargin=\amtIndent]
\usepackage[useTextBox]{annot_pro}
\end{Verbatim}
declares you are going to use \uif{Text Box} annotations. The option does
nothing more than to execute \cs{usepackage\darg{richtext}[2016/09/30]}. The
option is more of a convenience.

To create a  \uif{Text Box} (originally named \uif{Free Text}) annotation use the \cs{annotpro} command.
\bVerb\begin{minipage}{\linewidth}
\begin{minipage}{3.5in}
\xdef\panelWidth{\the\linewidth}%
\begin{Verbatim}[xleftmargin=\leftmargini,commandchars=!(),fontsize=\small]
\annotpro[!textbf(type=textbox),!ameta(KV-pairs)]
    {richtext=!ameta(name),defstyle=!ameta(name)}
\end{Verbatim}
\end{minipage}\hfill
\begin{minipage}{\linewidth-\panelWidth}
\setDisplayNumber\label{display:textbox}
\end{minipage}\end{minipage}\eVerb
Notice the second argument is not \ameta{text} as it is with the other annotations, but consists
of key-value pairs; recognized keys are \texttt{richtext} and \texttt{defstyle}.

\newtopic\noindent The sample file \texttt{textbox.tex} illustrates the features of this section.

\subsubsection{Creating an empty \texorpdfstring{\protect\uif{Text Box}}{Text Box}}

A common application would be to create an empty \uif{Text Box} for the
document consumer to type in comments. Below is an example of a \uif{Free
Text} annotation, called \uif{Text Box} by the user-interface of
\app{Acrobat}/\app{Adobe Reader}.
\begin{flushleft} %\previewtrue
\begin{minipage}{2in}
\annotpro[title=dpstory,type=textbox,subject=Empty Text Box]{}
\end{minipage}\hfill
\begin{minipage}{\linewidth-2in-10pt}\small
Press \uif{Ctrl+E} (\app{Windows}) or \uif{Cmd+E} (\app{Mac OS}) to obtain
the \uif{Properties} toolbar, now click on the text box  to obtain the
\uif{Text Box Properties} toolbar. Double clicking on the text box
brings up the \uif{Text Box Text Properties} toolbar.
\end{minipage}
\end{flushleft}
The verbatim listing of the above \uif{Text Box} is,
\begin{Verbatim}[xleftmargin=\leftmargini]
\annotpro[type=textbox,
    title=dpstory,subject=Empty Text Box]{}
\end{Verbatim}
The required second argument is empty, which leads to an empty \uif{Text Box}.

\subsubsection{Creating a non-empty \texorpdfstring{\protect\uif{Text Box}}{Text Box}}

A much more interesting exercise is to pre-populate the \uif{Text Box} with rich text for the
document consumer to read and/or to respond.

\paragraph[Steps to create rich text content]{Steps to create rich text content.}\chgCurrLblName{Steps to create rich text content}\label{para:StepsRC}
We briefly outline the techniques to create rich text
for a \uif{Text Box} annotation.
\begin{itemize}
    \item Use the \env{textboxpara} environment and the \cs{rtpara} command
    to declare your rich text paragraph.
\bVerb\takeMeasure{\string\rtpara[\ameta{KV-pairs}]\darg{\ameta{name\SUB{para}}}\darg{\ameta{rich-content}}}%
\begin{minipage}{\linewidth}
\begin{minipage}{\bxSize}
\xdef\panelWidth{\the\linewidth}%
\begin{Verbatim}[frame=single,commandchars=!()]
\begin{textboxpara}
\rtpara[!ameta(KV-pairs)]{!ameta(name!SUB(para))}{!ameta(rich-content)}
...
\end{textboxpara}
\end{Verbatim}
\end{minipage}\hfill
\begin{minipage}{\linewidth-\panelWidth}
\setDisplayNumber\label{display:rtpara}
\end{minipage}\end{minipage}\eVerb
Details of the \cs{rtpara} command are found in the documentation manual of
the \pkg{richtext} package. The \env{textboxpara} environment is needed for
certain redefinitions of internals because of the different way rich text
is supported and implemented in the \uif{Text Box} annotation verses the
rich text field.

\item Use the \cs{setRVVContent} command on your \cs{rtpara}-declared rich text and give it
a name \ameta{name\SUB{rvvc}}.
\bVerb\takeMeasure{\string\setRVVContent\darg{\ameta{name\SUB{rvvc}}}\darg{\ameta{name\SUB{para}}}}%
\begin{minipage}{\linewidth}
\begin{minipage}{\bxSize}
\xdef\panelWidth{\the\linewidth}%
\begin{Verbatim}[frame=single,commandchars=!()]
\setRVVContent{!ameta(name!SUB(rvvc))}{!ameta(name!SUB(para))}
...
\end{Verbatim}
\end{minipage}\hfill
\begin{minipage}{\linewidth-\panelWidth}
\setDisplayNumber\label{display:setRVVC}
\end{minipage}\end{minipage}\eVerb
This command expands the paragraph named \ameta{name\SUB{para}} and
develops the rich text version and the plain text version. It is
\ameta{name\SUB{rvvc}} that is used as a value for the \opt{richtext} key
above and illustrated below. To reduce the number of names, you can use
the same name for \ameta{name\SUB{rvvc}} as for \ameta{name\SUB{para}}
(\cs{setRVVContent\darg{para1}\darg{para1}}).

The rich text \emph{form field} supports multiple paragraphs, and richer
formatting options than the \uif{Text Box} annotation. Of importance is
that the \uif{Text Box} annotation only permits a \emph{single paragraph}.

\item (Optional) Declare a (named) default style using \cs{setDefaultStyle}:
\bVerb\takeMeasure{\string\setDefaultStyle\darg{\ameta{name\SUB{ds}}}\darg{\ameta{KV-pairs}}}%
\begin{minipage}{\linewidth}
\begin{minipage}{\bxSize}
\xdef\panelWidth{\the\linewidth}%
\begin{Verbatim}[frame=single,commandchars=!()]
\setDefaultStyle{!ameta(name!SUB(ds))}{!ameta(KV-pairs)}
...
\end{Verbatim}
\end{minipage}\hfill
\begin{minipage}{\linewidth-\panelWidth}
\setDisplayNumber\label{display:setDefStyle}
\end{minipage}\end{minipage}\eVerb
This default style is assignment a name that is used as the value of the
\opt{defstyle} key mentioned earlier, and illustrated below. If a value for
\opt{defstyle} is not provided, a standard default style is used.

\end{itemize}
Once the \cs{rtpara}-declared paragraphs have been made and their names have passed through
\cs{setRVVContent}, you are ready to create a \uif{Text Box} annotation.

\paragraph[Key-values for second argument]{Key-values for second argument.}\chgCurrLblName{Key-values for second argument}\label{para:KV2ndArg}
The required second argument, refer to display~\eqref{display:textbox}, has
two keys, both of which are optional. You are encouraged to read the
documentation for the \pkg{richtext} package for greater understanding of the
descriptions and examples found below.
\begin{description}
    \item[\texttt{richtext=\ameta{name\SUB{rvvc}}}] The \opt{richtext} key
        is the way the rich text is passed to the \uif{Text Box}. The
        \ameta{name\SUB{rvvc}} is declared by the \cs{setRVVContent}
        command. Use the command \cs{rtpara} within the \env{textboxpara}
        environment to define the actual rich text paragraph. For example,
\begin{Verbatim}[fontsize=\small,commandchars=!()]
\begin{textboxpara}
\rtpara{para1}{\span{color=FF0000}{Hello world},
    this is \bf{rich text}!}
\end{textboxpara}
\setRVVContent{myContent}{para1}
\annotpro[type=textbox,title=dpstory,
    subject=Text Box]{!textbf(richtext=myContent)}
\end{Verbatim}
The above code produces the following \uif{Text Box}:
\begin{quote}
\begin{textboxpara}
\rtpara{para1}{\span{color=FF0000}{Hello world},
    this is \bf{rich text}!}
\end{textboxpara}
\setRVVContent{myContent}{para1}
\annotpro[type=textbox,title=dpstory,
    subject=Text Box]{richtext=myContent}
\end{quote}

    \item[\texttt{defstyle=\ameta{name\SUB{ds}}}] Through the
        \opt{defstyle} you can define set the default style (refer to the
        documentation of the \pkg{richtext} package. If this key does not
        appear, then a predefined default style is provided.
\begin{Verbatim}[fontsize=\small,commandchars=!()]
\setDefaultStyle{myDS}{font={'Myriad Pro',sans-serif},
    color=0000FF}
\begin{textboxpara}
\rtpara{para1}{\span{color=FF0000}{Hello world},
    this is \it{rich text}!}
\setRVVContent{para1}{para1}
\end{textboxpara}
\annotpro[type=textbox,title=dpstory,
    subject=Text Box]{richtext=para1,!textbf(defstyle=myDS)}
\end{Verbatim}
Notice that we've used the name `\texttt{para1}' for both \cs{setRVVContent}
and \cs{rtpara}. The above code produces the following \uif{Text Box}:
\begin{flushleft}%\previewtrue
\begin{minipage}{2in}
\setDefaultStyle{myDS}{font={'Myriad Pro',sans-serif},color=0000FF}
\begin{textboxpara}
\rtpara{para1}{\span{color=FF0000}{Hello world},
    this is \it{rich text}!}
\end{textboxpara}
\setRVVContent{para1}{para1}
\annotpro[type=textbox,title=dpstory,
    subject=Text Box]{richtext=para1,defstyle=myDS}
\end{minipage}\hfill
\begin{minipage}{\linewidth-2in-10pt}\small
Press \uif{Ctrl+E} (\app{Windows}) or \uif{Cmd+E} (\app{Mac OS}) to
obtain the \uif{Properties} toolbar, now double click on the text box to
obtain the \uif{Text Box Text Properties} toolbar to verify the font used
is indeed Myriad Pro.
\end{minipage}
\end{flushleft}
\end{description}
If you are at all interested in generating the \uif{Text Box} annotation using rich text
strings, you are encouraged to read the documentation on \pkg{richtext},
there you will learn about all the key-values available to format the text
and the paragraph.

The \pkg{richtext} package was written for rich text form fields, but applies
to rich text annotations as well; however, it should be noted that there are
differences between forms and text box annotations in how they handle rich
text. One of the major differences is that rich text annotations (\uif{Text
Box}) \emph{do not support} multiple paragraphs as form fields do; as a
result, features listed in the \uif{Paragraph} and \uif{Link} tabs of the
\uif{Form Field Text Properties} dialog box are not available for the
\uif{Text Box}.

\paragraph[Keys \& commands inherited from the \texorpdfstring{\protect\pkg{richtext}}{richtext} package]%
{Keys \& commands inherited from the \pkg{richtext} package.}%
\chgCurrLblName{Keys \& commands inherited from the \pkg{richtext} package}\label{para:InheritedKeys}
The following keys are supported by the \uif{Text Box} annotation:
\bVerb\begin{minipage}{\linewidth}
\begin{minipage}[c]{4in}
\xdef\panelWidth{\the\linewidth}%
\begin{quote}\raggedright
\opt{font}, \opt{size}, \opt{\st{raise}}, \opt{ulstyle},
\opt{color}, \opt{\st{url}}, \opt{style}, \opt{\st{raw}}, \opt{halign}
\end{quote}
\end{minipage}\hfill
\begin{minipage}[c]{\linewidth-\panelWidth}
\setDisplayNumber\label{display:suppKeys}
\end{minipage}\end{minipage}\eVerb
The following commands are supported:
\bVerb\begin{minipage}{\linewidth}
\begin{minipage}[c]{4in}
\xdef\panelWidth{\the\linewidth}%
\begin{quote}\raggedright
\cs{span}, \cs{br}, \cs{it}, \cs{bf}, \cs{sup} and \cs{sub}
\end{quote}
\end{minipage}\hfill
\begin{minipage}[c]{\linewidth-\panelWidth}
\setDisplayNumber\label{display:suppCmds}
\end{minipage}\end{minipage}\eVerb
The ones having an overstrike are supported in a rich text \emph{form field}, but
not within an \uif{Text Box}. Refer to the documentation of the
\pkg{richtext} for details of these keys and commands. In this document, we
illustrate by example.

\paragraph[Key-values of \texorpdfstring{\protect\cs{rtpara}}{\textbackslash{rtpara}}]{Key-values of \cs{rtpara}.}%
\chgCurrLblName{Key-values of \cs{rtpara}}\label{para:KeysPara} The
keys of display~\eqref{display:suppKeys} -- excluding the overstrike ones -- may be used in the
\ameta{KV-pairs} argument of \cs{rtpara} of display~\eqref{display:rtpara}.

\paragraph[Permissible commands within \texorpdfstring{\protect\ameta{rich-content}}{<rich-content>}]{%
Permissible commands within \ameta{rich-content}.}\chgCurrLblName{Permissible
commands within \ameta{\ameta{rich-content}}}\label{para:KeysCmdsRC} The
\ameta{rich-content} argument of display~\eqref{display:rtpara} (normally)
consists of Latin 1 characters, plus any markup in the form of the commands
listed in display~\eqref{display:suppCmds}.
\begin{itemize}
    \item \cs{span} has two arguments, more on this command in the paragraph below
    titled \Nameref{para:Span}.
    \item \cs{br} is a line break, it has no argument.
    \item \cs{it} is italic font; it has one argument, the text to be
        placed in italics: \cs{it\darg{this is italic}}.
    \item \cs{bf} is bold font; it has one argument, the text to be placed in bold:
    \cs{bf\darg{this is bold}}.

    \cs{it} and \cs{bf} may be nested: \cs{it\darg{\cs{bf\darg{bold and italic}}}}.

    \item \cs{sup} and \cs{sub} are superscript and subscript, respectively; they each
    have one argument, the text to be raised or lowered. For example,
    \verb~We can \sup{raise} or we can \sub{lower} text~.
\end{itemize}
The above markups, with the exception of \cs{span} are illustrated below.
\begin{defineJS}{\annotextboxi}
\\begin{textboxpara}
\\rtpara{mypara}{\\it{This is italic}, whereas \\bf{this is bold}, but wait, we can do
\\it{\\bf{bold and italic}}.\\br\\br Moving on, we can \\sup{raise} or we can \\sub{lower} text.}
\\end{textboxpara}
\\setRVVContent{mypara}{mypara}
\\annotpro[type=textbox,width=3.5in]{richtext=mypara}
\end{defineJS}
\begin{quote}
\begin{textboxpara}
\rtpara{mypara}{\it{This is italic}, whereas \bf{this is bold}, but wait, we can do
\it{\bf{bold and italic}}.\br\br Moving on, we can \sup{raise} or we can \sub{lower} text.}
\end{textboxpara}
\setRVVContent{mypara}{mypara}
\annotpro[type=textbox,width=3.5in]{richtext=mypara}%
\annotpro[margin,readonly,margintext={\centering The Code}]{\annotextboxi}%
\end{quote}
The verbatim listing for this example is in the sticky note in the margin.

\paragraph[Some comments on the \texorpdfstring{\protect\cs{span}}{\textbackslash{span}}
command]{Some comments on the \cs{span} command.}\chgCurrLblName{Some comments on the \cs{span} command}\label{para:Span}
the \cs{span} command, defined only locally within the \ameta{rich-text} argument \cs{rtspan} is a general purpose
command to format text. It has two argument:
\begin{quote}
\cs{span\darg{\ameta{KV-pairs}}\darg{\ameta{text}}}.
\end{quote}
The \ameta{KV-pairs} argument can be the keys of
display~\eqref{display:suppKeys} (again excluding the overstrike keys). The \ameta{text} argument is the
text to be made rich; experience shows that \cs{it}, \cs{bf}, \cs{sub} and \cs{sup} may be used within
\ameta{text}. Italic and bold may be accomplished using the \opt{style} key, probably preferred over
using \cs{it} and \cs{bf} within \ameta{text}.
\begin{defineJS}{\annotextboxi}
\\begin{textboxpara}
\\rtpara{para1}{Welcome to my \\span{style={strikeit,bold}}{poor}\\span{style=bold}{rich text world}.
We add a little color shall we try \\span{color=FF0000}{red} or \\span{color=00FF00}{green}?\\br\\br
There are several styles of underlining \\span{ulstyle=ul}{basic underlining},
\\span{ulstyle=2ul}{double underlining}, \\span{ulstyle=wul}{word underlining}, and
\\span{ulstyle=2wul}{double word underlining}. Cool.}
\\end{textboxpara}
\\setRVVContent{para1}{para1}
\\annotpro[type=textbox,width=4.5in,height=14bp*7]{richtext=para1}
\end{defineJS}
\begin{quote}
\begin{textboxpara}
\rtpara{para1}{Welcome to my \span{style={strikeit,bold}}{poor}\span{style=bold}{rich text world}.
We add a little color shall we try \span{color=FF0000}{red} or \span{color=00FF00}{green}?\br\br
There are several styles of underlining \span{ulstyle=ul}{basic underlining},
\span{ulstyle=2ul}{double underlining}, \span{ulstyle=wul}{word underlining}, and
\span{ulstyle=2wul}{double word underlining}. Cool.}
\end{textboxpara}
\setRVVContent{para1}{para1}
\annotpro[type=textbox,width=4.5in,height=14bp*7]{richtext=para1}%
\annotpro[margin,readonly,margintext={\centering The Code}]{\annotextboxi}%
\end{quote}
The verbatim listing for this example is in the sticky note in the margin.

\paragraph[Key-values of \texorpdfstring{\protect\cs{setDefaultStyle}}{\textbackslash{setDefaultStyle}}]%
{Key-values of \cs{setDefaultStyle}.}%
\chgCurrLblName{Key-values of \cs{setDefaultStyle}}\label{para:KeysDS} The
keys of display~\eqref{display:suppKeys} -- excluding the overstrike ones --
may be used in the \ameta{KV-pairs} argument of \cs{setDefaultStyle} of
display~\eqref{display:setDefStyle}; however, only the keys \opt{font},
\opt{size}, \opt{color}, and \opt{halign} are typically used. For example,
\begin{Verbatim}[xleftmargin=\amtIndent,fontsize=\small,commandchars=!()]
\setDefaultStyle{myDS}{font={'Myriad Pro',sans-serif},
    size=12.0,color=0000FF,halign=left}
\end{Verbatim}
The name `\opt{myDS}' may then be used as the value of \opt{defstyle} key in the second argument
of \cs{annotpro}, see display~\eqref{display:textbox}.

\subsubsection{Key-values for text box annotations}

\hyperref[s:CommonKeys]{Section~\ref*{s:CommonKeys}} lists keys that are
common to all annotations; we list the ones that make sense for the \uif{Text
Box} annotation, and strikeout these that do not:
\begin{quote}\raggedright
\texttt{type}, \texttt{\st{name}}, \texttt{title}, \texttt{subject},
\texttt{\st{color}}, \texttt{readonly}, \texttt{opacity}, \texttt{margin},
\texttt{presets}
\end{quote}
In addition to these keys,  there are several keys particular to the text box
annotation. We list these and describe them in detail.
\begin{itemize}
    \item \texttt{width=\ameta{length}}: The width of the annotation, the
        default is \texttt{144bp} (\texttt{2in}).
    \item \texttt{height=\ameta{length}}: The height of the annotation, the
        default is \texttt{72bp} (\texttt{1in}).
    \item \texttt{bgcolor=\ameta{color}} The color to be used as the background color
    of the text box annotation. If \opt{bgcolor} has no value, transparent color is used.
    The default is white.
    \item \texttt{bcolor=\ameta{color}} The color to be used as the boundary color of the
    annotation. The default is black.
    \item \texttt{borderstyle=\ameta{choice}}: This keys determines the
        style of border to be used. It is a choice key, choices are
        \texttt{none}, \texttt{solid}, \texttt{dash1}, \texttt{dash2},
        \texttt{dash3}, \texttt{dash4}, \texttt{dash5}, \texttt{dash6},
        \texttt{cloud1}, and \texttt{cloud2}. The default is  \texttt{solid}.
    \item \texttt{borderwidth=\ameta{choice}}: The border width of the
        annotation, acceptable choices are  \texttt{.5}, \texttt{1}, \texttt{2},
        \texttt{3}, \texttt{4}, \texttt{6}, 8, and \texttt{10}. The default is \texttt{1}.
\end{itemize}
\begin{textboxpara}
\rtpara{para1}{\cs{annotpro[type=textbox, width=\cs{linewidth}, height=14bp*2, bgcolor=cornsilk,
bcolor=blue]{richtext=para1}}}\setRVVContent{para1}{para1}
\rtpara{para2}{\cs{annotpro[type=textbox, width=\cs{linewidth}, height=16bp*3, bgcolor, bcolor=red,
borderstyle=dash2, borderwidth=2]{richtext=para2}}}\setRVVContent{para2}{para2}
\rtpara{para3}{\cs{annotpro[type=textbox, width=\cs{linewidth}, height=18bp*3, bcolor=red,
borderstyle=cloud1]{richtext=para3}}}\setRVVContent{para3}{para3}
\end{textboxpara}%\previewtrue
\setDefaultStyle{myDS}{font=Courier,size=12.0,color=000000}
\annotpro[type=textbox, width=\linewidth, height=14bp*2, bgcolor=cornsilk, bcolor=blue]{richtext=para1,defstyle=myDS}\\[6bp]
\annotpro[type=textbox, width=\linewidth, height=16bp*3, bgcolor, bcolor=red, borderstyle=dash2, borderwidth=2]{richtext=para2,defstyle=myDS}\\[6bp]
\annotpro[type=textbox, width=\linewidth, height=18bp*3, bcolor=red, borderstyle=cloud1]{richtext=para3,defstyle=myDS}\\[6bp]
The second text box annotation above has transparent background color. Using your pointing device, move it around to verify
the background is `see through', compare with the other two by moving them around, not `see through'.

\subsubsection{Accented glyphs and the unicode characters}

There are several advantages that text box annotation have over rich text
form fields: movability and unicode. An annotation can be moved around the
page by the user quite easily, a form field typically cannot unless the user
is using \app{Acrobat}. Also, when it comes to using unicode, text box
annotations are far superior to rich text form fields. Unicode characters may
be inserted using the convenience commands \cs{uHex} and \cs{uDec}, where the
first take a hex code as its argument and the second takes a non-negative
integer as its argument. Latin1 accented characters can be entered using octal notation
for example, \verb~J\374rgen~
\begin{defineJS}{\annotextboxi}
\\begin{textboxpara}
\\rtpara{para1}{J\\374rgen is a nice fellow, though I've never met him.\\br\\br
We've communicated, J\\uHex{00FC}rgen and I, via email. J\\uDec{252}rgen where are you?}
\\end{textboxpara}
\\setRVVContent{para1}{para1}
\\annotpro[type=textbox,width=4.5in,height=14bp*7]{richtext=para1}
\end{defineJS}
\begin{textboxpara}
\rtpara{para1}{J\374rgen is a nice fellow, though I've never met him.\br\br
We've communicated, J\uHex{00FC}rgen and I, via email. J\uDec{252}rgen where are you?}
\end{textboxpara}
\begin{quote}%\previewtrue
\setRVVContent{para1}{para1}
\annotpro[type=textbox,width=4in,height=16bp*4]{richtext=para1}%
\annotpro[margin,readonly,margintext={\centering The Code}]{\annotextboxi}%
\end{quote}
But wait, we're not done. In theory, we can access any unicode character through the use
of \cs{uHex} or \cs{uDec}. I'll randomly pick off some unicode characters.
\begin{defineJS}{\annotextboxi}
\\begin{textboxpara}
\\rtpara{para1}{%
\\uHex{01A2}, \\uHex{023E}, \\uHex{03A3}, \\uHex{0416},
\\uHex{0583}, \\uHex{06A6}, \\uHex{263A}, \\uHex{FB21},
\\uHex{82A0}, \\uHex{4EE4}, \\uHex{F92C}, \\uHex{5475}}
\\end{textboxpara}
\\setRVVContent{para1}{para1}
\\annotpro[type=textbox,width=4in,height=14bp*2]{richtext=para1}
\end{defineJS}
\begin{textboxpara}
\rtpara{para1}{%
\uHex{01A2}, \uHex{023E}, \uHex{03A3}, \uHex{0416},
\uHex{0583}, \uHex{06A6}, \uHex{263A}, \uHex{FB21},
\uHex{82A0}, \uHex{4EE4}, \uHex{F92C}, \uHex{5475}}
\end{textboxpara}
\begin{quote}%\previewtrue
\setRVVContent{para1}{para1}
\annotpro[type=textbox,width=4in,height=14bp*2]{richtext=para1}%
\annotpro[margin,readonly,margintext={\centering The Code}]{\annotextboxi}%
\end{quote}
Cool!


\subsection{Setting Global Options with
    \texorpdfstring{\protect\cs{setAnnotOptions}}{\CMD{setAnnotOptions}}}

Global options are by using the \cs{setAnnotOptions} command.
In the preamble of this document I placed
\begin{Verbatim}[fontsize=\footnotesize]
\setAnnotOptions{subject={AcroTeX Communiqu\'e},title={D.P. Story}}
\end{Verbatim}
That way, I didn't have to constantly type in my personal name for each example. These options can be overwritten
by specifying options locally, if I say, \cs{annotpro[author=Don Story]\darg{Hi there!}}, the author is now my
alter ego, Don Story.

%\redpoint\textbf{\textcolor{red}{Important:}} Certain key, \texttt{name}, should not be used to set global options,
%\cs{setAnnotOptions} tests for these, and puts them back to their default values that are expected
%by \cs{annotpro}. These keys should only be used for passing options to \cs{annotpro} in its option list.


\bigskip
\noindent
That's all for now, I simply must get back to my retirement. \dps\space\annotpro[type=stamp,
    customStamp=MyDPSImage,ap=AdobeDon,color=webbrown]{%
    Did I say that I had to get back to my retirement?}

\end{document}
