| 1 |
% Copyright (C) 2012 by Paul Gaborit |
| 2 |
% |
| 3 |
% This file may be distributed and/or modified |
| 4 |
% |
| 5 |
% 1. under the LaTeX Project Public License and/or |
| 6 |
% 2. under the GNU Public License. |
| 7 |
|
| 8 |
\documentclass[a4paper]{ltxdoc} |
| 9 |
\usepackage[vmargin=2cm,hmargin=3.5cm,nohead]{geometry} |
| 10 |
\usepackage[latin1]{inputenc} |
| 11 |
\usepackage[T1]{fontenc} |
| 12 |
\usepackage{lmodern} |
| 13 |
\usepackage{xcolor} |
| 14 |
\usepackage{ifthen} |
| 15 |
\usepackage{doc} |
| 16 |
\usepackage{fancyvrb} |
| 17 |
\usepackage{newverbs} |
| 18 |
\usepackage{listings} |
| 19 |
\lstdefinestyle{TeXcode}{ |
| 20 |
fancyvrb=true, |
| 21 |
language=[LaTeX]TeX, |
| 22 |
basicstyle=\ttfamily, |
| 23 |
upquote=true, |
| 24 |
keywordstyle=\color{blue}\bfseries, |
| 25 |
commentstyle=\color{red!50!black}\itshape, |
| 26 |
stringstyle=\ttfamily\color{green!50!black}, |
| 27 |
showspaces=false, |
| 28 |
showstringspaces=false, |
| 29 |
backgroundcolor=\color{blue!10}, |
| 30 |
fontadjust=true, |
| 31 |
aboveskip=1ex, |
| 32 |
belowskip=1ex, |
| 33 |
emphstyle=\color{blue}\bfseries, |
| 34 |
keepspaces=true, |
| 35 |
flexiblecolumns=true, |
| 36 |
emph={switchocg,showocg,hideocg,actionsocg,usetikzlibrary,node} |
| 37 |
} |
| 38 |
\makeatletter |
| 39 |
\newenvironment{prog}[1]{\vspace{1ex}--- \texttt{\emph{#1}} ---}{} |
| 40 |
\newenvironment{ocgXample}[1]{% name |
| 41 |
\gdef\ocgXample@filename{#1}% |
| 42 |
\@tempswafalse\filec@ntents{#1}% |
| 43 |
} |
| 44 |
{\endfilecontents\aftergroup\showocgXample} |
| 45 |
\newcommand\showocgXample{ |
| 46 |
\minipage{1.0\linewidth}% |
| 47 |
\prog{\ocgXample@filename} |
| 48 |
\lstinputlisting[style=TeXcode,aboveskip=0ex]\ocgXample@filename% |
| 49 |
\endprog |
| 50 |
\endminipage |
| 51 |
} |
| 52 |
|
| 53 |
\newcommand{\TeXexample}[3][]{% |
| 54 |
\begin{minipage}{1.0\linewidth} |
| 55 |
\ifthenelse{\equal{#1}{}}{\begin{prog}{#2}}{\begin{prog}{#2 (#1)}}% |
| 56 |
\lstinputlisting[style=TeXcode,aboveskip=0ex,#3]{#2}% |
| 57 |
\end{prog} |
| 58 |
\end{minipage}\par |
| 59 |
} |
| 60 |
\makeatother |
| 61 |
|
| 62 |
\usepackage{url} |
| 63 |
\usepackage[colorlinks]{hyperref} |
| 64 |
\usepackage[english]{babel} |
| 65 |
\usepackage[babel]{microtype} |
| 66 |
\setlength{\parindent}{0pt} |
| 67 |
\setlength{\parskip}{.4\baselineskip plus .5\baselineskip minus .2\baselineskip} |
| 68 |
\usepackage{tikz} |
| 69 |
\usetikzlibrary{shadows} |
| 70 |
\usepackage[all]{nowidow} |
| 71 |
\usepackage{ocgx} |
| 72 |
\usepackage{filecontents} |
| 73 |
|
| 74 |
\newcounter{mynotes} |
| 75 |
\newenvironment{note}{% |
| 76 |
\vspace{5pt} |
| 77 |
\tikzpicture |
| 78 |
\node[%draw=black,line width=.1pt, |
| 79 |
rounded corners=1em, |
| 80 |
inner xsep=1.3em, inner ysep=.8em, |
| 81 |
text width=\linewidth-2.6em-\pgflinewidth, |
| 82 |
align=justify, |
| 83 |
draw=cyan!50!black, |
| 84 |
fill=white, |
| 85 |
fill=yellow!20, |
| 86 |
line width=1pt, |
| 87 |
drop shadow={fill=cyan!50!black}, |
| 88 |
] (note) \bgroup% |
| 89 |
}{% |
| 90 |
\egroup; |
| 91 |
\node[circle,overlay, |
| 92 |
%fill=white,draw=cyan!50!black, |
| 93 |
draw=white,fill=cyan!50!black,text=white, |
| 94 |
line width=2pt, |
| 95 |
drop shadow={fill=cyan!50!black}, |
| 96 |
font=\small\bfseries,inner sep=4pt] |
| 97 |
at (note.north west){\stepcounter{mynotes}\arabic{mynotes}}; |
| 98 |
\endtikzpicture\par\vspace{.1em}% |
| 99 |
} |
| 100 |
|
| 101 |
|
| 102 |
\newverbcommand\code{\color{red}}{} |
| 103 |
\newverbcommand\style{\hspace{-2em}\color{red}}{} |
| 104 |
\newcommand\defaultvalue[1]{\hfill(#1)} |
| 105 |
\newcommand\argument[1]{\textcolor{black}{\ttfamily #1}} |
| 106 |
\newcommand\TikZ{Ti\emph{k}Z} |
| 107 |
|
| 108 |
\title{The \texttt{ocgx} package (version \ocgxversion)} |
| 109 |
\author{% |
| 110 |
Paul \textsc{Isambert} |
| 111 |
\and% |
| 112 |
Paul \textsc{Gaborit}\\\url{[email protected]}} |
| 113 |
\date{\today} |
| 114 |
|
| 115 |
\begin{document} |
| 116 |
\maketitle |
| 117 |
|
| 118 |
\tableofcontents |
| 119 |
|
| 120 |
\section*{Abstract} |
| 121 |
|
| 122 |
The \code+ocgx+ package extends the \code+ocg-p+ package which allows |
| 123 |
you to create OCGs (\emph{Optional Content Group}) in PDF documents. |
| 124 |
|
| 125 |
Every OCG includes \TeX{} material into a layer of the PDF file. Each of |
| 126 |
these layers can be displayed or not. Links can enable or disable the |
| 127 |
display of OCGs. |
| 128 |
|
| 129 |
The \code+ocgx+ package does not use Javascript embedded in the PDF |
| 130 |
document to enable (to show) or disable (to hide) OCGs. |
| 131 |
|
| 132 |
\begin{note} |
| 133 |
OCGs are usable with several PDF readers: to date, it has been |
| 134 |
successfully tested with \emph{Acrobat Reader}, \emph{Foxit Reader}, |
| 135 |
\emph{PDF-XChange-Viewer}, and \emph{Evince}. The management of OGCs |
| 136 |
by \emph{Evince} is not yet fully debugged: it still sometimes crash! |
| 137 |
\end{note} |
| 138 |
|
| 139 |
\section{Usage} |
| 140 |
|
| 141 |
Here is a simple example. |
| 142 |
|
| 143 |
\begin{ocgXample}{ocgx-example-1.tex} |
| 144 |
\documentclass{article} |
| 145 |
\usepackage{ocgx} |
| 146 |
\begin{document} |
| 147 |
\begin{ocg}{OCG 1}{ocg1}{1} |
| 148 |
first example. |
| 149 |
\end{ocg} |
| 150 |
|
| 151 |
\switchocg{ocg1}{Button.} |
| 152 |
\end{document} |
| 153 |
\end{ocgXample} |
| 154 |
|
| 155 |
This document creates an OCG called \emph{ocg1} containing the text |
| 156 |
``\emph{first example.}'' which is visible. You can show or hide this |
| 157 |
OCG by clicking the link ``\emph{Button.}''. |
| 158 |
|
| 159 |
\subsection{Create OCGs} |
| 160 |
|
| 161 |
The following code creates an OCG named \emph{OCG name} with |
| 162 |
\emph{refocg} as internal reference. The content of this OCG is |
| 163 |
``\emph{content...}''. This OCG is visible (the third argument is 1). |
| 164 |
|
| 165 |
\begin{ocgXample}{ocgx-example-2} |
| 166 |
\begin{ocg}{OCG name}{refocg}{1} |
| 167 |
content... |
| 168 |
\end{ocg} |
| 169 |
\end{ocgXample} |
| 170 |
|
| 171 |
\DescribeEnv{ocg}% |
| 172 |
The \code+ocg+ environment (provided by the package \code+ocg-p+) |
| 173 |
creates OCGs. It requires three arguments. The first argument is the |
| 174 |
name of the OCG as it appears in the layer toolbar of the PDF |
| 175 |
viewer. The second argument is the internal name used to reference this |
| 176 |
OCG. The third argument sets the initial visibility of the OCG when the |
| 177 |
document is opened (1 for visible, 0 for invisible). The content of the |
| 178 |
environment (any \TeX material) is added into the OCG. |
| 179 |
|
| 180 |
\begin{note} |
| 181 |
The same reference can be used with several \code+ocg+ environments (not |
| 182 |
necessarily in the same page). All materials are grouped in the same |
| 183 |
OCG. Only the first name provided will be used. |
| 184 |
\end{note} |
| 185 |
|
| 186 |
\begin{note} |
| 187 |
A reference of an OCG consists of letters (A-Z, a-z), numbers (0-9). |
| 188 |
\end{note} |
| 189 |
|
| 190 |
\begin{note} |
| 191 |
The content of the \code+ocg+ environment should not span across |
| 192 |
multiple pages. Currently, nothing prevents you to try it but the |
| 193 |
result will certainly not be the one you were expecting! |
| 194 |
\end{note} |
| 195 |
|
| 196 |
\begin{note} |
| 197 |
It is possible to nest an OCG in another OCG. To display the internal |
| 198 |
OCG, both the internal and external OCGs need to be in the visible |
| 199 |
state. |
| 200 |
\end{note} |
| 201 |
|
| 202 |
\subsection{Manage the visibility of OCGs} |
| 203 |
|
| 204 |
\DescribeMacro{\switchocg}% |
| 205 |
The \code+\switchocg+ macro turns its second argument into a clickable |
| 206 |
link that toggles the visibility status of all listed OCGs (by their |
| 207 |
reference) in its first argument: if an OCG was visible, it becomes |
| 208 |
invisible, and conversely, if an OCG was invisible, it becomes visible. |
| 209 |
|
| 210 |
The following code creates the link \emph{toggle} that switches the |
| 211 |
visibility status of OCGs whose references are \emph{ocg1} and |
| 212 |
\emph{ocg2}: |
| 213 |
|
| 214 |
\begin{lstlisting}[style=TeXcode] |
| 215 |
\switchocg{ocg1 ocg2}{toggle} |
| 216 |
\end{lstlisting} |
| 217 |
|
| 218 |
\DescribeMacro{\showocg}% |
| 219 |
The \code+\showocg+ macro turns its second argument into a clickable |
| 220 |
link that make visible all OCGs whose references are listed in its first |
| 221 |
argument: an invisible OCG becomes visible and an OCG already visible |
| 222 |
remains visible. |
| 223 |
|
| 224 |
The following code creates the link \emph{show} which makes visible the |
| 225 |
OCGs whoses references are \emph{ocg1} and \emph{ocg2}: |
| 226 |
|
| 227 |
\begin{lstlisting}[style=TeXcode] |
| 228 |
\showocg{ocg1 ocg2}{show} |
| 229 |
\end{lstlisting} |
| 230 |
|
| 231 |
\DescribeMacro{\hideocg}% |
| 232 |
The \code+\hideocg+ macro turns its second argument into a clickable |
| 233 |
link that make invisible all OCGs whose references are listed in its |
| 234 |
first argument: a visible OCG becomes invisible and an OCG already |
| 235 |
invisible remains invisible. |
| 236 |
|
| 237 |
The following code creates the link \emph{hide} which makes invisible |
| 238 |
the OCGs whoses references are \emph{ocg1} and \emph{ocg2}: |
| 239 |
|
| 240 |
\begin{lstlisting}[style=TeXcode] |
| 241 |
\hideocg{ocg1 ocg2}{hide} |
| 242 |
\end{lstlisting} |
| 243 |
|
| 244 |
\DescribeMacro{\actionsocg}% |
| 245 |
The \code+\actionsocg+ macro transforms its fourth argument into a |
| 246 |
clickable link. Its three first arguments are lists of references of |
| 247 |
OCGs. The first list contains references of OCGs which visibility status |
| 248 |
is to be toggled. The second list contains references of OCGs to be set |
| 249 |
visible. The third list contains references of OCGs to be set invisible. |
| 250 |
|
| 251 |
The following code creates the link \emph{actions} to toggle the |
| 252 |
visibility status of the OCG named \emph{ocg1}, to make visible the OCG |
| 253 |
named \emph{ocg3}, and to make invisible OCG named \emph{ocg2}: |
| 254 |
|
| 255 |
\begin{lstlisting}[style=TeXcode] |
| 256 |
\actionsocg{ocg1}{ocg3}{ocg2}{actions} |
| 257 |
\end{lstlisting} |
| 258 |
|
| 259 |
\subsection{Usage with \TikZ{}} |
| 260 |
|
| 261 |
You can use the \code+ocgx+ package with \TikZ{}. The package provides a |
| 262 |
\TikZ{} library offering some specific styles to add material to OCGs, |
| 263 |
or to transform a path (\code+\path+ or \code+\node+) into a clickable |
| 264 |
link. To use it, simply add the following lines in your preamble: |
| 265 |
|
| 266 |
\begin{ocgXample}{ocgx-tikz-preamble} |
| 267 |
\usepackage{tikz} |
| 268 |
\usetikzlibrary{ocgx} |
| 269 |
\end{ocgXample} |
| 270 |
|
| 271 |
\subsubsection*{How to add \TikZ{} scopes into OCGs} |
| 272 |
|
| 273 |
\begin{list}{} |
| 274 |
\item |
| 275 |
|
| 276 |
\noindent\style+/tikz/ocg+\argument{=\{\emph{<ocg options>}\}} |
| 277 |
|
| 278 |
The \code+ocg+ family is used to specify the options used to add a |
| 279 |
scope into an OCG. |
| 280 |
|
| 281 |
\begin{list}{} |
| 282 |
\item |
| 283 |
|
| 284 |
\noindent\style+/tikz/ocg/ref+\argument{=\emph{<refname>}}\defaultvalue{no |
| 285 |
default} |
| 286 |
|
| 287 |
This option add the current scope to the OCG referenced by |
| 288 |
\texttt{refname}. If this OCG does not exist, it is created with |
| 289 |
\texttt{name} and visibility \texttt{status} specified by the |
| 290 |
two options below. |
| 291 |
|
| 292 |
\noindent\style+/tikz/ocg/name+\argument{=\emph{<name>}}\defaultvalue{no |
| 293 |
default, initially empty} |
| 294 |
|
| 295 |
It is the \texttt{\emph{name}} of the OCG as it appears in the PDF |
| 296 |
viewer. If the OCG is already created, this option is useless. |
| 297 |
|
| 298 |
\noindent\style+/tikz/ocg/status+\argument{=\emph{<visibility>}}\defaultvalue{no |
| 299 |
default, initially \texttt{visible}} |
| 300 |
|
| 301 |
Specify the initial visibility state of the OCG. Permissible values |
| 302 |
are \texttt{visible}, and \texttt{invisible}. If the OCG is already |
| 303 |
created, this option is useless. |
| 304 |
|
| 305 |
\end{list} |
| 306 |
|
| 307 |
\begin{note} |
| 308 |
If you prefer, you can also use the \code+ogc+ environment in a |
| 309 |
\code+tikzpicture+. The \code+pgfonlayer+ environment is special: |
| 310 |
inside, you must reuse options below, or use a new \code+ocg+ |
| 311 |
environment. |
| 312 |
\end{note} |
| 313 |
|
| 314 |
\end{list} |
| 315 |
|
| 316 |
\subsubsection*{How to transform nodes or paths into clickable links} |
| 317 |
|
| 318 |
\begin{list}{} |
| 319 |
\item |
| 320 |
|
| 321 |
\noindent\style+/tikz/switch ocg+\argument{=\{\emph{<OCGs list>}\}} |
| 322 |
|
| 323 |
This style transforms the current path or the current node in a link acting as |
| 324 |
if it was produced by the macro \code+\switchocg+ (the visibility |
| 325 |
status of referenced OCGs is reversed). |
| 326 |
|
| 327 |
\noindent\style+/tikz/show ocg+\argument{=\{\emph{<OCGs list>}\}} |
| 328 |
|
| 329 |
This style transforms the current path or the current node in a link acting as |
| 330 |
if it was produced by the macro \code+\showocg+ (the referenced OCGs |
| 331 |
are made visible). |
| 332 |
|
| 333 |
\noindent\style+/tikz/hide ocg+\argument{=\{\emph{<OCGs list>}\}} |
| 334 |
|
| 335 |
This style transforms the current path or the current node in a link acting as |
| 336 |
if it was produced by the macro \code+\hideocg+ (the referenced OCGs |
| 337 |
are made invisible). |
| 338 |
|
| 339 |
\noindent\style+/tikz/actions ocg+\argument{=\{\emph{<OCGs |
| 340 |
list>}\}\{\emph{<OCGs list>}\}\{\emph{<OCGs list>}\}} |
| 341 |
|
| 342 |
This style transforms the current path or the current node in a link acting as |
| 343 |
if it is produced by the macro \code+\actionsocg+ (the visibility |
| 344 |
status of OCGs of the first list is reversed, the OCGs in the second |
| 345 |
list are made visible and those of the third list are made invisible). |
| 346 |
|
| 347 |
\noindent\style+/tikz/switch ocg with mark on+\argument{=\{\emph{<ocg |
| 348 |
reference>}\}\{\emph{<OCGs list>}\}} |
| 349 |
|
| 350 |
\noindent\style+/tikz/switch ocg with mark off+\argument{=\{\emph{<ocg |
| 351 |
reference>>}\}\{\emph{<OCGs list>}\}} |
| 352 |
|
| 353 |
These styles transform the current path or the current node in a link acting |
| 354 |
as if it is produced by the macro \code+\switchocg+ (the visibility |
| 355 |
status of referenced OCGs in the list is reversed). |
| 356 |
|
| 357 |
A mark (currently a simple cross) is drawn over the current path or |
| 358 |
node in an OCG whose reference is \texttt{\emph{ocg reference}}. The |
| 359 |
visibility status of this OCG will be reversed as those of the entire |
| 360 |
list. |
| 361 |
|
| 362 |
If the OCG whose reference is \texttt{\emph{ocg reference}} does not |
| 363 |
exist, it is created with an empty name and its initial visibility |
| 364 |
state is true with \code+on+ and false with \code+off+. |
| 365 |
|
| 366 |
\end{list} |
| 367 |
|
| 368 |
\begin{note} |
| 369 |
Due to limitation of PDF, whatever the shape of the current path or |
| 370 |
node is, it is its \emph{bounding box} that is used to make the link: |
| 371 |
the link is always \emph{rectangular} and \emph{horizontal}! |
| 372 |
\end{note} |
| 373 |
|
| 374 |
\subsubsection*{Example with \TikZ{}} |
| 375 |
|
| 376 |
\begin{filecontents*}{ocgx-example-3} |
| 377 |
\begin{tikpicture} |
| 378 |
\begin{scope}[ocg={name=TikZ example,ref=tikzex,status=visible} |
| 379 |
\fill[orange] (0,0) circle (1); |
| 380 |
\end{scope} |
| 381 |
\node[draw,switch ocg=tikzref] at (2,0) {Switch}; |
| 382 |
\end{tikpicture} |
| 383 |
\end{filecontents*} |
| 384 |
\TeXexample{ocgx-example-3}{} |
| 385 |
|
| 386 |
|
| 387 |
|
| 388 |
\section{Examples} |
| 389 |
|
| 390 |
The document \code+demo-ocgx.tex+ provides several examples of usage of |
| 391 |
package \code+ocgx+ with \TikZ{} (and \code+beamer+). |
| 392 |
|
| 393 |
\section{Limits and bugs} |
| 394 |
|
| 395 |
\begin{enumerate} |
| 396 |
\item Links are always horizontal rectangles! |
| 397 |
\item An \code+ocg+ environment spanning across multiple pages are not |
| 398 |
detected and don't work correctly. |
| 399 |
\item The packages \code+ocg-p+ and \code+ocgx+ are not compatible with |
| 400 |
Plain-\TeX{}. |
| 401 |
\item While \code+ocg-p+ is usable with \code+pdflatex+ and |
| 402 |
\code+xelatex+, \code+ocgx+ works only with \code+pdflatex+ (and |
| 403 |
\code+lualatex+). |
| 404 |
\end{enumerate} |
| 405 |
|
| 406 |
\section{Development and history} |
| 407 |
This package is still experimental. It is released on CTAN. You can |
| 408 |
donwload the latest version from \url{https://github.com/polgab/ocgx}. Any |
| 409 |
help to participate in its development is welcome: contact the |
| 410 |
maintainer (\url{[email protected]}). |
| 411 |
|
| 412 |
\paragraph{version 0.5} (2012-12-07) Now, the \code+ocgx+ package uses |
| 413 |
the new \code+ocg-p+ package instead of the \code+ocg+ package : the |
| 414 |
layers can be nested in the layer toolbar of the PDF viewer. |
| 415 |
|
| 416 |
\paragraph{version 0.4} (2012-11-14) Added dependancy to \texttt{calc} |
| 417 |
TikZ library. Fixed bug: bad lists in \code+\actionsocg+. |
| 418 |
|
| 419 |
\paragraph{version 0.3} (2012-09-30) Complete documentation for part |
| 420 |
\emph{Usage with TikZ} and correct TDS archive. |
| 421 |
|
| 422 |
\paragraph{version 0.2} (2012-09-27) First release on CTAN. |
| 423 |
\end{document} |
| 424 |
|
| 425 |
|
| 426 |
|
| 427 |
%%% Local Variables: |
| 428 |
%%% mode: latex |
| 429 |
%%% TeX-master: t |
| 430 |
%%% End: |