summaryrefslogtreecommitdiff
path: root/texmf-dist/doc/latex/fitr/fitr_man.tex
blob: d0898ac60d198885aa9e29f30f12c34add7b2f4c (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
\documentclass{article}
\usepackage[fleqn]{amsmath}
\usepackage[
    web={centertitlepage,designv,forcolorpaper,
         latextoc,pro}, %tight,
    eforms,aebxmp
]{aeb_pro}
\usepackage[fortextbook,usecustomdesign,nomarginwrite]{eqexam}
\usepackage{graphicx,array}
\usepackage[blink,!preview,!viewMagWin]{fitr}

%\usepackage{myriadpro}
\usepackage[altbullet]{lucidbry}


\renewcommand\allowFXDefault{false}

%\usepackage{makeidx}
%\makeindex
\usepackage{acroman}
\usepackage[active]{srcltx}

\let\tops\texorpdfstring

\makeatletter
\newcommand{\FmtMP}[2][0pt]{\mbox{}\marginpar{\raisebox{#1}{\parbox{\marginparwidth}{\slshape\raggedleft\small#2}}}}
\addtolength{\marginparwidth}{1in}
\def\eq@fititin#1{\noindent\unskip\nobreak\hfill\penalty50
    \hskip2em\hbox{}\nobreak\hfill#1}
\def\fitit{\eq@fititin{\exrtnlabelformat}}
\@mparswitchfalse\reversemarginpar
\def\meta#1{$\langle\textit{\texttt{#1}}\rangle$}
\let\maketitle\web@maketitle
\renewcommand{\paragraph}
    {\@startsection{paragraph}{4}{0pt}{6pt}{-3pt}
    {\normalfont\normalsize\bfseries}}
\renewcommand{\subparagraph}
    {\@startsection{subparagraph}{5}{\parindent}{6pt}{-3pt}%
    {\normalfont\normalsize\bfseries}}
\makeatother


\urlstyle{rm}
\def\fitrpkg{\textsf{f{i}tr}}
\let\texorpdfstring\tops

\DeclareDocInfo
{
    university={\AcroTeX.Net},
    title={\tops{The}{The manual for the} \tops{\textsf{f{i}tr}}{fitr} Package\tops{\\
        Defining and Jumping to\\a Rectangular Destination}{}},
    author={D. P. Story},
    email={dpstory@acrotex.net},
    subject=Documentation for the fitr package,
    talksite={\url{www.acrotex.net}},
    version={1.3.2, 2020/07/09},
    Keywords={LaTeX,PDF,fitr,JavaScript,Adobe Acrobat},
    copyrightStatus=True,
    copyrightNotice={Copyright (C) \the\year, D. P. Story},
    copyrightInfoURL={http://www.acrotex.net}
}
\DeclareInitView{windowoptions={showtitle}}
\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=-62.5pt,fontsize=large,color=aeb}
\subsectionLayout{indent=-31.25pt,color=aeb}
\subsubsectionLayout{indent=0pt,color=aeb}
\subsubDefaultDing{\tops{$\bullet$}{\textrm\textbullet}}

%\pagestyle{empty}


%\definePath\bgPath{"C:/Users/Public/Documents/%
%   ManualBGs/Manual_BG_Print_AeB.pdf"}
\chngDocObjectTo{\newDO}{doc}
\begin{docassembly}
var titleOfManual="The fitr Package";
var manualfilename="Manual_BG_Print_fitr.pdf";
var manualtemplate="Manual_BG_Green.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 an implementation of the \textbf{FitR} view-type
destination. The \textsl{PDF Reference} describes \textbf{FitR} as,
\begin{quote}
    Display the page designated by page, with its contents
    magnified just enough to fit the rectangle specified by the
    coordinates \textsl{left}, \textsl{bottom}, \textsl{right},
    and \textsl{top} entirely within the
    window both horizontally and vertically.
\end{quote}
The package supports the \app{dvips}, \app{pdflatex}, \app{lualatex},
\app{xelatex}, \textsf{dvipdfm}, and \textsf{dvipdfmx} applications.

The only required packages are the \pkg{eforms} package (dated
2012/06/20 or later), which is part of the \pkg{AeB Bundle}, and
\pkg{collectbox} by Martin Scharrer, more on this package later, and
the ubiquitous \pkg{xcolor}.\footnote{The \textsf{eforms} package
itself brings in other packages, including \textsf{hyperref} and
\textsf{insdljs}.}

\paragraph*{Motivation.} This package was developed in response to a user of the \pkg{AeB Bundle} who
was interested in developing documents for students with \emph{low vision};
the idea is to magnify regions of the document so the student can read more
comfortably.

\paragraph*{Demonstration files.} The demonstration files are \texttt{fitr\_demo.tex} which
illustrates the package and some special methods for people with low vision,
and \texttt{fitr\_minimal.tex}, which is the same demo file with any extra
packages stripped out.

\paragraph*{What's New for Version 1.3.2 (2020/07/09)} The package is extended to support
the PDF creator \app{lualatex}. All common workflows are now automatically
detected: \app{pdflatex}, \app{lualatex}, and \app{xelatex}. If  no driver is
specified and none is automatically detected, \app{dvips} is automatically
selected by default. The other drivers \app{dvipdfm} and \app{dvipdfmx} need
to be explicitly specified as the driver (\ameta{driver}). The \ameta{driver}
option is described in the next section. Also, there are several new options,
one of which is \opt{gonative}; when this option is selected, no field or
document JavaScript is used. For the \opt{gonative} option, the workflow
\app{dvips\,->\,ps2pdf} is also supported because there is no document
JavaScript required.

\section{The Preamble and Package Options}

The minimal preamble for this package is
\begin{Verbatim}[xleftmargin=\amtIndent,commandchars=!()]
\usepackage[!meta(driver),!meta(options)]{fitr}
\end{Verbatim}
Permissible names for \ameta{driver} are \opt{dvips}, \opt{pdftex},
\opt{luatex}, \opt{xetex}, \textsf{dvipdfm}, and \textsf{dvipdfmx}. The
\ameta{driver} option is only required for \app{dvipdfm} and \app{dvipdfmx},
the others are either detected automatically, or is the default driver
(\opt{dvips}). The drivers and options are discussed in more detail below.

\paragraph*{Package requirements.} The \pkg{hyperref} package is brought in through the \pkg{eforms} package.
Another package requirement is \textsf{collectbox} by Martin Scharrer.
The \cs{collectbox} command is used to collect the second argument of
\cs{jdRect}, see the discussion of \cs{jdRect} in \hyperref[jdRect]{Section~\ref*{jdRect}}.
As a result, the second argument may contain verbatim text in it. Very cool.

\paragraph*{Package options.} The package has several options, broken down below by
category: Driver, View, and Other options.
\begin{description}
\item[Driver Options:] The major driver options are
    \opt{dvips}\FmtMP{\opt{dvips}} (the default),
    \opt{pdftex}\FmtMP{\opt{pdftex}}, \opt{luatex}\FmtMP{\opt{luatex}}, and
    \opt{xetex}\FmtMP{\opt{xetex}}. Lesser driver options are
    \opt{dvipdfm}\FmtMP{\opt{dvipdfm}} and
    \opt{dvipdfmx}\FmtMP{\opt{dvipdfmx}}, but there seems to be a bug in
    the \cs{includegraphics} command as the bounding box is not correctly
    re-scaled. If you specify \opt{dvips}, it is assumed that you are using
    \app{Adobe Distiller} as your PDF creator.\footnote{Unless you are also
    using the \opt{gonative} option, see the description of this option.}

    The \pkg{fitr} package checks whether the \pkg{web} package is loaded,
    if so, the driver of \pkg{web} is used; otherwise \pkg{fitr}
    auto-detects for \app{pdftex}, \app{luatex}, and \app{xetex}. If no
    driver is passed, and neither \app{pdftex}, \app{luatex}, nor
    \app{xetex} are detected, the default driver, \app{dvips}, is used.

\item[Viewing Options:] When you specify
    \opt{preview}\FmtMP{\opt{preview}}, the bounding boxes of the buttons
    are shown in the dvi-previewer (or the PDF viewer); you can turn off
    this preview by specifying \opt{!preview} (or removing \opt{preview}
    entirely from the option list). The other option type is
    \opt{viewMagWin}\FmtMP{\opt{viewMagWin}}, when this option the viewing
    window, a rectangular region, becomes visible in the dvi-previewer (or
    in the PDF document); specifying \opt{!viewMagWin} turns off this type
    of preview.

    The effects of the viewing options will be illustrated later in this
    document, see \autoref{previewEx} on page~\pageref*{previewEx}.

\item[Special Effects Options:] There are several options for bringing in
    additional document JavaScript for special effects: (1)
    \opt{blinkonjmp}\FmtMP{\opt{blinkonjmp}} blinks the border following the jump
    to a focused destination; (2)
    \opt{blinkonrestore}\FmtMP{\opt{blinkonrestore}} blinks the border following
    the restore action; (3) \opt{blink}\FmtMP{\opt{blink}} is a convenience
    option that combines the actions of \opt{blinkonjmp} and
    \opt{blinkonrestore}. There are negative versions of these options as
    well: \opt{!blinkonjmp}, \opt{!blinkonrestore}, and \opt{!blink}. The
    default is to have no special effects, in effect \opt{!blink} is the
    default. Refer to \hyperref[FX]{Section~\ref*{FX}} for more information
    on special effects.

\item[Other Options:] The \opt{gonative}\FmtMP{\opt{gonative}} option does
    not use any field or document JavaScript; as a result, the
    \app{dvips\,->\,ps2pdf} is then supported as no document JavaScripts
    are employed.

\end{description}

\section{The \tops{\protect\cs{jdRect}}{\textbackslash{jdRect}} command}\label{jdRect}

The {\fitrpkg} has only one command, \cs{jdRect}, which (optionally)
\textbf{j}umps to and/\allowbreak or sets a \textbf{d}estination of a
\textsf{Fit\textbf{Rect}}angle.\footnote{I had some problems
naming this command.}
There are two forms of usage. \cs{jdRect} optionally
creates a push button or link, and optionally creates a viewing window. The
term \emph{viewing window} refers to a rectangular region that is created by
the \textbf{FitR} destination viewing specification, see \textbf{Table~8.2
Destination syntax} of the \textsl{PDF Reference}, version 1.7. A \emph{named
destination} is created and is associated with the viewing window. When we
jump to a viewing window, this window is magnified to the largest extent
possible. For example, click on the either of the two displayed forms of the
syntax for \cs{jdRect}; after jumping to the viewing window, click on the
same display to return to the previous view.

%\previewtrue
\newtopic\noindent
There are two versions of \cs{jdRect}, the command itself, and a
\texttt{*} version, \cs{jdRect*}. The syntax follows, along with the
expected parameters.
\bVerb %\previewOn\viewMagWinOn
\takeMeasure{\string\jdRect[\ameta{key-values}]}%
\setlength{\dimen0}{\bxSize}%
\def\1{\rlap{\hspace*{\dimen0}\sffamily(Click on box to zoom in)}}
\jdRect[width=\bxSize,height=1.5\baselineskip,lift=\baselineskip,adddestw=10bp,adddesth=10bp]\relax
\begin{dCmd}[commandchars=!()]{\bxSize}
!1\jdRect[!ameta(key-values)]
\end{dCmd}
\eVerb
%\begin{quote}
%    \jdRect*[adddestw=10bp,adddesth=10bp]{\cs{jdRect[\meta{key-values}]}}
%\end{quote}
The above version is used to overlay a region with a button and view
window. No content is specified, but is defined by specifying the
\texttt{width} and \texttt{height}; it can be positioned using
\texttt{shift} and \texttt{lift}.

\newtopic\noindent
There is a \texttt{*}-version as well:
\bVerb %\previewOn\viewMagWinOn
\takeMeasure{\string\jdRect[\ameta{key-values}]\darg{\ameta{content}}}%
\setlength{\dimen0}{\bxSize}%
\def\1{\rlap{\hspace*{\dimen0}\sffamily(Click on box to zoom in)}}
\jdRect[width=\bxSize,height=1.5\baselineskip,lift=\baselineskip,adddestw=10bp,adddesth=10bp]\relax
\begin{dCmd}[commandchars=!()]{\bxSize}
!1\jdRect[!ameta(key-values)]{!ameta(content)}
\end{dCmd}
\eVerb
%\begin{quote}
%    \jdRect*[adddestw=10bp,adddesth=10bp]{\cs{jdRect*[\meta{key-values}]}\verb!{!\meta{content}\verb!}!}
%\end{quote}
The second parameter \meta{content} is required when the \texttt{*} is
present. This version is meant to enclose \meta{content} within the button
and view window. The \texttt{width} and \texttt{height} keys are ignored,
but \texttt{shift} and \texttt{lift} are obeyed (though you may
\texttt{shift} or \texttt{lift} the button/view window away from the
content).

\paragraph*{Description of \ameta{key-values}.}
Before illustrating the \cs{jdRect} command, we first discuss its
key-value pairs.
\begin{itemize}
\item \texttt{lift=\meta{length}}: This key-value lifts (raises) the
    button/viewing window up (or down); for example,
    \texttt{lift=15pt} (or \texttt{lift=-15pt}). The default is a lift
    of \texttt{0pt}. See \autoref{displayEqEx} on page~\pageref*{displayEqEx}.

\item \texttt{shift=\meta{length}}: The amount of horizontal shift;
    positive to the right, negative to the left. For example,
    \texttt{shift=-1in} shifts the button/viewing window 1 inch to the
    left. The default is \texttt{0pt}. See
    \autoref{displayEqEx} on page~\pageref*{displayEqEx}.

\item \texttt{width=\meta{length}}: When using \cs{jdRect}---as
    opposed to \cs{jdRect*}---, the width of the button and viewing
    window is determined by the \texttt{width} key. For example
    \texttt{width=1in} creates a button/viewing window that is 1 inch
    wide. The value of this key is ignored when the \texttt{*} form of
    the \cs{jdRect} is used. The default value is \texttt{0pt}. This
    key is required when \texttt{*} is not present. See
    \autoref{displayEqEx} on page~\pageref*{displayEqEx}.

\item \texttt{height=\meta{length}}: Similar comments here as was made
    for the \texttt{width} key. This key is used to set the height of
    the button/viewing window. The default is 0pt. It is required when
    \texttt{*} is not present. See \autoref{displayEqEx} on
    page~\pageref*{displayEqEx}.

\item \texttt{ref=t|c|b}: The \texttt{ref} key-value pair determines
    the reference point of the button/viewing window. Permissible
    values are \texttt{t} top (the default), \texttt{c} center, and
    \texttt{b} bottom. This key is only obeyed with the \cs{jdRect*}
    form of the command; otherwise, a reference point of \texttt{b} is
    used.

\item \texttt{adddestw=\meta{length}}: The default is for the viewing window to have
the same dimensions as the underlying button. The \texttt{adddestw}
key-value pair is used to widen the viewing window; \texttt{adddestw=.2in}
widens the window by \texttt{.2in} on the left and \texttt{.2in} on the
right. See \hyperref[bvw]{Figure~\ref*{bvw}}, page~\pageref*{bvw}.

\item \texttt{adddesth=\meta{length}}: Similar to \texttt{adddestw} but for height.
The \texttt{adddesth}
key-value pair is used to increase the height the viewing window; \texttt{adddesth=.2in}
increases the height of the window by \texttt{.2in} on the top and \texttt{.2in} in the bottom.
See \hyperref[bvw]{Figure~\ref*{bvw}} below.
\begin{figure}[htb]
\begin{center}\setlength\fboxsep{0pt}
   \fbox{\parbox[c][.9in]{2.4in}
        {\vfill\hfil\fbox{\parbox[c][.5in]{2in}{\hfill\vfill}}\hfil\vfill}}\\[4pt]
        \caption{Button and Viewing Window}\label{bvw}
        {\small\texttt{width=2in,height=.5in,adddestw=.2in,adddesth=.2in}}
\end{center}
\end{figure}

\item \texttt{button=true|false}: \texttt{button} is a Boolean switch.
    If \texttt{true} (the default), \cs{jdRect} creates a push button.
    When the user pushes the button, the viewer zooms in to the view
    window. Clicking the same region again restores the previous view.

\item[] When \texttt{button} is \texttt{false}, the button is not created,
    but the viewing window is still created. You can then jump to the
    viewing window with a separate link or button. When
    \texttt{button=false}, use the \texttt{dest} key to assign a name
    (\ameta{name}) to the viewing window. ({\fitrpkg} automatically creates
    the destination names internally, they are used by the buttons. If no
    button is created, name the destination so you know its name and can
    reference it in link that jumps to that viewing area.)


\item \texttt{link=jmp|restore} If \texttt{link} has a value, then
    {\fitrpkg} puts \texttt{button=false}. The \texttt{link} key is
    used to create jumps or restore actions to or from a viewing
    window. When \texttt{link=jmp} a jump action is created, the jump
    will be to the value of the \texttt{dest} key. If this is a pure
    link that jumps to another viewing window, then use the
    \texttt{nodest} key as well; no viewing window will be created
    around the link, as it is unlikely you'll want to jump to a link.


\def\RungePic{\kern0pt\includegraphics[width=1in]{runge}}
\def\jrOpts#1#2{link=#1,dest=#2}

\item[] For example click on the link
\textbf{\jdRect*[nodest,\jrOpts{jmp}{rungePic},adddestw=10,adddesth=10]{Carl Runge}}%
\marginpar{\raggedleft\jdRect*[\jrOpts{restore}{rungePic},adddestw=\marginparsep,
adddesth=\marginparpush]{\parbox[t]{1in}{\RungePic\\
\normalcolor\centering\footnotesize\textsf{Carl Runge}}}} and jump to
the picture of Runge in the margin. Click on the picture of Runge and
return to the previous view.

The jump to the picture from the text ``Carl Runge'' is as follows:
\begin{Verbatim}[xleftmargin=\amtIndent]
\jdRect*[nodest,link=jmp,dest=rungePic,
adddestw=10bp,adddesth=10bp]{Carl Runge}
\end{Verbatim}
The important options are \texttt{nodest,link=jmp,dest=rungePic};
no (named) viewing window is created, we want to create a jump link here,
the destination of the jump link is the destination \texttt{rungePic}.

\item[] The color of the link is determined by \cs{@linkcolor}, a \textsf{hyperref}
command that holds a named color. This can be redefined at anytime,
directly using
\begin{Verbatim}[xleftmargin=\amtIndent]
\makeatletter
\def\@linkcolor{blue}
\makeatother
\end{Verbatim}
or, if you are using the \texttt{pro} option with the \textsf{web}
package, you can say,
\begin{Verbatim}[xleftmargin=\amtIndent]
\selectColors{linkColor=blue}
\end{Verbatim}
When using the \textsf{web} package, the default is \texttt{webgreen}.

\item[] The action to restore the previous view is as follows:
\begin{Verbatim}[xleftmargin=\amtIndent]
\marginpar{\raggedleft\jdRect*[link=restore,dest=rungePic,
  adddestw=\marginparsep,adddesth=\marginparpush
  ]{\parbox[t]{1in}{\RungePic\\
  \normalcolor\centering\footnotesize\textsf{Carl Runge}}}}
\end{Verbatim}
The picture is placed in the margin using \cs{marginpar}; the command
\cs{RungePic} is a convenience macro that uses \cs{includegraphics} in
import the picture. The important options are
\texttt{link=restore,dest=rungePic}, this first key-value pair causes
\cs{jdRect} to create a restore link, the second one says to create a
viewing window with a name of \texttt{rungePic}, this is the
destination the Carl Runge link jumps to.


\item \texttt{nodest}: A Boolean switch whose default value is
    \texttt{false}. When \texttt{nodest} is used (making the switch a
    value of \texttt{true}), no viewing window is created.

\item \texttt{dest=\meta{name}}: This key is a way of explicitly naming the
    viewing window (the destination). The destination is normally
    automatically generated when \texttt{button=true}, this key is
    used with the \texttt{link} key, as illustrated above.
\item \texttt{allowFX}: A Boolean switch (of sorts). The \texttt{fitr}
    allows for special effects (FX) when a viewing window is jumped to
    and when the view is restored. The default value of
    \texttt{allowFX} is \texttt{true} allow special effects if there
    are any defined. By saying \texttt{allowFX=false}, no special
    effects are used, even if some are defined.

\item[] An example of special effects you say? Try clicking on the
    Pythagorean Theorem
    \jdRect*[allowFX,adddestw=10bp,adddesth=10bp]{$ a^2 + b^2 = c^2 $}
The default is to allow special effects, the default is set by the command,
\bVerb\takeMeasure{\string\renewcommand\darg{\string\allowFXDefault}\darg{true}}%
\begin{dCmd}[commandchars=!()]{\bxSize}
\renewcommand{\allowFXDefault}{true}
\end{dCmd}
\eVerb By declaring \verb~\renewcommand{\allowFXDefault}{false}~, the default
is now set to no special effects.
\end{itemize}

\paragraph*{Passing KV-pairs to the push button of \cs{jdRect}.}\label{para:Presets} When \cs{jdRect}
produces a push button, you can pass \pkg{eforms} key-value pairs (KV-pairs) to
the underlying push button.
\bVerb\takeMeasure{\string\newcommand\darg{\string\overlayPresets}\darg{\string\H\darg{I}\string\BG\darg{}\string\BC\darg{}\string\S\darg{S}}}%
\begin{dCmd}[commandchars=!()]{\bxSize}
\newcommand{\overlayPresets}{\H{I}\BG{}\BC{}\S{S}}
\restoreOverlayPresets
\end{dCmd}
\eVerb See the \textsf{eforms} manual for the meaning of these cryptic symbols.
The initial value of \cs{overlayPresets} create transparent push
buttons. In subsequent examples, we will redefine \cs{overlayPresets} to
change the visibility of the overlay buttons. The command
\cs{restoreOverlayPresets} returns any re-definition of \cs{overlayPresets}
to its default definition, which is shown above.

\section{Some Examples}

\everymath{\displaystyle}

In this section, several examples are presented that illustrate the options
of the \cs{jdRect} command. The examples in this section are created with
\begin{Verbatim}[xleftmargin=\amtIndent]
\renewcommand{\allowFXDefault}{false}
\end{Verbatim}
in force. There is one example
where we set \opt{allowFX=true}. Additional discussion on special effects
(FX) may be found in \hyperref[FX]{Section~\ref*{FX}}.

\begin{example}\label{previewEx}\previewOn\viewMagWinOn
\textbf{Illustrate Preview Rectangles.} The \texttt{preview} and
\texttt{viewMagWin} options just set Boolean switches. In this example, we
manually give these switches a value of \texttt{true}
(\cs{previewtrue}\cs{viewMagWintrue}). Take a close look at the following
function \jdRect*{$ f(x) = \frac{1}{\sqrt{2\pi}}\int_{-\infty}^x
e^{-t^2/2}\,\text{d}t$}, or the more general form
\jdRect*[adddestw=20bp,adddesth=10bp]{$ f(x;\mu;\sigma) =
\frac{1}{\sigma\sqrt{2\pi}}\int_{-\infty}^x
e^{-\frac{(t-\mu)^2}{2\sigma^2}}\,\text{d}t$} The preview rectangles are
shown: For the one on the left, the dimensions of the push button and the
viewing rectangle are the same; for one on the right, the dimensions of the
viewing window have been increased by using
\texttt{adddestw=20bp,adddesth=10bp}. When you jump to each of these viewing
windows, the one on the left is magnified much more than the one on the
right, but the larger viewing window allows the user to see some of the
surrounding text.\fitit
\end{example}

\begin{example}\label{displayEqEx}
\textbf{Display Math.} Displayed math presents a problem. We take the
following set of equations to illustrate.

Suppose we want to classify third order \textsf{Runge-Kutta} type methods.
Start with
\begin{align*}
\jdRect[height=1.3in,width=2.6in,lift=16pt,shift=-15pt,
    adddestw=10bp,adddesth=10bp]
K_1 &= hf(t_n, y_n)\\
K_2 &= hf(t_n +r h, y_n+aK_1)\\
K_3 &= hf(t_n +s h, y_n+bK_1+cK_2)\\
K &= w_1 K_1+ w_2 K_2+ w_3 K_3\\
y_{n+1} &= y_n+K
\end{align*}
Find the system of equations satisfied by
\jdRect*[adddestw=10,adddesth=10]{$r,s, a, b, c, w_1, w_2, w_3$}
that will make the above algorithm a third order method.

The verbatim listing of this set of aligned equations is,
\begin{Verbatim}[xleftmargin=\amtIndent,numbers=left]
\begin{align*}
\jdRect[height=1.3in,width=2.6in,lift=16pt,shift=-15pt,
    adddestw=10bp,adddesth=10bp]
K_1 &= hf(t_n, y_n)\\
K_2 &= hf(t_n +r h, y_n+aK_1)\\
K_3 &= hf(t_n +s h, y_n+bK_1+cK_2)\\
K &= w_1 K_1+ w_2 K_2+ w_3 K_3\\
y_{n+1} &= y_n+K
\end{align*}
\end{Verbatim}
This is an example of \cs{jdRect} (the non-\texttt{*} version), so there is
no second argument.  In this case, we create our button dimensions using
\texttt{height=1.3in,width=2.6in}, line~(2). Note the positioning of the
\cs{jdRect} command, the upper-left point of the display. We then use
\texttt{lift=16pt,shift=-15pt} to move the button around to cover the
equations, line~(2); finally, we increase the dimensions of the viewing
window in line~(3) with \texttt{adddestw=10bp,adddesth=10bp}. Now, how were
the values of these keys determined? By trial and error, while the
\texttt{preview} and \texttt{viewMagWin} options were in effect. Below are
the same equations with \cs{previewtrue} and \cs{viewMagWintrue}, locally
invoked:\previewOn\viewMagWinOn\footnote{You can also use the commands
\cs{previewOn}, \cs{previewOff}, \cs{viewMagWinOn}, and \cs{viewMagWinOff} as
a convenient way of turning on or off these switches.}
\begin{align*}
\jdRect[height=1.3in,width=2.6in,lift=16pt,shift=-15pt,
    adddestw=10bp,adddesth=10bp]
K_1 &= hf(t_n, y_n)\\
K_2 &= hf(t_n +r h, y_n+aK_1)\\
K_3 &= hf(t_n +s h, y_n+bK_1+cK_2)\\
K &= w_1 K_1+ w_2 K_2+ w_3 K_3\\
y_{n+1} &= y_n+K
\end{align*}
The preview rectangles do not take up any {\TeX} space, so they overlap
parts of the paragraph content. When you zoom in, you'll see part of the
part of the word ``invoked:'', as seen in the upper-left corner, at least
according to the viewing window preview. Is it so?

After you've set the position of the rectangles, and after all changes
have been made to the underlying content, you don't need the preview
modes.\fitit
\end{example}

\begin{example}\label{CustomAppr}
\textbf{Customizing the appearance.} The among the properties of the
underlying push button is to be visible, but does not print. The background
and the border are transparent. The default properties of the button overlay
are passed to the push button using \cs{overlayPresets}, introduced earlier
on \hyperref[para:Presets]{page~\pageref*{para:Presets}}. You can modify these
settings locally, within a group, or globally. In this example, we change the
border to red dashed line. We redefine \cs{overlayPresets} as follows:
\begin{Verbatim}[xleftmargin=\amtIndent]
\renewcommand{\overlayPresets}{\H{I}\BG{}\BC{red}\S{D}}
\end{Verbatim}
\renewcommand{\overlayPresets}{\H{I}\BG{}\BC{red}\S{D}}%
In the re-definition, \verb!\BC{red}! is declared (the \textsf{xcolor} package is
required here for named colors; otherwise, we would say \verb~\BC{1 0 0}~),
\verb!\S{S}! is changed to \verb~\S{D}~, which gives a dashed
(\texttt{D}) border as opposed to a solid (\texttt{S}) border. Now to
illustrate this. My name is \jdRect*{D. P. Story!}; lets increase the
viewing window, shall we? My name is \jdRect*[adddestw=10bp,adddesth=10bp]{D. P.
Story!}. Keep in mind that we are overlaying a push button; if you want
the underlying text to have a color, you need to color it yourself:
\jdRect*[allowFX,adddestw=10bp,adddesth=10bp]{\textcolor{blue}{D. P. Story}!}
This last button has code,
\begin{Verbatim}[xleftmargin=\amtIndent,commandchars=!()]
\jdRect*[!textbf(allowFX),adddestw=10bp,adddesth=10bp]%
    {\textcolor{blue}{D. P. Story}!}
\end{Verbatim}
As the changes to the preset appearance are inside a group, after this
example (environment)) \cs{overlayPresets} will revert to its definition
that was in effect outside the example.\fitit
\end{example}

\section{Special Effects (FX)}\label{FX}

\subsection{Built-in FX}

There are two built-in JavaScript functions \texttt{pbJmpHook()} and
\texttt{pbRestoreHook()}; the first blinks the view window just after the
focused jump, and the latter blinks the view window after the previous view
is restored. These built-in functions are not available by default, they are
brought into the document with the options \opt{blinkonjmp} and
\opt{blinkonrestore}. The option \opt{blink} is equivalent to specifying both
\opt{blinkonjmp} and \opt{blinkonrestore}. This document was compiled by inputting
the \pkg{fitr} package as \verb~\usepackage[blink]{fitr}~.

\subsubsection{FX examples}

\begin{example}
\textbf{FX and Verbatim.} Zoom in on verbatim text
\jdRect*[allowFX,adddestw=10bp,adddesth=10bp]
{\verb!#$$%&$%^&$%^$!} which can be handled by \cs{jdRect*} command. The listing is,
\begin{Verbatim}[xleftmargin=\amtIndent,commandchars={~()}]
\jdRect*[~textbf(allowFX),adddestw=10bp,adddesth=10bp]
{\verb!#$$%&$%^&$%^$!} which can be handled by
\verb!\jdRect*! command. The listing is,
\end{Verbatim}
Notice that \texttt{allowFX} is specified. This key does not normally
appear in the option list, its default value is normally \texttt{true};
however, for this document, the following definition was made in the preamble,
\begin{Verbatim}[xleftmargin=\amtIndent]
\renewcommand\allowFXDefault{false}
\end{Verbatim}
This (re)definition of \cs{allowFXDefault} sets the default value of
\texttt{allowFX} to \texttt{false}. This is that earlier, the special effects
would not be seen, by default. To see their effect, we have to explicitly put
\texttt{allowFX} to \texttt{true}, which is what the single key does. (Or,
you can say \texttt{allowFX=true}, but that is five more key presses.)\fitit
\end{example}

\begin{example}\label{fx}
\textbf{FX.} Jump to the
{\renewcommand{\overlayPresets}{\H{I}\BG{}\BC{blue}\S{D}}%
\jdRect*[allowFX,adddestw=10bp,adddesth=10bp]{{\fitrpkg} Package!}} Click
on the verbatim region below to view the listing up close.
\bVerb\takeMeasure{Jump to the
\string\jdRect*[\textbf{allowFX},adddestw=10bp,adddesth=10bp]\%}%
\jdRect*[allowFX,adddestw=10bp,adddesth=10bp]
{\noindent\begin{minipage}{\bxSize}
\begin{Verbatim}[commandchars=!()]
\renewcommand{\overlayPresets}{\H{I}\BG{}\BC{blue}\S{D}}%
...
Jump to the \jdRect*[!textbf(allowFX),adddestw=10bp,adddesth=10bp]%
  {{\fitrpkg} Package!}
\end{Verbatim}
\end{minipage}}\eVerb
We redefined the \cs{overlayPresets} command, choosing an initial border of
blue, in this way, the document consumer sees that s/he can zoom in on the
text.

%\previewOn\viewMagWinOn
\jdRect[allowFX,height=4\baselineskip,width=340pt,adddestw=10,adddesth=10,lift=-\baselineskip]%
By the way, you can also zoom in on displayed verbatim text using \cs{jdRect} only.
% lift=16pt,shift=-15pt,
\begin{Verbatim}[xleftmargin=\amtIndent,commandchars=!()]
\renewcommand{\overlayPresets}{\H{I}\BG{}\BC{blue}\S{D}}%
...
Jump to the \jdRect*[!textbf(allowFX),adddestw=10bp,adddesth=10bp]%
  {{\fitrpkg} Package!}
\end{Verbatim}
This is done by explicitly enclosing the verbatim region as follows:
\begin{Verbatim}[xleftmargin=\amtIndent,commandchars=!()]
\jdRect[!textbf(allowFX),height=4\baselineskip,width=340pt,
  adddestw=10,adddesth=10,lift=-\baselineskip]%
By the way, ...
\end{Verbatim}
and, in this instance, is placed at the beginning of the sentence.\fitit
\end{example}


\subsection{Custom FX}

For the standard set up, where there is a push button that overlays the
content along with the viewing window it jumps to, there are two JavaScript
``hooks'' that can be exploited. These are document author defined.
\begin{itemize}
    \item \texttt{pbJmpHookCustom()} is an undefined JavaScript
        function that is executed after the jump to the viewing
        window. (It is enclosed in a \texttt{try/catch} construct that
        catches the error thrown.) The document author can define
        \texttt{pbJmpHookCustom()} to perform some action following the
        jump.
    \item \texttt{pbRestoreHookCustom()} is an undefined JavaScript
        function that is executed following the restored view action.
        The document author needs to make a custom definition if
        special effects are desired.
\end{itemize}
The distribution comes with two skeleton custom JavaScript functions, defined
in the files \texttt{jmpHook.js} and \texttt{restoreHook.js}. Study the two
built-in functions, \texttt{pbJmpHook()} and \texttt{pbRestoreHook()}, which
are part of this package, as a guide for writing your own special effects. To
use your custom JavaScript functions, place
\begin{Verbatim}[xleftmargin=\amtIndent]
\usepackage[js=jmpHook,js=restoreHook]{lmacs}
\end{Verbatim}
in the preamble of your document.\footnote{The alternative is to copy and
paste the \env{indDLJS} environments directly into the preamble.} The
\textsf{lmacs} package is a new package I made available to CTAN, it's a
simple package that imports files with extensions of \texttt{.def},
\texttt{.cfg}, and \texttt{.js}. We import \texttt{jmpHook.js} and
\texttt{restoreHook.js} using a key-value method, where the key is one of the
supported extensions; thus \texttt{js=jmpHook} will import the file
\texttt{jmpHook.js} if it exists. By the way, another nice feature of
\textsf{lmacs} is that you can prefix an exclamation point (!) to cancel out
that import, for example, if we wanted to use \texttt{jmpHook} but not
\texttt{restoreHook} specify,
\begin{Verbatim}[xleftmargin=\amtIndent]
\usepackage[js=jmpHook,!js=restoreHook]{lmacs}
\end{Verbatim}

\newtopic\noindent
Now, I simply must get back to my retirement. \dps

\end{document}