Debian Codegraph @

texmf-dist/source/latex/cooltooltips/cooltooltips.dtx

raw
1 % \iffalse meta-comment
2 %
3 % Copyright (C) 2006-2021 by Scott Pakin <[email protected]>
4 % -------------------------------------------------------------
5 %
6 % This file may be distributed and/or modified under the
7 % conditions of the LaTeX Project Public License, either version 1.3c
8 % of this license or (at your option) any later version.
9 % The latest version of this license is in:
10 %
11 % http://www.latex-project.org/lppl.txt
12 %
13 % and version 1.3c or later is part of all distributions of LaTeX
14 % version 2008/05/04 or later.
15 %
16 % \fi
17 %
18 % \iffalse
19 %<*driver>
20 \ProvidesFile{cooltooltips.dtx}
21 %</driver>
22 %<package>\NeedsTeXFormat{LaTeX2e}[2001/06/01]
23 %<package>\ProvidesPackage{cooltooltips}
24 %<*package>
25 [2021/08/08 v1.1 Cool PDF tooltips]
26 %</package>
27 %
28 %<*driver>
29 \documentclass{ltxdoc}
30 \usepackage{cooltooltips}
31 \usepackage{graphicx}
32 \usepackage{color}
33 \usepackage{hyperref}
34 \EnableCrossrefs
35 \CodelineIndex
36 \RecordChanges
37 \begin{document}
38 \sloppy
39 \DocInput{cooltooltips.dtx}
40 \PrintChanges
41 \PrintIndex
42 \end{document}
43 %</driver>
44 % \fi
45 %
46 % \CheckSum{216}
47 %
48 % \CharacterTable
49 % {Upper-case \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
50 % Lower-case \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
51 % Digits \0\1\2\3\4\5\6\7\8\9
52 % Exclamation \! Double quote \" Hash (number) \#
53 % Dollar \$ Percent \% Ampersand \&
54 % Acute accent \' Left paren \( Right paren \)
55 % Asterisk \* Plus \+ Comma \,
56 % Minus \- Point \. Solidus \/
57 % Colon \: Semicolon \; Less than \<
58 % Equals \= Greater than \> Question mark \?
59 % Commercial at \@ Left bracket \[ Backslash \\
60 % Right bracket \] Circumflex \^ Underscore \_
61 % Grave accent \` Left brace \{ Vertical bar \|
62 % Right brace \} Tilde \~}
63 %
64 %
65 % \changes{v1.0}{2006/03/07}{Initial version}
66 % \changes{v1.1}{2021/08/08}{Enable support for Lua\string\LaTeX}
67 %
68 % \GetFileInfo{cooltooltips.dtx}
69 %
70 % \DoNotIndex{\@ifundefined,\@tempboxa,\@tempcnta,\@tempcntb,\@tempdima}
71 % \DoNotIndex{\@tempdimb,\@tempdimc,\DeclareRobustCommand,\MessageBreak,\\}
72 % \DoNotIndex{\active,\addtolength,\advance,\begingroup,\bgroup,\catcode}
73 % \DoNotIndex{\csname,\def,\dp,\edef,\egroup,\else,\endcsname,\endgroup}
74 % \DoNotIndex{\expandafter,\fi,\gdef,\hbox,\hspace,\ht,\ifnum,\immediate}
75 % \DoNotIndex{\let,\makebox,\mbox,\newcommand,\noexpand,\paperwidth}
76 % \DoNotIndex{\pdflastannot,\pdflastobj,\pdflastxform,\renewcommand}
77 % \DoNotIndex{\savebox,\setbox,\setcounter,\setlength,\space,\stepcounter}
78 % \DoNotIndex{\strip@pt,\the,\thepage,\usebox,\wd,\xdef}
79 %
80 % ^^A Define the document's metadata.
81 % \title{The \cool\ package\thanks{This document
82 % corresponds to \textsf{cooltooltips}~\fileversion, dated \filedate.}}
83 % \author{Scott Pakin \\ \texttt{[email protected]}}
84 % \hypersetup{^^A
85 % pdftitle={The cooltooltips package},
86 % pdfauthor={Scott Pakin <[email protected]>},
87 % pdfsubject={Including cool-looking tooltips in a pdfLaTeX document},
88 % pdfkeywords={tooltips, popups, pdfLaTeX, LaTeX package, PDF}
89 % }
90 %
91 % ^^A Define some logical styles and helper macros to use throughout
92 % ^^A the documentation.
93 % \let\acro=\textsc
94 % \newcommand*{\pdfterm}[1]{\textsf{#1}}
95 % \let\pkgname=\textsf
96 % \newcommand*{\cool}{\pkgname{cooltooltips}}
97 %
98 % ^^A The following definition was copied more-or-less verbatim
99 % ^^A from ltxguide.cls.
100 % \makeatletter
101 % \DeleteShortVerb{\|}
102 % \newenvironment{decl}
103 % {\par\small\addvspace{4.5ex plus 1ex}^^A
104 % \vskip -\parskip
105 % \noindent\hspace{-\leftmargini}^^A
106 % \begin{tabular}{|l|}\hline\ignorespaces}^^A
107 % {\\\hline\end{tabular}\nobreak\par\nobreak
108 % \vspace{2.3ex}\vskip -\parskip}
109 % \MakeShortVerb{\|}
110 % \makeatother
111 %
112 % ^^A The following were copied blindly from the UK TeX FAQ.
113 % \renewcommand{\topfraction}{.85}
114 % \renewcommand{\bottomfraction}{.7}
115 % \renewcommand{\textfraction}{.15}
116 % \renewcommand{\floatpagefraction}{.66}
117 % \renewcommand{\dbltopfraction}{.66}
118 % \renewcommand{\dblfloatpagefraction}{.66}
119 % \setcounter{topnumber}{9}
120 % \setcounter{bottomnumber}{9}
121 % \setcounter{totalnumber}{20}
122 % \setcounter{dbltopnumber}{9}
123 %
124 %
125 % \maketitle
126 %
127 % \section{Introduction}
128 %
129 % The \cool\ package enables a document to contain hyperlinks that pop
130 % up a brief tooltip when the mouse moves over them and also open a
131 % small window containing additional text. \cool\ works only with
132 % pdf\LaTeX\@. Furthermore, the tooltips that \cool\ produces are much
133 % less cool when viewed under older versions of Acrobat~($<7.0$) or most
134 % other \acro{pdf} readers because they don't pop up the extra, small
135 % window. \cooltooltip[0 0 1]{Example}{This is an example of a cool
136 % tooltip. Pretty cool, eh?}{http://www.ctan.org/}{Visit CTAN on the
137 % Web}{This text\strut} is an example of a cool tooltip (assuming
138 % you're viewing this document with a sufficiently capable \acro{pdf}
139 % reader). Move your mouse pointer over it and watch what happens.
140 % Then, click on the link. If your \acro{pdf} reader is properly
141 % configured it should launch a Web browser and send it to the
142 % \acro{ctan} home page.
143 %
144 % If the \cool\ popup mechanism causes problems with your browser you
145 % can \cooltooltiptoggle{\fcolorbox{blue}{white}{click here}} to disable
146 % popups. (Click again to re-enable them.) Regardless of whether
147 % popups are enabled the tooltip and hyperlink mechanisms should continue
148 % to function.
149 %
150 % The cool tooltip shown above was created with the following code:
151 %
152 % \begin{verbatim}
153 % \cooltooltip
154 % [0 0 1]
155 % {Example}
156 % {This is an example of a cool tooltip. Pretty cool, eh?}
157 % {http://www.ctan.org/}{Visit CTAN on the Web}
158 % {This text\strut}
159 % \end{verbatim}
160 %
161 % The ``click here'' button was created as follows:
162 %
163 % \begin{verbatim}
164 % \cooltooltiptoggle{\fcolorbox{blue}{white}{click here}}
165 % \end{verbatim}
166 %
167 %
168 % \section{Usage}
169 %
170 % \begin{decl}
171 % \texttt{\string\cooltooltip} \oarg{popup color} \oarg{link color} \\
172 % \marg{subject} \marg{message} \marg{\acro{url}} \marg{tooltip}
173 % \marg{text}
174 % \end{decl}
175 % \bgroup
176 % \def\PrintDescribeMacro#1{}
177 % \DescribeMacro{\cooltooltip}
178 % \egroup
179 % The |\cooltooltip| macro takes two optional arguments and five
180 % mandatory arguments. The first argument, \meta{popup color}, is the
181 % color of the box containing the textual message to display and is
182 % specified as a ``\meta{red} \meta{green} \meta{blue}'' triple with
183 % each element ranging from 0~(off) to 1~(on). If omitted, \meta{popup
184 % color} defaults to ``\texttt{0 1 0}''~(bright green). The second
185 % argument, \meta{link color}, is the color of the frame drawn around
186 % the hyperlink. If omitted, it defaults to the same value as
187 % \meta{popup color}. \meta{subject} is a text string to display as the
188 % subject of the popup window. \meta{message} is a text string to
189 % display within the popup window. There's no provision for scrolling
190 % the popup window so \meta{message} should be kept reasonably short.
191 % When a user clicks on the hyperlink, the \acro{pdf} browser should
192 % take him to \acro{url} \meta{\acro{url}}. While the mouse is hovering
193 % over the link, the \meta{tooltip} text is displayed. Finally,
194 % \meta{text} is the text of the hyperlink and can be composed of
195 % arbitrary \LaTeX\ text, including mathematics, graphics, etc.
196 %
197 % The width of the hyperlink frame is governed by |\fboxrule| and the
198 % space separating the frame from \meta{text} is governed by |\fboxsep|.
199 % Use \LaTeX's |\setlength| command to assign values to those registers.
200 %
201 % Figure~\ref{fig:ctip-arguments} illustrates how Adobe Reader~7.0
202 % displays \meta{subject}, \meta{message}, \meta{tooltip}, and
203 % \meta{text} with a \meta{popup color} of cyan (\texttt{0 1 1}) and a
204 % \meta{link color} of magenta (\texttt{1 0 1}). (The \acro{url}
205 % specified by \meta{\acro{url}} does not appear on screen.)
206 %
207 % \begin{figure}[tbp]
208 % \includegraphics[width=\linewidth]{example}
209 % \caption{Illustration of \texttt{\bslash cooltooltip} arguments}
210 % \label{fig:ctip-arguments}
211 % \end{figure}
212 %
213 % Because \cool\ uses \LaTeX's |\label|\slash|\pageref| mechanisms for
214 % accurately determining the current page, documents built using \cool\
215 % will need to be run through |pdflatex| at least twice. (|pdflatex|
216 % will issue the standard ``\texttt{Rerun to get cross-references
217 % right}'' message as a reminder.)
218 %
219 % \begin{decl}
220 % \texttt{\string\cooltooltiptoggle} \marg{text}
221 % \end{decl}
222 % \bgroup
223 % \def\PrintDescribeMacro#1{}
224 % \DescribeMacro{\cooltooltiptoggle}
225 % \egroup
226 %
227 % The popup mechanism used by \cool\ is extremely fragile. \cool\ has
228 % to manually transfer focus among the hyperlink, popup, and a per-page
229 % invisible form field. (See Section~\ref{sec:widgets} for details and
230 % an explanation of why this trickery is necessary.) If the browser
231 % window is so small that the popup overlaps the mouse pointer, the
232 % popup will flicker rapidly and impede the use of the hyperlink.
233 % Because this behavior is disturbing to readers of the document, the
234 % author may want to provide the reader with the ability to disable
235 % popups.
236 %
237 % The |\cooltooltiptoggle| command converts its \meta{text} argument to
238 % a toggle button. Pressing the button suppresses all popups in the
239 % document. Pressing it again re-enables popups.
240 %
241 %
242 % \StopEventually{^^A
243 % \section{Future work}
244 %
245 % There's unlikely to be any future work on \cool; consider it to be a
246 % ``dead'' package. Yes, I know that someone will want a
247 % \texttt{dvipdfm} port and someone else will want finer-grained control
248 % over which of \meta{subject}, \meta{message}, \meta{\acro{url}}, and
249 % \meta{tooltip} are utilized and a third person will request a less
250 % sloppy implementation of the code. However, I wrote \cool\ primarily
251 % as a one-time-use package for my personal use; I needed a way to
252 % implement fancy popups for my Visual \LaTeX\ FAQ document and
253 % initially had no intention of distributing the popup mechanism as a
254 % separate package. If you find \cool\ useful in its current form,
255 % that's great. If not, then you're on your own for fixing it; I don't
256 % plan on spending any significant time maintaining the package.
257 %
258 %
259 % \section{License agreement}
260 % \label{sec:license}
261 %
262 % \begin{center}
263 % Copyright \textcopyright{} 2006--2021
264 % by Scott Pakin \texttt{<[email protected]>}
265 % \end{center}
266 %
267 % \noindent
268 % This file may be distributed and/or modified under the conditions of
269 % the \LaTeX{} Project Public License, either version~1.3c of this
270 % license or (at your option) any later version. The latest version of
271 % this license is in \url{http://www.latex-project.org/lppl.txt} and
272 % version~1.3c or later is part of all distributions of \LaTeX{} version
273 % 2008/05/04 or later.
274 % }
275 %
276 % \section{Implementation}
277 % \label{sec:implementation}
278 %
279 % This section presents the commented \LaTeXe\ source code for the
280 % \cool\ package. Each cool tooltip is implemented in terms of two
281 % \acro{pdf} \pdfterm{Annot} objects. The popup is a \pdfterm{Text}
282 % annotation with an invisible appearance. The popup trigger/tooltip is
283 % both a \pdfterm{Widget} annotation and \pdfterm{Btn} pushbutton field.
284 % JavaScript code implements the popup open/close logic. For
285 % compatibility with \acro{pdf} browsers that don't support
286 % \pdfterm{Widget} annotations we also include an ordinary
287 % \pdfterm{Link} annotation.
288 %
289 % Section~\ref{sec:implementation} is structured as follows.
290 % Section~\ref{sec:acroform} marks the document as a \acro{pdf} form,
291 % which is necessary for using fields and widgets.
292 % Section~\ref{sec:text} defines macros for creating a \pdfterm{Text}
293 % annotation, \cool's popup mechanism. Most of \cool's behavior is
294 % defined in Section~\ref{sec:widgets}. All \acro{pdf}
295 % fields/\pdfterm{Widget}s are specified in that section. The
296 % |\cooltooltip| command proper is defined in
297 % Section~\ref{sec:user-commands}. Finally,
298 % Section~\ref{sec:sanity-checks} includes a tiny amount of extra code
299 % to verify that the document is being built under pdf\LaTeX\@. If not,
300 % it disables all \cool\ functionality but enables the document to build
301 % without it.
302 %
303 % \bigskip
304 %
305 % Because \cool\ works only with pdf\LaTeX---or Lua\LaTeX\ with the
306 % \pkgname{luatex85} compatibility package---and only in \acro{pdf}
307 % mode, we load the \textsf{iftex} package up front to simplify testing
308 % for the execution environment.
309 % \begin{macrocode}
310 \RequirePackage{iftex}
311 \ifluatex
312 \RequirePackage{luatex85}
313 \fi
314 % \end{macrocode}
315 %
316 % \begin{macro}{\ifcoolpdf}
317 % \begin{macro}{\coolpdftrue}
318 % \begin{macro}{\coolpdffalse}
319 % We define a new test, |\ifcoolpdf|, which is true only when \TeX\ is
320 % in \acro{pdf} mode and only when pdf\LaTeX\ or Lua\LaTeX~+
321 % \pkgname{luatex85} is being used to build the document.
322 % \begin{macrocode}
323 \newif\ifcoolpdf
324 \ifpdf
325 \ifluatex
326 \coolpdftrue
327 \fi
328 \ifpdftex
329 \coolpdftrue
330 \fi
331 \fi
332 % \end{macrocode}
333 % \end{macro}
334 % \end{macro}
335 % \end{macro}
336 %
337 %
338 % \subsection{\pdfterm{AcroForm} construction}
339 % \label{sec:acroform}
340 %
341 % \acro{pdf} requires that all top-level form fields be pointed to by an
342 % \pdfterm{AcroForm} entry in the catalogue. We therefore have to keep
343 % track of all of our form fields.
344 %
345 % \begin{macro}{ctip@form@fields}
346 % Define a list of ``\meta{object}~|0 R|'' elements.
347 % \begin{macrocode}
348 \newcommand*{\ctip@form@fields}{}
349 % \end{macrocode}
350 % \end{macro}
351 %
352 % At the end of the document we need to export the final value of
353 % |\ctip@form@fields| as an \pdfterm{AcroForm}.
354 % \begin{macrocode}
355 \ifcoolpdf
356 \AtEndDocument{%
357 \immediate\pdfobj {
358 <<
359 /Fields [\ctip@form@fields]
360 /NeedAppearances true
361 >>
362 }%
363 % \end{macrocode}
364 % \begin{macrocode}
365 \pdfcatalog {
366 /AcroForm \the\pdflastobj\space 0 R
367 }%
368 }
369 \fi
370 % \end{macrocode}
371 %
372 %
373 % \subsection{\pdfterm{Text} annotation construction}
374 % \label{sec:text}
375 %
376 % \begin{macro}{\ctip@empty@icon}
377 % Define an empty \pdfterm{XForm} object to use as an invisible icon for
378 % the \pdfterm{Text} annotation.
379 % \begin{macrocode}
380 \ifcoolpdf
381 \setbox\@tempboxa=\hbox{}
382 \immediate\pdfxform\@tempboxa
383 \edef\ctip@empty@icon{\the\pdflastxform}
384 \fi
385 % \end{macrocode}
386 % \end{macro}
387 %
388 % \begin{macro}{\ctip@tip@number}
389 % Keep track of the current tip number. This is necessary for
390 % generating unique object names.
391 % \begin{macrocode}
392 \newcommand*{\ctip@tip@number}{0}
393 % \end{macrocode}
394 % \end{macro}
395 %
396 % \begin{macro}{\ctip@make@Text}
397 % Create a \pdfterm{Text} annotation with a given color~(|#1|, optional),
398 % subject~(|#2|), and content string~(|#3|) and an invisible icon. This
399 % annotation is what will be popped up when the pointer enters the
400 % associated \pdfterm{Widget}.
401 % \begin{macrocode}
402 \newcommand*{\ctip@make@Text}[3][0 1 0]{%
403 \pdfannot width 0pt height 0pt depth 0pt {
404 /Subtype /Text
405 /C [#1]
406 /Subj (#2)
407 /Contents (#3)
408 /NM (ctip Text \ctip@tip@number)
409 /AP <<
410 /N \ctip@empty@icon\space 0 R
411 /D \ctip@empty@icon\space 0 R
412 /R \ctip@empty@icon\space 0 R
413 >>
414 /Open false
415 }%
416 }
417 % \end{macrocode}
418 % \end{macro}
419 %
420 %
421 % \subsection{\pdfterm{Widget} annotation construction}
422 % \label{sec:widgets}
423 %
424 % The \pdfterm{Widget}s in this section are also \acro{pdf} pushbutton
425 % fields. \acro{pdf} supports merging the two object dictionaries
426 % because their keys are disjoint.
427 %
428 % \begin{macro}{\ctip@current@page}
429 % Store the page number on which a \pdfterm{Widget} is finally placed.
430 % \begin{macrocode}
431 \newcommand*{\ctip@current@page}{1}
432 % \end{macrocode}
433 % \end{macro}
434 %
435 % \begin{macro}{\ctip@last@invis}
436 % Keep track of the page number on which we last placed an invisible
437 % \pdfterm{Widget}.
438 % \begin{macrocode}
439 \newcommand*{\ctip@last@invis}{0}
440 % \end{macrocode}
441 % \end{macro}
442 %
443 % \begin{macro}{\ctip@label}
444 % The \pkgname{amsmath} package redefines |\label| within its equation
445 % environments. We need access to the original |\label| so we store a
446 % copy in |\ctip@label|.
447 % \begin{macrocode}
448 \let\ctip@label=\label
449 % \end{macrocode}
450 % \end{macro}
451 %
452 % \begin{macro}{\ctip@update@pagenum}
453 % We can't reliably use |\thepage| to get the current page number
454 % (cf.~\url{https://texfaq.org/FAQ-wrongpn}). Hence, we exploit the
455 % |\label|\slash|\pageref| mechanism to get an accurate page number.
456 % |\ctip@update@pagenum| creates a label (based on
457 % Section~\ref{sec:text}'s |\ctip@tip@number|) then sets
458 % |\ctip@current@page| to the page on which the label occurs.
459 % \begin{macrocode}
460 \newcommand*{\ctip@update@pagenum}{%
461 % \end{macrocode}
462 % \begin{macro}{\ctip@refname}
463 % Using |\label| to define a label \meta{label name} implicitly defines
464 % a macro called |\r@|\meta{label name}. That macro is |\relax| the
465 % first time |pdflatex| is run and thereafter expands to some number of
466 % values, the second of which is the label's page number.
467 % \begin{macrocode}
468 \ctip@label{ctip:tip:\ctip@tip@number}%
469 \expandafter\let\expandafter\ctip@refname
470 \csname r@ctip:tip:\ctip@tip@number\endcsname
471 \@ifundefined{ctip@refname}{%
472 % \end{macrocode}
473 % The first time through we use |\thepage| as an estimate for the
474 % correct page number.
475 % \begin{macrocode}
476 \xdef\ctip@current@page{\thepage}%
477 }{%
478 % \end{macrocode}
479 % On subsequent runs we extract the second (page number) argument and
480 % discard the rest.
481 % \begin{macrocode}
482 \def\ctip@secondofN##1##2##3!{%
483 \xdef\ctip@current@page{##2}%
484 }%
485 \expandafter\ctip@secondofN\ctip@refname!%
486 }%
487 }
488 % \end{macrocode}
489 % \end{macro}
490 % \end{macro}
491 %
492 % \begin{macro}{\ctip@make@invisible@Widget}
493 % For a \pdfterm{Widget} to return focus to the ``background'' it really
494 % returns focus to an \emph{invisible} \pdfterm{Widget}. We need only
495 % one invisible \pdfterm{Widget} per page for this trick to work.
496 % \begin{macrocode}
497 \newcommand*{\ctip@make@invisible@Widget}{%
498 \pdfannot width 0pt height 0pt depth 0pt {
499 /Subtype /Widget
500 /FT /Btn
501 /T (ctip invisible Widget \ctip@current@page)
502 /DA (/Helv 10 Tf 0 0 0 rg)
503 /Ff 65536
504 /F 2
505 % \end{macrocode}
506 % Sometimes, for various focusing trickery to work, the invisible
507 % \pdfterm{Widget} has to be made visible temporarily. We therefore
508 % define an action that makes the \pdfterm{Widget} invisible again as
509 % soon as it receives the input focus.
510 % \begin{macrocode}
511 /AA <<
512 /Fo <<
513 /Type /Action
514 /S /JavaScript
515 /JS (event.target.display = display.hidden)
516 >>
517 >>
518 }%
519 }
520 % \end{macrocode}
521 % \end{macro}
522 %
523 % \begin{macro}{\ctip@content@box}
524 % The \pdfterm{Widget}'s visual content is stored as a \TeX\ box.
525 % \begin{macrocode}
526 \newsavebox{\ctip@content@box}
527 % \end{macrocode}
528 % \end{macro}
529 %
530
531 % \begin{macro}{\ctip@unfocus@js}
532 % Although a \acro{pdf} field can grab the input focus using the
533 % JavaScript |setFocus()| method, there's no mechanism in \acro{pdf}~1.6
534 % to explicitly reset the input focus to the page. The reason we want
535 % to clear the input focus is that the Page~Up and Page~Down keys
536 % function as expected only when none of the fields have the focus.
537 % |\ctip@unfocus@js| expands to some JavaScript code that implicitly
538 % resets the input focus. The trick is to make an invisible
539 % \pdfterm{Widget} temporarily visible, give it the focus, and let its
540 % focus~(|Fo|) action make the \pdfterm{Widget} invisible again.
541 % Because an invisible \pdfterm{Widget} apparently can't retain the
542 % input focus, the focus is reset to the page.
543 % \begin{macrocode}
544 \newcommand*{\ctip@unfocus@js}{%
545 var ctipField =
546 this.getField("ctip invisible Widget \ctip@current@page");
547 ctipField.display = display.visible;
548 ctipField.setFocus();
549 }
550 % \end{macrocode}
551 % \end{macro}
552 %
553 % \begin{macro}{\ctip@enter@js}
554 % The |\ctip@enter@js| macro expands to some JavaScript code to execute
555 % when the mouse pointer enters the (visible) \pdfterm{Widget}. The
556 % code instructs the associated \pdfterm{Text} annotation to open. If
557 % the global JavaScript variable |ctip_disable_popups| is set to |true|
558 % then |\ctip@enter@js| does nothing.
559 % \begin{macrocode}
560 \newcommand*{\ctip@enter@js}{%
561 if (!global.ctip_disable_popups) {
562 var ctipText =
563 this.getAnnot(this.pageNum, "ctip Text \ctip@tip@number");
564 ctipText.popupOpen = true;
565 \ctip@unfocus@js
566 }
567 }
568 % \end{macrocode}
569 % \end{macro}
570 %
571 % \begin{macro}{\ctip@exit@js}
572 % The |\ctip@exit@js| macro expands to some JavaScript code to execute
573 % when the mouse pointer exits the (visible) \pdfterm{Widget}. The code
574 % instructs the associated \pdfterm{Text} annotation to close. The
575 % problem is that it doesn't close immediately but rather waits until
576 % focus leaves the \pdfterm{Text} annotation. (Opening the annotation
577 % apparently gives it focus.) Hence, we explicitly change the focus to
578 % the associated invisible \pdfterm{Widget} annotation to force the
579 % \pdfterm{Text} annotation to close immediately. Because the invisible
580 % \pdfterm{Widget} is invisible it can't steal the input focus from the
581 % page and thereby prevent the Page~Up and Page~Down keys from
582 % functioning properly. If the global JavaScript variable
583 % |ctip_disable_popups| is set to |true| then |\ctip@exit@js| does
584 % nothing.
585 % \begin{macrocode}
586 \newcommand*{\ctip@exit@js}{%
587 if (!global.ctip_disable_popups) {
588 var ctipText =
589 this.getAnnot(this.pageNum, "ctip Text \ctip@tip@number");
590 ctipText.popupOpen = false;
591 \ctip@unfocus@js
592 }
593 }
594 % \end{macrocode}
595 % \end{macro}
596 %
597 % \begin{macro}{\ctip@make@Widget}
598 % Create a \pdfterm{Widget} annotation which represents a pushbutton
599 % field. |\ctip@make@Widget| expects |\ctip@content@box| to have the
600 % desired height, width, and depth of the \pdfterm{Widget}. The
601 % arguments to |\ctip@make@Widget| are the link color~(|#1|, optional),
602 % the \acro{url} to link to~(|#2|), the tooltip to display~(|#3|).
603 % \begin{macrocode}
604 \newcommand*{\ctip@make@Widget}[3][0 1 0]{%
605 % \end{macrocode}
606 % Prepare to make the \pdfterm{Widget} annotation the same size as
607 % |\ctip@content@box| plus an |\fboxsep|$+$|\fboxrule|'s worth of space
608 % on each of its four sides.
609 % \begin{macrocode}
610 \setlength{\@tempdima}{\wd\ctip@content@box}%
611 \addtolength{\@tempdima}{\fboxsep}%
612 \setlength{\@tempdimb}{\ht\ctip@content@box}%
613 \addtolength{\@tempdimb}{0.5\fboxsep}%
614 \setlength{\@tempdimc}{\dp\ctip@content@box}%
615 \addtolength{\@tempdimc}{0.5\fboxsep}%
616 \hspace*{-0.5\fboxsep}%
617 % \end{macrocode}
618 % \begin{macro}{\ctip@action@object}
619 % Create a separate \pdfterm{Action} object because we intend to use it
620 % in both the \pdfterm{Widget} annotation and in a \pdfterm{Link}
621 % annotation. (See below.)
622 % \begin{macrocode}
623 \immediate
624 \pdfobj {
625 <<
626 /Type /Action
627 /S /URI
628 /URI (#2)
629 >>
630 }%
631 \edef\ctip@action@object{\the\pdflastobj\space 0 R}%
632 % \end{macrocode}
633 % \end{macro}
634 % For compatibility with xpdf, which---as of this writing---does not
635 % support \pdfterm{Widget} annotations, we put a \pdfterm{Link}
636 % annotation behind the \pdfterm{Widget} annotation.
637 % \begin{macrocode}
638 \makebox[0pt][l]{%
639 % \end{macrocode}
640 % Because |\fboxrule| is rounded down when used as a \pdfterm{Border}
641 % width we (locally) increment it by $\sim 1$ to get it to round up
642 % instead.
643 % \begin{macrocode}
644 \advance\fboxrule by 0.9999pt
645 \pdfannot width \@tempdima
646 height \@tempdimb
647 depth \@tempdimc {
648 /Subtype /Link
649 /A \ctip@action@object
650 /Border [0 0 \strip@pt\fboxrule]
651 /C [#1]
652 }%
653 }%
654 % \end{macrocode}
655 % We now create a \pdfterm{Widget} annotation, which is placed directly
656 % atop the \pdfterm{Link} annotation.
657 % \begin{macrocode}
658 \pdfannot width \@tempdima
659 height \@tempdimb
660 depth \@tempdimc {
661 /Subtype /Widget
662 /FT /Btn
663 /T (ctip Field \ctip@tip@number)
664 % \end{macrocode}
665 % Acrobat~7.0, at least, displays the ``alternate field
666 % name''~(\pdfterm{TU}) as a tooltip.
667 % \begin{macrocode}
668 /TU (#3)
669 % \end{macrocode}
670 % We're obligated to include a default appearance string~(\pdfterm{DA})
671 % even though we don't really need it here.
672 % \begin{macrocode}
673 /DA (/Helv 10 Tf 0 0 0 rg)
674 % \end{macrocode}
675 % Set bit~17 ($2^{17-1}$) of the field flags~(\pdfterm{Ff}) to indicate
676 % that this is a pushbutton---as opposed to a radio button or check box.
677 % \begin{macrocode}
678 /Ff 65536
679 % \end{macrocode}
680 % Honor |\fboxrule| as the width of the link border.
681 % \begin{macrocode}
682 /BS <<
683 /Type /Border
684 /W \strip@pt\fboxrule
685 >>
686 % \end{macrocode}
687 % Define an appearance.
688 % \begin{macrocode}
689 /MK <<
690 /BC [#1]
691 /TP 1
692 >>
693 % \end{macrocode}
694 % Create an additional actions~(\pdfterm{AA}) dictionary. This is where
695 % all of the popup magic is defined.
696 % \begin{macrocode}
697 /AA <<
698 % \end{macrocode}
699 % When the mouse pointer enters the \pdfterm{Widget} we tell our
700 % associated \pdfterm{Text} annotation to open.
701 % \begin{macrocode}
702 /E <<
703 /Type /Action
704 /S /JavaScript
705 /JS (\ctip@enter@js)
706 >>
707 % \end{macrocode}
708 % When the mouse pointer exits the \pdfterm{Widget} we tell our
709 % associated \pdfterm{Text} annotation to close.
710 % \begin{macrocode}
711 /X <<
712 /Type /Action
713 /S /JavaScript
714 /JS (\ctip@exit@js)
715 >>
716 % \end{macrocode}
717 % When the user clicks on the \pdfterm{Widget} we relinquish the input
718 % focus and launch the specified \acro{url}.
719 % \begin{macrocode}
720 /U <<
721 /Type /Action
722 /S /JavaScript
723 /JS (\ctip@unfocus@js)
724 /Next \ctip@action@object
725 >>
726 >>
727 }
728 % \end{macrocode}
729 % Now that the \pdfterm{Widget} is defined we need to append an object
730 % reference for it to |\ctip@form@fields| so we can add that to the
731 % document's \pdfterm{AcroForm}.
732 % \begin{macrocode}
733 \xdef\ctip@form@fields{\ctip@form@fields\space\the\pdflastannot\space 0 R}
734 }
735 % \end{macrocode}
736 % \end{macro}
737 %
738 %
739 % \subsection{User commands}
740 % \label{sec:user-commands}
741 %
742 % \begin{macro}{\cooltooltip}
743 % The user can create a cool tooltip by invoking |\cooltooltip| with the
744 % popup color~(|#1|, optional), the link color~(|#2|, optional), the
745 % subject of the popup~(|#3|), the string to display in the
746 % popup~(|#4|), the \acro{url} to link to~(|#5|), the tooltip to
747 % display~(|#6|), and the text that will activate the
748 % tooltip/popup~(|#7|).
749 % \begin{macrocode}
750 \DeclareRobustCommand{\cooltooltip}[1][0 1 0]{%
751 \def\ctip@popup@color{#1}%
752 \ctip@cooltooltip@i
753 }
754 % \end{macrocode}
755 % \end{macro}
756 %
757 % \begin{macro}{\ctip@cooltooltip@i}
758 % This is where everything gets called. Upon entry, |\ctip@popup@color|
759 % is already defined as the popup color (and default color for the
760 % link).
761 % \begin{macrocode}
762 \newcommand*{\ctip@cooltooltip@i}[6][\ctip@popup@color]{%
763 % \end{macrocode}
764 % Store into |\ctip@content@box| the visual appearance of the link.
765 % \begin{macrocode}
766 \savebox{\ctip@content@box}{#6}%
767 % \end{macrocode}
768 % Increase the cool tooltip number. |\ctip@tip@number| is used by
769 % |\ctip@make@Widget|, |\ctip@make@Text|, and |\ctip@update@pagenum|.
770 % \begin{macrocode}
771 \@tempcnta=\ctip@tip@number
772 \advance\@tempcnta by 1
773 \xdef\ctip@tip@number{\the\@tempcnta}%
774 % \end{macrocode}
775 % Determine if we're on a new page and therefore need to create another
776 % invisible \pdfterm{Widget}.
777 % \begin{macrocode}
778 \ctip@update@pagenum
779 \@tempcnta=\ctip@last@invis
780 \@tempcntb=\ctip@current@page
781 \ifnum\@tempcnta<\@tempcntb
782 \ctip@make@invisible@Widget
783 \xdef\c@ctip@last@invis{\ctip@current@page}%
784 \fi
785 % \end{macrocode}
786 % Place a \pdfterm{Widget} and its associated \pdfterm{Text} popup but
787 % without occupying any space on the page (as far as \TeX\ can
788 % determine).
789 % \begin{macrocode}
790 \makebox[0pt][l]{%
791 \ctip@make@Widget[#1]{#4}{#5}%
792 \makebox[\paperwidth][r]{%
793 \ctip@make@Text[\ctip@popup@color]{#2}{#3}%
794 }%
795 }%
796 % \end{macrocode}
797 % Render the link contents that we stored earlier.
798 % \begin{macrocode}
799 \usebox{\ctip@content@box}%
800 }
801 % \end{macrocode}
802 % \end{macro}
803 %
804 % \begin{macro}{\cooltooltiptoggle}
805 % Cool tooltips are rather kludgy in the way that they manipulate
806 % \acro{pdf} annotation state and transfer focus from annotation to
807 % annotation. Because this kludginess can lead to strange interactive
808 % behavior we provide the author with a |\cooltooltiptoggle| macro which
809 % creates a button to disable/enable the \cool\ popup mechanism. The
810 % sole argument to |\cooltooltiptoggle| is the button text.
811 % \begin{macrocode}
812 \DeclareRobustCommand{\cooltooltiptoggle}[1]{%
813 \savebox{\ctip@content@box}{#1}%
814 \makebox[0pt][l]{%
815 \pdfannot width \wd\ctip@content@box
816 height \ht\ctip@content@box
817 depth \dp\ctip@content@box {
818 /Subtype /Link
819 /Border [0 0 0]
820 /A <<
821 /Type /Action
822 /S /JavaScript
823 /JS (
824 global.ctip_disable_popups = !global.ctip_disable_popups;
825 var ctipField;
826 var i;
827 for (i=1; (ctipField=this.getField("ctip Field " + i)); i++)
828 ctipField.display =
829 global.ctip_disable_popups ? display.hidden : display.visible;
830 )
831 >>
832 }%
833 }%
834 \usebox{\ctip@content@box}%
835 }
836 % \end{macrocode}
837 % \end{macro}
838 %
839 %
840 % \subsection{Sanity checks}
841 % \label{sec:sanity-checks}
842 %
843 % Complain---but attempt to continue---if we're not running
844 % pdf\LaTeX\ or Lua\LaTeX\ in \acro{pdf} mode.
845 % \begin{macrocode}
846 \ifcoolpdf
847 \else
848 \PackageWarning{cooltooltips}{%
849 Not running pdfLaTeX or LuaLaTeX in PDF mode; disabling cooltooltips%
850 }
851 \renewcommand*{\ctip@cooltooltip@i}[6][]{\mbox{#6}}
852 \fi
853 % \end{macrocode}
854 %
855 %
856 % \Finale
857 \endinput