summaryrefslogtreecommitdiff
path: root/texmf-dist/doc/latex/cntdwn/cntdwn_man.tex
blob: 4948e6bd15ea43f1a227a619dde4c537a26c020f (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
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
% makeindex < aebpro_man.idx > aebpro_man.ind
\documentclass{article}
%\usepackage[fleqn]{amsmath}
\usepackage[
    web={centertitlepage,designv,tight,
        forcolorpaper,latextoc,pro},%usesf,
        eforms,aebxmp
]{aeb_pro}
%\usepackage{multicol}
\usepackage{array}
\usepackage[altbullet]{lucidbry}
\usepackage[shortcount,longcount]{cntdwn}
%\usepackage[usecmtt]{myriadpro}

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


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

\usepackage[active]{srcltx}

\def\expath{../examples}

\urlstyle{rm}

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

\DeclareDocInfo
{
    university={\AcroTeX.Net},
    title={The \texorpdfstring{\textsf{cntdwn} Package\\[1em]}{: }
        Creating short and long countdowns},
    author={D. P. Story},
    email={dpstory@acrotex.net},
    subject={Creating short and long countdowns},
    talksite={\url{www.acrotex.net}},
    version={1.0},
    keywords={countdown timer},
    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,afterskip=1sp}
\subsectionLayout{indent=-20pt,color=aeb,afterskip=1sp}
\subsubsectionLayout{indent=0pt,color=aeb,afterskip=1sp}
\subsubDefaultDing{\texorpdfstring{$\bullet$}{\textrm\textbullet}}

\newenvironment{eqComments}[1][\strut]{\smallskip\leftskip-\labelwidth
\item[]\textbf{\textcolor{blue}{#1}}}{\par\smallskip}

%--------------------
\setShortCntDwn{Timer1}{%
    length=1*\minutes,
    notify1=45*\seconds,
    notify2=30*\seconds,
    notify3=15*\seconds
}
\setLongCntDwn{NewYearsLocal}{%
    date=2011/01/01,
    time=00:01:00,
}
\setLongCntDwn{NewYearsCET}{%
    date=2011/01/01,
    time=00:01:00,
    tzoffset=+0100
}
\setClockTimer{LocalClock}{}
\setClockTimer{CESTClock}{tzoffset=+0200}
%--------------------


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

\definePath\bgPath{"C:/Users/Public/Documents/ManualBGs/Manual_BG_Print_AeB.pdf"}
\begin{docassembly}
\addWatermarkFromFile({
    bOnTop:false,
    cDIPath:\bgPath
});
\executeSave();
\end{docassembly}

\begin{document}

\maketitle

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

\section{Introduction}\label{s:intro}

The \textsf{cntdwn} package provides two types of countdowns, short and
long.
\begin{itemize}
    \item A short countdown, accessed through the \texttt{shortcount}
    option, is a countdown (or count-up) that is for a relatively short time
    period (less than a day). Such a countdown is designed for a talk (or
    presentation).
    \item A long countdown, accessed through the \texttt{longcount}
    option, is a countdown to a distant event, perhaps many days or even
    years in the future.
    \item As a bonus of long countdown, a clocks can be defined for local
    or time zones.
\end{itemize}
Each type of countdown (clocks excepted) has several events: (1) the main event, which is the
target of the countdown; (2) pre-events, events that occur \textit{before} the
occurrence of the main event; and (3) post-events, events that occur \textit{after} the
occurrence of the main event. Each event occurs at a definable instant in
time, and may have a (JavaScript) action associated with the event.

\section{Requirements and Sample files}

The \textsf{cntdwn} requires the \textsf{eforms} package, part of AeB (the
{\AcroTeX} eDucation Bundle), and, of course, the \textsf{hyperref} package.

The PDFs need to be viewed in Adobe Reader (or Acrobat), not some other nonconforming
PDF viewer that does not support document level JavaScript.

Basic examples are provided in the \texttt{examples} folder; advanced
examples can be found, in time, on my \href{http://www.math.uakron.edu/~dpstory/aebblog.html}{{\AEB} Blog} site,
\url{http://www.math.uakron.edu/~dpstory/aebblog.html}.

\section{The short countdown}\label{s:short}

To input the code for the short count, type either\\[6pt]
\hspace*{20pt}\verb!\usepackage{cntdwn}! or
\verb!\usepackage[shortcount]{cntdwn}!\\[6pt]
in the preamble.

We begin with an example of the default behavior of a short countdown:\\[6pt]
\hspace*{20pt}\cntdwnDisplay{Timer1}{.5in}{11bp}
\cntdwnStartT{Timer1}{11bp}{11bp}
\cntdwnPauseT{Timer1}{11bp}{11bp}
\cntdwnStopT{Timer1}{11bp}{11bp}\\[6pt]
To start the countdown, press the Start button (the second form field from
the left). The left-most field is a text field, the others are buttons.
The original idea behind this behavior was that this seemed a nice way to
do a count for a talk: (1) at a preselected time (45 seconds in this
example) the first button would turn green indicating to the speaker that
time is running out; (2) a little later, the second notification signal
appears, a yellow button (at 30 seconds); at a third notification time,
the third button starts blinking red (at 15 seconds), this tells the
speaker to wrap it up; (4) finally, at the end of the defined length of
the timer, the third button stops blinking indicating that the speaker's
time is up.

The buttons also play roles as controls over the counter, the three
buttons are \textbf{Start}, \textbf{Pause}, and \textbf{Stop}.  The user can press the \textbf{Pause} button to
pause the count (without taking away from his/her time), then restart it
by pressing the \textbf{Start} button.

The code for the above countdown consisted to two sets of lines. In the
preamble, we find,
\begin{verbatim}
    \setShortCntDwn{Timer1}{%
        length=1*\minutes,
        notify1=45*\seconds,
        notify2=30*\seconds,
        notify3=15*\seconds
    }
\end{verbatim}
This defines a timer name \texttt{Timer1}, with key-value pairs give
above. The length of the countdown is 1 minutes, following by the
defining of three notification times. The mean of these key-values is
clear in light of the above example.

The second line of code is the laying down of the timers themselves.
\begin{verbatim}
    \cntdwnDisplay{Timer1}{.5in}{11bp}
    \cntdwnStartT{Timer1}{11bp}{11bp}
    \cntdwnPauseT{Timer1}{11bp}{11bp}
    \cntdwnStopT{Timer1}{11bp}{11bp}
\end{verbatim}
The first argument of each is the name of the timer to use,
\texttt{Timer1},  in this case. All of these form fields are optional; if
none is included in the document, the timer ticks away
silently.\footnote{Why would anyone do this, you might ask?}

\subsection{Using \texorpdfstring{\protect\cs{setShortCntDwn}}{\CMD{setShortCntDwn}}
in the preamble}

For each short countdown timer, the \cs{setShortCntDwn} must be used to
define the properties of the timer.
\begin{dCmd*}{.6\linewidth}
\setShortCntDwn{<t_name>}{<key-values>}
\end{dCmd*}
\CmdDescription The command defines the properties of the countdown.
Internally, the command defines macros \cs{seconds}, \cs{minutes},
and \cs{hours}. For key-value pairs that take a time as its value, use
these commands to define the time value, for example, 20~minutes should be
denoted \texttt{20*\cs{minutes}} (use \texttt{*} for multiplication); for
1~minute and 30~seconds, you can type either \texttt{1*\cs{minutes}+\texttt{30*\cs{seconds}}}
or, alternatively, \texttt{1.5*\cs{minutes}}; and so on.

\PD The first parameter \texttt{<t\_name>} is a name you assign the timer. The
name must be unique among all timer names defined in the document. The
second parameter consists of key-value pairs, described below.
\KVP The second parameter takes several key-value pairs.
\begin{itemize}
    \item \texttt{length}: The length of the countdown, the default is 20
          minutes. (\texttt{20*\cs{minutes}})
    \item \texttt{stopwatch}: A Boolean, which if \texttt{true}, the counter counts up, like
          a stopwatch; he default is \texttt{false}, in this case the
          counter counts down. If stopwatch is not in the list of
          parameters, the counter counts down.
    \item \texttt{onfinish}: A choice key that determines the behavior of
          the counter when it reaches the main time event. Possible values
          are \texttt{stop} (the default) and \texttt{continue}. If
          \texttt{onfinish=continue}, the clock continues to count even
          after the main time has been attained.
    \item \texttt{endmsg}: When the timer reaches the main time event,
        the default behavior of the timer is to write a message to a
        text field created by the \cs{cntdwnEndTarget} command. The
        default message is ``This ends the Presentation, any
        questions?'' This message can be changed for this timer using
        the \texttt{endmsg} key. To globally change the message,
        redefine the command \cs{cnddwnDefaultEndMsg}. The
        redefinition of this command must occur before the expansion
        of any \cs{setShortCntDwn} command.
\end{itemize}
The next three keys take time as a value. Use the special macros
\cs{hours}, \cs{minutes}, and \cs{seconds}, as explained above.
\begin{itemize}
    \item \texttt{notify1}: The first notification time; the time
        before/after the main time event. The time is a prior time if
        the counter is counting down; and is a post time if the
        counter is counting up (\texttt{stopwatch=true}). The default is
        \texttt{5*\cs{minutes}}.
    \item \texttt{notify2}: The second notification time; the time
        before/after the main time event. The time is a prior time if
        the counter is counting down; and is a post time if the
        counter is counting up (\texttt{stopwatch=true}). The default is
        \texttt{3*\cs{minutes}}.
    \item \texttt{notify3}: The third notification time; the time
        before/after the main time event. The time is a prior time if
        the counter is counting down; and is a post time if the
        counter is counting up (\texttt{stopwatch=true}). The default is
        \texttt{1*\cs{minutes}}.
\end{itemize}
If \texttt{stopwatch=false}, the default, the counter is counting down to
the main time event (at time 0 seconds); in this case \texttt{notify1 >
notify2 > notify3}. If \texttt{stopwatch=false}, the counter is counting
up to the main time event (at time \texttt{length}); in this case
\texttt{notify1 < notify2 < notify3}. If these restrictions are not met,
the timer and notification may not be as expected.

The next four keys concern the actions that are taken at the four
notification times (\texttt{notify1}, \texttt{notify2}, \texttt{notify3},
and the main time event). These actions are in the form of JavaScript
functions, which may be re-defined by the document author to obtain custom
behaviors.
\begin{itemize}
    \item \texttt{event1}: A JavaScript function (which the document
    author can create) to handle the first notification event. The default
    event turns the \textbf{Start} button green and causes a beep to sound.
    \item \texttt{event2}:  A JavaScript function (which the document
    author can create) to handle the second notification event. The default
    event turns the \textbf{Pause} button yellow and causes a beep to sound.
    \item \texttt{event3}:  A JavaScript function (which the document
    author can create) to handle the third notification event. The default
    event causes the \textbf{Stop} button to blink red and causes a beep to sound.
    \item \texttt{endEvent}: When main time is reached (time 0 or
    \texttt{length}), this function turns the \texttt{Stop} button to solid red
    (non-blinking), and writes a message to the text field created by the
    command \cs{cntdwnEndTarget}.
    \item \texttt{startcolor}: The color used by the default \texttt{event1} function
    to color the \textbf{Start} button. The color is a JavaScript color; the
    default is \texttt{color.green}.
    \item \texttt{pausecolor}: The color used by the default \texttt{event2} function
    to color the \textbf{Pause} button. The color is a JavaScript color; the
    default is \texttt{color.yellow}.
    \item \texttt{stopcolor}: The color used by the default \texttt{event3} and
    \texttt{endEvent} functions to color the \textbf{Stop} button.
    The color is a JavaScript color; the default is \texttt{color.red}.
    \item \texttt{autorun}: A Boolean that determines whether the count
    begins when the page containing the counter is opened. The default is
    \texttt{false}.
    \item \texttt{refreshrate}: The refresh rate of the counter, the
    default is 1000 (milliseconds).
\end{itemize}

\subsection{Commands that go in the body}

The main field for the counter is \cs{cntdwnDisplay}, and it has three
supporting fields \cs{cntdwnStartT}, \cs{cntdwnPauseT}, and
\cs{cntdwnStopT}.

\begin{dCmd*}{\linewidth}
\cntdwnDisplay[<eforms_options>]{<t_name>}{<width>}{<height>}
\cntdwnStartT[<eforms_options>]{t_name}{<width>}{<height>}
\cntdwnPauseT[<eforms_options>]{t_name}{<width>}{<height>}
\cntdwnStopT[<eforms_options>]{t_name}{<width>}{<height>}
\end{dCmd*}
\PD The first optional parameter is used to change the appearance of the
fields (these fields use the \textsf{eforms} package). The second
parameter is the name of a timer (\texttt{<t\_name>}) that has already been
defined by \cs{setShortCntDwn}. The last two parameters sets the width and
height of the form fields.
\CmdDescription All four of these fields are optional (no JavaScript
exceptions are thrown if they do not exist). \cs{cntdwnDisplay} show the
countdown of the timer; \cs{cntdwnStartT} is the start button,
\cs{cntdwnPauseT} is the pause button, and \cs{cntdwnStopT} is the stop
button. The capital letter \texttt{T} indicates that these buttons are the
\texttt{T}arget of the default event functions. Below, we describe
non-target start, pause, and stop buttons.

When the timer reaches it main time event (time 0 for a
countdown clock, and time \texttt{length} for a count-up clock), the default
endEvent writes message to the multiline text field created by
\cs{cntdwnEndTarget}.

\begin{dCmd*}{\linewidth}
\cntdwnEndTarget[<eforms_options>]{t_name}{<width>}{<height>}
\end{dCmd*}
\PD The four parameters are the same as described above for the
\cs{cntdwnDisplay} field, for example. This field is optional, if it does
not exist, no exception is thrown.\footnote{Actually, an exception is
thrown, but it is ``caught'' so no harm is done.}

The \textsf{cntdwn} package also provides three form field buttons for
starting, pausing, and stopping the target count. The parameters are the
same as those of the `\texttt{T}' counterparts.
\begin{dCmd*}{\linewidth}
\cntdwnStart[<eforms_options>]{t_name}{<width>}{<height>}
\cntdwnPause[<eforms_options>]{t_name}{<width>}{<height>}
\cntdwnStop[<eforms_options>]{t_name}{<width>}{<height>}
\end{dCmd*}

\section{The long countdown}\label{s:long}

A long countdown is one where the main countdown event is in the distant
future. Since a short countdown is designed for less than one day, a long
countdown is for times greater than a day.

As an example, let us countdown to New Year's Day, which is 1~second after
midnight.\\[6pt]
\hspace*{20pt}\lcntdwnDisplay{NewYearsLocal}{3.5in}{11bp}\\[6pt]
This countdown is in \emph{local time}. No matter where you are in the
world, in whatever time zone, the countdown reflect the time until your
New Year's Day.

The time until my friend J\"{u}rgen celebrates New Year's Day is shown
below:\\[6pt]
\hspace*{20pt}\lcntdwnDisplay{NewYearsCET}{3.5in}{11bp}\\[6pt]
Note that there is a difference in the count between the two counters, probably in
the hour position; this is due difference between his timezone offset, and yours.
This counter gives the time until my friend celebrates
the New Year; it should read the same throughout the world, for he
celebrates at a unique time in the world.

As with the short countdown, to obtain such clocks we must set the
clocks parameters in the preamble (using the \cs{setLongCntDwn} command),
and place the countdown clock anywhere we like in the body of the
document (using \cs{lcntdwnDisplay}).

In the preamble, we have

\begin{verbatim}
    \setLongCntDwn{NewYearsLocal}{%
        date=2011/01/01,
        time=00:01:00,
    }
    \setLongCntDwn{NewYearsCEST}{%
        date=2011/01/01,
        time=00:01:00,
        tzoffset=+0100
    }
\end{verbatim}
The first one sets the parameters of the local clock. The \texttt{date} and \texttt{time}
are specified in the obvious way. We set the counter to run and pause
automatically. The parameters for the Central European New Year clock are the same,
with one exception; I've included a value for the \texttt{tzoffset} key
(time zone offset), this is \texttt{+0100} (in Germany during the Winter).

In the body of the document, we place the countdown clocks,
\begin{verbatim}
    \lcntdwnDisplay{NewYearsLocal}{3.5in}{11bp}
    ...
    \lcntdwnDisplay{NewYearsCET}{3.5in}{11bp}
\end{verbatim}
As with the short count, we reference the counter parameters through the
name of the counter, as defined using \cs{setLongCntDwn}.

\subsection{Using \texorpdfstring{\protect\cs{setLongCntDwn}}{\CMD{setShortCntDwn}}
in the preamble}

For each long countdown timer, the \cs{setLongCntDwn} must be used to
define the properties of the timer.
\begin{dCmd*}{.6\linewidth}
\setLongCntDwn{<t_name>}{<key-values>}
\end{dCmd*}
\CmdDescription The command defines the properties of the countdown.
Internally, the command defines macros \cs{seconds}, \cs{minutes},
\cs{hours}, \cs{weeks}, and \cs{years}. For key-value pairs that take a time as its value, use
these commands to define the time value, for example, 20 minutes should be
denoted \texttt{20*\cs{minutes}} (use \texttt{*} for multiplication); for
2 weeks and 3 days, you can type either \texttt{2*\cs{weeks}+\texttt{3*\cs{days}}}
or \texttt{13*\cs{days}}; and so on.

\PD The first parameter \texttt{<t\_name>} is a name you assign the timer. The
name must be unique among all timer names defined in the document. The
second parameter consists of key-value pairs, described below.
\KVP The second parameter takes several key-value pairs.
\begin{itemize}
    \item \texttt{date}: The date of the event. The value of the \texttt{date} key
    has the form \texttt{YYYY/MM/DD}. If \texttt{date} key is not specified then
    the default date of \texttt{1970/01/01} is used and a warning message is
    written to the log. Valid variations on the \texttt{date} key are
    \texttt{YYYY} (in which case the default month and day values are
    used,  \texttt{YYYY/01/01}, and \texttt{YYYY/MM} (again, the
    default day is used \texttt{YYYY/MM/01}). Year must be specified with
    four numbers, and the month and day with two numbers. (The first month
    is 01.)
    \item \texttt{time}: The time of the event on the specified date. The
    format for the value of time is \texttt{HH:mm:SS} (hours, minutes,
    seconds). All time components are specified with two digits, if
    specified at all. The default value of \texttt{00} is taken for any
    missing component. If no \texttt{time} is specified then
    \texttt{00:00:00} is used; if \texttt{HH} only is specified, then the
    value for time is \texttt{HH:00:00}; if \texttt{HH:mm} is specified,
    then the value of time is \texttt{00:mm:00}.
    \item \texttt{tzoffset}: The time zone offset of the time of the
    event. If \texttt{tzoffset} is not specified, then time is interpreted
    as local time.  The format for \texttt{tzoffset} is \texttt{Z|OHHmm},
    where \texttt{Z} means that local time is equal to UT (Universal
    Time). For the \texttt{OHHmm} pattern, the \texttt{O} is \texttt{+} (plus) or
    \texttt{-} (minus); a \texttt{+} (plus) means that local time is later than
    UT, and a \texttt{-} (minus) means that local time is earlier than UT. For
    example CST (Central Standard Time) is \texttt{-0600} while CET (Central European Time) is
    \texttt{+0100}. See \url{http://www.timeanddate.com} for time zone
    information. \texttt{HH} is the number of hours offset from UT and \texttt{mm} is the
    number of minutes (some time zones are measured in hours and minutes,
    for example, Australian Central Standard Time is \texttt{+0930}).
    \item \texttt{refreshrate}: The refresh rate of the counter, the
    default is 1000 (milliseconds).
    \item \texttt{autorun}: A Boolean that determines whether the count
    begins when the page containing the counter is opened. The default is
    \texttt{true}.
    \item \texttt{autopause}: A Boolean that determines whether the count
    is paused when the page containing the counter is closed. The default is
    \texttt{true}.
    \item \texttt{autorunenabled}: A Boolean that enables the \texttt{autorun}
    feature. The default value of this key is \texttt{true}. The purpose
    of this key-value is to turn off \texttt{autorun} dynamically (through
    JavaScript). The timer object that keeps all timer information has a
    key named \texttt{bAutorunEnabled}. If the name of the timer is
    \texttt{MyTimer}, and you execute
    \texttt{\_oMyTimer.bAutorunEnabled=false}, the timer, if already paused,
    \emph{will not start} (automatically) when the page containing the timer is
    opened again. For an example of usage, see the file
    \texttt{armistice\_day.pdf}, titled ``The cntdwn Package: Handling Notification Events for the Long Countdown
    Timer, Remembrance Day,'' available on the \href{http://www.math.uakron.edu/~dpstory/aebblog.html}{AeB Blog site}.
    \item \texttt{notify1}, \texttt{notify2}, \texttt{notify3}:
        Leading up to the main time event are three \emph{pre-events} that
        occur at times \texttt{notify1 > notify2 > notify3}
        \emph{before} the main event. These are the first, second, and
        third notification event times. The times are relative to the main
        event, so if \texttt{notify1=1*\string\weeks}, then the
        first notification event occurs 1 week \emph{before} the
        main event.
    \item \texttt{notify5}, \texttt{notify6}, \texttt{notify7}:
        Following the main time event are three \emph{post-events}
        that occur at times \texttt{notify5 < notify6 > notify7}
        \emph{after} the main event. These are the fifth, sixth, and
        seventh notification event times.\footnote{You may ask about
        the fourth notification event, that event is the main time
        event, the event that occurs when the countdown reaches 0.}
        The times are relative to the main event, so if
        \texttt{notify5=5*\string\hours}, then the fifth notification
        event (the first after the main event) occurs 5 hours
        \emph{after} the main event.
    \item \texttt{eventhandler}: When the timer reaches any of the
        seven notification times, a event handler function is
        launched, the default function is \texttt{\_NoOpt}. The
        \texttt{\_NoOpt} does nothing. The document author ca define
        his/her own event handler using this key.

    An event handler should take three parameters \texttt{doc},
    \texttt{cTimer}, and \texttt{nEvent}. Use the \texttt{insDLJS} environment
    to define your custom handler. A very simple example is
\begin{verbatim}
\begin{insDLJS}[myEventHandler]{dps}{My Event Handlers}
function myEventHandler (doc,cTimer,nEvent) {
    console.show();
    console.println("Event number " + nEvent + " just occurred);
}
\end{insDLJS}
\end{verbatim}
and type \texttt{eventhandler=myEventHandle} as part of the
key-values of \cs{set\-Long\-Cnt\-Dwn}.
    \item \texttt{endtimecolor}: When main time event is reached (0
    seconds), the color of the display is changed to the JavaScript color
    determined by this key. The default is \texttt{color.red}.
    \item \texttt{displayfunc}: This JavaScript function displays the
    count; the default display function is \texttt{\_defaultLDisplayFunc},
    it takes parameters\vspace{3pt}
\begin{Verbatim}[fontsize=\small]
function _defaultLDisplayFunc(f,nYears,nDays,nHours,nMinutes,nSeconds)
\end{Verbatim}
where \texttt{f} is the field object of the display field, the meaning of
the other parameters is obvious.

The default display function uses the strings year, years, day, days,
hours, hour, minutes, minute, seconds, second. For localization of these
strings, the document author may redefine the commands
\begin{dCmd*}{.6\linewidth}
\newcommand{\cntdwnYear}{year}
\newcommand{\cntdwnYears}{years}
\newcommand{\cntdwnDay}{day}
\newcommand{\cntdwnDays}{day}
\newcommand{\cntdwnHour}{hour}
\newcommand{\cntdwnHours}{hours}
\newcommand{\cntdwnMinute}{minute}
\newcommand{\cntdwnMinutes}{minutes}
\newcommand{\cntdwnSecond}{second}
\newcommand{\cntdwnSeconds}{seconds}
\end{dCmd*}
    \item \texttt{onfinish}: A choice key that determines the behavior
        of the counter when it reaches the main time event. Possible
        values are \texttt{stop} and \texttt{continue} (the default).
        If \texttt{onfinish=stop}, the clock stops the count
        when main event time is attained (when the timer reaches 0
        seconds).
    \item \texttt{endmsg}: When the timer reaches the main time event
        and \texttt{onfinish=stop}, the default behavior
        is to write a message to a text field created by the
        \cs{lcntdwnDisplay} command. The default message is ``The time
        has expired.'' This message can be changed for this timer using
        the \texttt{endmsg} key. To globally change the message,
        redefine the command \cs{lcnddwnDefaultEndMsg}. The
        redefinition of this command must occur before the expansion
        of any \cs{setLongCntDwn} command.
\end{itemize}

\subsection{Commands that go in the body}

In the body of the document there are several commands used with the long
countdown timer.

\begin{dCmd*}{\linewidth}
\lcntdwnDisplay[<eform_options>]{<t_name>}{<width>}{<height>}
\end{dCmd*}

\CmdDescription The command creates a text field that holds the current
countdown.

\PD The first optional parameter is used to change the appearance of the
field (these field use the \textsf{eforms} package). The second
parameter is the name of a timer (\texttt{<t\_name>}) that has already been
defined by \cs{setLongCntDwn}. The last two parameters sets the width and
height of the form fields.

\begin{dCmd*}{\linewidth}
\lcntdwnToggle[<eform_options>]{<t_name>}{<width>}{<height>}
\end{dCmd*}

\CmdDescription The command creates a push button field that is used to
toggle the count on and off (start and pause). Normally, this button is
not needed, but there may be situations that it may be useful.

\PD The first optional parameter is used to change the appearance of the
field (these field use the \textsf{eforms} package). The second
parameter is the name of a timer (\texttt{<t\_name>}) that has already been
defined by \cs{setLongCntDwn}. The last two parameters sets the width and
height of the form fields.

\newtopic For example, the button \kern1bp\lcntdwnToggle{NewYearsLocal}{11bp}{11bp}\kern1bp
\lcntdwnDisplay{NewYearsLocal}{2.5in}{11bp}\space\kern1bp
will toggle the New Years Day counter.

The verbatim listing is as follows:
\begin{Verbatim}[fontsize=\small]
For example, the button \lcntdwnToggle{NewYearsLocal}{11bp}{11bp}\kern1bp
\lcntdwnDisplay{NewYearsLocal}{2.5in}{11bp} will toggle the New Years
Day counter.
\end{Verbatim}

\subsection{The clock timer}

I was just getting to wrap up this package, when I decided that it
wouldn't be too much trouble to define clock timers. I include the code in
as part of the \texttt{longcount} option because the code for the clock is
derived from the \texttt{longcount} count. Multiple clocks can be
activated at once, both clocks in the local time zone, as well as other
time zones, as shown below.

\begin{tabular}{rcc}
&\textbf{Time}&\textbf{Date}\\[3bp]
Local Time:&
\cntdwnclocktime{LocalClock}{1in}{11bp}&
\cntdwnclockdate{LocalClock}{1in}{11bp}\\[3bp]
CEST:&
\cntdwnclocktime{CESTClock}{1in}{11bp}&
\cntdwnclockdate{CESTClock}{1in}{11bp}%
\end{tabular}

\newtopic\textbf{Note:}
You can specify the time zone you want your clock to function in, there
is, however, no way to automatically adjust time zone when there is a
change from standard to/from summer time.\footnote{The statement has
limited truth to it. If the dates are known when a given time zone changes
UT offsets (between standard and summer/daylight savings time), you can
write some JavaScript to make this adjustment dynamically. The problem is
the dates/times may change from year to year. The ultimate solution is
have access to a time/date database/server.}

For these two clocks, we need to execute the command \cs{setClockTimer} in
the preamble.
\begin{verbatim}
    \setClockTimer{LocalClock}{}
    \setClockTimer{CESTClock}{tzoffset=+0200}
\end{verbatim}
The first parameter is the name of the clock and the second takes
key-value pairs. For the \texttt{LocalClock}, we take the defaults,
for the \texttt{CESTClock}, we set the time zone offset from UTC to CEST
(Central European Summer Time).

The code for the clocks themselves that appear above follows:

\begin{verbatim}
\begin{tabular}{rcc}
&\textbf{Time}&\textbf{Date}\\[3bp]
Local Time:&
\cntdwnclocktime{LocalClock}{1in}{11bp}&
\cntdwnclockdate{LocalClock}{1in}{11bp}\\[3bp]
CEST:&
\cntdwnclocktime{CESTClock}{1in}{11bp}&
\cntdwnclockdate{CESTClock}{1in}{11bp}%
\end{tabular}
\end{verbatim}
The current time is displayed by \cs{cntdwnclocktime} and the date is
displayed by \cs{cntdwnclockdate}.

\subsubsection{Using \texorpdfstring{\protect\cs{setClockTimer}}{\CMD{setClockTimer}}
in the preamble}

For each clock , the \cs{setClockTimer} must be used to
define the properties of the clock.
\begin{dCmd*}{.6\linewidth}
\setClockTimer{<t_name>}{<key-values>}
\end{dCmd*}
\CmdDescription The command defines the properties of the clock.

\PD The first parameter \texttt{<t\_name>} is a name you assign the clock. The
name must be unique among all timer names defined in the document. The
second parameter consists of key-value pairs, described below.
\KVP The second parameter takes several key-value pairs.
\begin{itemize}
    \item \texttt{tzoffset}: The time zone offset of the time of the
    event. If \texttt{tzoffset} is not specified, then time is interpreted
    as local time.  The format for \texttt{tzoffset} is \texttt{Z|OHHmm},
    where \texttt{Z} means that local time is equal to UT (Universal
    Time). For the \texttt{OHHmm} pattern, the \texttt{O} is \texttt{+} (plus) or
    \texttt{-} (minus); a \texttt{+} (plus) means that local time is later than
    UT, and a \texttt{-} (minus) means that local time is earlier than UT. For
    example CST (Central Standard Time) is \texttt{-0600} while CET (Central European Time) is
    \texttt{+0100}. See \url{http://www.timeanddate.com} for time zone
    information. \texttt{HH} is the number of hours offset from UT and \texttt{mm} is the
    number of minutes (some time zones are measured in hours and minutes,
    for example, Australian Central Standard Time is \texttt{+0930}).
    \item \texttt{refreshrate}: The refresh rate of the counter, the
    default is 1000 (milliseconds).
    \item \texttt{autorun}: A Boolean that determines whether the count
    begins when the page containing the counter is opened. The default is
    \texttt{true}.
    \item \texttt{autopause}: A Boolean that determines whether the count
    is paused when the page containing the counter is closed. The default is
    \texttt{true}.
    \item \texttt{currtimefunc}: When a long count is active, \textsf{cntdwn}
    provides the current time and date.  The document author can design
    a custom display through this key. The default value of this key is
    \texttt{\_defaultTimeDateFunc}, the definition of which is
\begin{verbatim}
function _defaultTimeDateFunc(oTime,cTimer) {
    try{ this.getField(cTimer+".clock.time").value
        =util.printd("H:MM:ss",oTime); } catch(e) {};
    try { this.getField(cTimer+".clock.date").value=
        util.printd("mm/dd/yyyy", oTime); } catch(e) {};
\end{verbatim}
where \texttt{oTime} is the Date object containing current time/date.
\end{itemize}


\subsubsection{Commands that go in the body}

In the body of the document there are several commands used with the long
countdown timer.

\begin{dCmd*}{\linewidth}
\cntdwnclocktime[<eform_options>]{<t_name>}{<width>}{<height>}
\cntdwnclockdate[<eform_options>]{<t_name>}{<width>}{<height>}
\end{dCmd*}

\CmdDescription Each command creates a read-only text field, the first
displays the time, and second displays the date.
countdown.

\PD The first optional parameter is used to change the appearance of the
field (these field use the \textsf{eforms} package). The second
parameter is the name of a timer (\texttt{<t\_name>}) that has already been
defined by \cs{setClockTimer}. The last two parameters sets the width and
height of the form fields.

\begin{dCmd*}{\linewidth}
\clockToggle[<eform_options>]{<t_name>}{<width>}{<height>}
\end{dCmd*}

\CmdDescription The command creates a push button field that is used to
toggle the clock on and off (start and pause). Normally, this button is
not needed, but there may be situations that it may be useful.

\PD The first optional parameter is used to change the appearance of the
field (these field use the \textsf{eforms} package). The second
parameter is the name of a timer (\texttt{<t\_name>}) that has already been
defined by \cs{setClockTimer}. The last two parameters sets the width and
height of the form fields.

\newtopic\textbf{Note:} It is easy to create a single button to toggle all
clocks, or a selection of clocks, but this button is not provided with
this package.

\bigskip

That's all for now, I simply must get back to my retirement. {\dps}

\end{document}