summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/ocgx/ocgx-manual-en.tex
blob: c790c312b3f60e78bf874ac5c18f4c3689a0cebd (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
% Copyright (C) 2012 by Paul Gaborit
%
% This file may be distributed and/or modified
%
% 1. under the LaTeX Project Public License and/or
% 2. under the GNU Public License.

\documentclass[a4paper]{ltxdoc}
\usepackage[vmargin=2cm,hmargin=3.5cm,nohead]{geometry}
\usepackage[latin1]{inputenc}
\usepackage[T1]{fontenc}
\usepackage{lmodern}
\usepackage{xcolor}
\usepackage{ifthen}
\usepackage{doc}
\usepackage{fancyvrb}
\usepackage{newverbs}
\usepackage{listings}
\lstdefinestyle{TeXcode}{
  fancyvrb=true,
  language=[LaTeX]TeX,
  basicstyle=\ttfamily,
  upquote=true,
  keywordstyle=\color{blue}\bfseries,
  commentstyle=\color{red!50!black}\itshape,
  stringstyle=\ttfamily\color{green!50!black},
  showspaces=false,
  showstringspaces=false,
  backgroundcolor=\color{blue!10},
  fontadjust=true,
  aboveskip=1ex,
  belowskip=1ex,
  emphstyle=\color{blue}\bfseries,
  keepspaces=true,
  flexiblecolumns=true,
  emph={switchocg,showocg,hideocg,actionsocg,usetikzlibrary,node}
}
\makeatletter
\newenvironment{prog}[1]{\vspace{1ex}--- \texttt{\emph{#1}} ---}{}
\newenvironment{ocgXample}[1]{% name 
  \gdef\ocgXample@filename{#1}%
  \@tempswafalse\filec@ntents{#1}%
}
{\endfilecontents\aftergroup\showocgXample}
\newcommand\showocgXample{
  \minipage{1.0\linewidth}%
  \prog{\ocgXample@filename}
  \lstinputlisting[style=TeXcode,aboveskip=0ex]\ocgXample@filename%
  \endprog
  \endminipage
}

\newcommand{\TeXexample}[3][]{%
  \begin{minipage}{1.0\linewidth}
    \ifthenelse{\equal{#1}{}}{\begin{prog}{#2}}{\begin{prog}{#2 (#1)}}%
        \lstinputlisting[style=TeXcode,aboveskip=0ex,#3]{#2}%
    \end{prog}
  \end{minipage}\par
}
\makeatother
  
\usepackage{url}
\usepackage[colorlinks]{hyperref}
\usepackage[english]{babel}
\usepackage[babel]{microtype}
\setlength{\parindent}{0pt}
\setlength{\parskip}{.4\baselineskip plus .5\baselineskip minus .2\baselineskip}
\usepackage{tikz}
\usetikzlibrary{shadows}
\usepackage[all]{nowidow}
\usepackage{ocgx}
\usepackage{filecontents}

\newcounter{mynotes}
\newenvironment{note}{%
  \vspace{5pt}
  \tikzpicture
  \node[%draw=black,line width=.1pt,
  rounded corners=1em,
  inner xsep=1.3em, inner ysep=.8em,
  text width=\linewidth-2.6em-\pgflinewidth,
  align=justify,
  draw=cyan!50!black,
  fill=white,
  fill=yellow!20,
  line width=1pt,
  drop shadow={fill=cyan!50!black},
  ] (note) \bgroup%
}{%
  \egroup;
  \node[circle,overlay,
  %fill=white,draw=cyan!50!black,
  draw=white,fill=cyan!50!black,text=white,
  line width=2pt,
  drop shadow={fill=cyan!50!black},
  font=\small\bfseries,inner sep=4pt]
  at (note.north west){\stepcounter{mynotes}\arabic{mynotes}};
  \endtikzpicture\par\vspace{.1em}%
}


\newverbcommand\code{\color{red}}{}
\newverbcommand\style{\hspace{-2em}\color{red}}{}
\newcommand\defaultvalue[1]{\hfill(#1)}
\newcommand\argument[1]{\textcolor{black}{\ttfamily #1}}
\newcommand\TikZ{Ti\emph{k}Z}

\title{The \texttt{ocgx} package (version \ocgxversion)}
\author{%
  Paul \textsc{Isambert}
  \and%
  Paul \textsc{Gaborit}\\\url{paul.gaborit@gmail.com}}
\date{\today}

\begin{document}
\maketitle

\tableofcontents

\section*{Abstract}

The \code+ocgx+ package extends the \code+ocg-p+ package which allows
you to create OCGs (\emph{Optional Content Group}) in PDF documents.

Every OCG includes \TeX{} material into a layer of the PDF file. Each of
these layers can be displayed or not. Links can enable or disable the
display of OCGs.

The \code+ocgx+ package does not use Javascript embedded in the PDF
document to enable (to show) or disable (to hide) OCGs.

\begin{note}
  OCGs are usable with several PDF readers: to date, it has been
  successfully tested with \emph{Acrobat Reader}, \emph{Foxit Reader},
  \emph{PDF-XChange-Viewer}, and \emph{Evince}. The management of OGCs
  by \emph{Evince} is not yet fully debugged: it still sometimes crash!
\end{note}

\section{Usage}

Here is a simple example.

\begin{ocgXample}{ocgx-example-1.tex}
\documentclass{article}
\usepackage{ocgx}
\begin{document}
\begin{ocg}{OCG 1}{ocg1}{1}
  first example.
\end{ocg}

\switchocg{ocg1}{Button.}
\end{document}
\end{ocgXample}

This document creates an OCG called \emph{ocg1} containing the text
``\emph{first example.}''  which is visible. You can show or hide this
OCG by clicking the link ``\emph{Button.}''.

\subsection{Create OCGs}

The following code creates an OCG named \emph{OCG name} with
\emph{refocg} as internal reference. The content of this OCG is
``\emph{content...}''. This OCG is visible (the third argument is 1).

\begin{ocgXample}{ocgx-example-2}
\begin{ocg}{OCG name}{refocg}{1}
  content...
\end{ocg}
\end{ocgXample}

\DescribeEnv{ocg}%
The \code+ocg+ environment (provided by the package \code+ocg-p+)
creates OCGs. It requires three arguments. The first argument is the
name of the OCG as it appears in the layer toolbar of the PDF
viewer. The second argument is the internal name used to reference this
OCG. The third argument sets the initial visibility of the OCG when the
document is opened (1 for visible, 0 for invisible). The content of the
environment (any \TeX material) is added into the OCG.

\begin{note}
  The same reference can be used with several \code+ocg+ environments (not
  necessarily in the same page). All materials are grouped in the same
  OCG. Only the first name provided will be used.
\end{note}

\begin{note}
  A reference of an OCG consists of letters (A-Z, a-z), numbers (0-9).
\end{note}

\begin{note}
  The content of the \code+ocg+ environment should not span across
  multiple pages. Currently, nothing prevents you to try it but the
  result will certainly not be the one you were expecting!
\end{note}

\begin{note}
  It is possible to nest an OCG in another OCG. To display the internal
  OCG, both the internal and external OCGs need to be in the visible
  state.
\end{note}

\subsection{Manage the visibility of OCGs}

\DescribeMacro{\switchocg}%
The \code+\switchocg+ macro turns its second argument into a clickable
link that toggles the visibility status of all listed OCGs (by their
reference) in its first argument: if an OCG was visible, it becomes
invisible, and conversely, if an OCG was invisible, it becomes visible.

The following code creates the link \emph{toggle} that switches the
visibility status of OCGs whose references are \emph{ocg1} and
\emph{ocg2}:

\begin{lstlisting}[style=TeXcode]
\switchocg{ocg1 ocg2}{toggle}
\end{lstlisting}

\DescribeMacro{\showocg}%
The \code+\showocg+ macro turns its second argument into a clickable
link that make visible all OCGs whose references are listed in its first
argument: an invisible OCG becomes visible and an OCG already visible
remains visible.

The following code creates the link \emph{show} which makes visible the
OCGs whoses references are \emph{ocg1} and \emph{ocg2}:

\begin{lstlisting}[style=TeXcode]
\showocg{ocg1 ocg2}{show}
\end{lstlisting}

\DescribeMacro{\hideocg}%
The \code+\hideocg+ macro turns its second argument into a clickable
link that make invisible all OCGs whose references are listed in its
first argument: a visible OCG becomes invisible and an OCG already
invisible remains invisible.

The following code creates the link \emph{hide} which makes invisible
the OCGs whoses references are \emph{ocg1} and \emph{ocg2}:

\begin{lstlisting}[style=TeXcode]
\hideocg{ocg1 ocg2}{hide}
\end{lstlisting}

\DescribeMacro{\actionsocg}%
The \code+\actionsocg+ macro transforms its fourth argument into a
clickable link. Its three first arguments are lists of references of
OCGs. The first list contains references of OCGs which visibility status
is to be toggled. The second list contains references of OCGs to be set
visible. The third list contains references of OCGs to be set invisible.

The following code creates the link \emph{actions} to toggle the
visibility status of the OCG named \emph{ocg1}, to make visible the OCG
named \emph{ocg3}, and to make invisible OCG named \emph{ocg2}:

\begin{lstlisting}[style=TeXcode]
\actionsocg{ocg1}{ocg3}{ocg2}{actions}
\end{lstlisting}

\subsection{Usage with \TikZ{}}

You can use the \code+ocgx+ package with \TikZ{}. The package provides a
\TikZ{} library offering some specific styles to add material to OCGs,
or to transform a path (\code+\path+ or \code+\node+) into a clickable
link. To use it, simply add the following lines in your preamble:

\begin{ocgXample}{ocgx-tikz-preamble}
\usepackage{tikz}
\usetikzlibrary{ocgx}
\end{ocgXample}

\subsubsection*{How to add \TikZ{} scopes into OCGs}

\begin{list}{}
\item

  \noindent\style+/tikz/ocg+\argument{=\{\emph{<ocg options>}\}}
  
  The \code+ocg+ family is used to specify the options used to add a
  scope into an OCG.
  
  \begin{list}{}
  \item
    
    \noindent\style+/tikz/ocg/ref+\argument{=\emph{<refname>}}\defaultvalue{no
    default}
    
    This option add the current scope to the OCG referenced by
    \texttt{refname}. If this OCG does not exist, it is created with
    \texttt{name} and visibility \texttt{status} specified by the
    two options below.

    \noindent\style+/tikz/ocg/name+\argument{=\emph{<name>}}\defaultvalue{no
    default, initially empty}
    
    It is the \texttt{\emph{name}} of the OCG as it appears in the PDF
    viewer. If the OCG is already created, this option is useless.
    
    \noindent\style+/tikz/ocg/status+\argument{=\emph{<visibility>}}\defaultvalue{no
      default, initially \texttt{visible}}
    
    Specify the initial visibility state of the OCG. Permissible values
    are \texttt{visible}, and \texttt{invisible}. If the OCG is already
    created, this option is useless.
    
  \end{list}

  \begin{note}
    If you prefer, you can also use the \code+ogc+ environment in a
    \code+tikzpicture+. The \code+pgfonlayer+ environment is special:
    inside, you must reuse options below, or use a new \code+ocg+
    environment.
  \end{note}

\end{list}  

\subsubsection*{How to transform nodes or paths into clickable links}

\begin{list}{}
\item
    
\noindent\style+/tikz/switch ocg+\argument{=\{\emph{<OCGs list>}\}}
  
  This style transforms the current path or the current node in a link acting as
  if it was produced by the macro \code+\switchocg+ (the visibility
  status of referenced OCGs is reversed).
  
  \noindent\style+/tikz/show ocg+\argument{=\{\emph{<OCGs list>}\}}
  
  This style transforms the current path or the current node in a link acting as
  if it was produced by the macro \code+\showocg+ (the referenced OCGs
  are made visible).

  \noindent\style+/tikz/hide ocg+\argument{=\{\emph{<OCGs list>}\}}

  This style transforms the current path or the current node in a link acting as
  if it was produced by the macro \code+\hideocg+ (the referenced OCGs
  are made invisible).

  \noindent\style+/tikz/actions ocg+\argument{=\{\emph{<OCGs
      list>}\}\{\emph{<OCGs list>}\}\{\emph{<OCGs list>}\}}

  This style transforms the current path or the current node in a link acting as
  if it is produced by the macro \code+\actionsocg+ (the visibility
  status of OCGs of the first list is reversed, the OCGs in the second
  list are made visible and those of the third list are made invisible).

  \noindent\style+/tikz/switch ocg with mark on+\argument{=\{\emph{<ocg
      reference>}\}\{\emph{<OCGs list>}\}}

  \noindent\style+/tikz/switch ocg with mark off+\argument{=\{\emph{<ocg
      reference>>}\}\{\emph{<OCGs list>}\}}

  These styles transform the current path or the current node in a link acting
  as if it is produced by the macro \code+\switchocg+ (the visibility
  status of referenced OCGs in the list is reversed).

  A mark (currently a simple cross) is drawn over the current path or
  node in an OCG whose reference is \texttt{\emph{ocg reference}}. The
  visibility status of this OCG will be reversed as those of the entire
  list.

  If the OCG whose reference is \texttt{\emph{ocg reference}} does not
  exist, it is created with an empty name and its initial visibility
  state is true with \code+on+ and false with \code+off+.

\end{list}

\begin{note}
  Due to limitation of PDF, whatever the shape of the current path or
  node is, it is its \emph{bounding box} that is used to make the link:
  the link is always \emph{rectangular} and \emph{horizontal}!
\end{note}

\subsubsection*{Example with \TikZ{}}

\begin{filecontents*}{ocgx-example-3}
\begin{tikpicture}
  \begin{scope}[ocg={name=TikZ example,ref=tikzex,status=visible}
    \fill[orange] (0,0) circle (1);
  \end{scope}
  \node[draw,switch ocg=tikzref] at (2,0) {Switch};
\end{tikpicture}
\end{filecontents*}
\TeXexample{ocgx-example-3}{}



\section{Examples}

The document \code+demo-ocgx.tex+ provides several examples of usage of
package \code+ocgx+ with \TikZ{} (and \code+beamer+).

\section{Limits and bugs}

\begin{enumerate}
\item Links are always horizontal rectangles!
\item An \code+ocg+ environment spanning across multiple pages are not
  detected and don't work correctly.
\item The packages \code+ocg-p+ and \code+ocgx+ are not compatible with
  Plain-\TeX{}.
\item While \code+ocg-p+ is usable with \code+pdflatex+ and
  \code+xelatex+, \code+ocgx+ works only with \code+pdflatex+ (and
  \code+lualatex+).
\end{enumerate}

\section{Development and history}
This package is still experimental. It is released on CTAN. You can
donwload the latest version from \url{https://github.com/polgab/ocgx}. Any
help to participate in its development is welcome: contact the
maintainer (\url{paul.gaborit@gmail.com}).

\paragraph{version 0.5} (2012-12-07) Now, the \code+ocgx+ package uses
the new \code+ocg-p+ package instead of the \code+ocg+ package : the
layers can be nested in the layer toolbar of the PDF viewer.

\paragraph{version 0.4} (2012-11-14) Added dependancy to \texttt{calc}
TikZ library. Fixed bug: bad lists in \code+\actionsocg+.

\paragraph{version 0.3} (2012-09-30) Complete documentation for part
\emph{Usage with TikZ} and correct TDS archive.

\paragraph{version 0.2} (2012-09-27)  First release on CTAN.
\end{document}



%%% Local Variables: 
%%% mode: latex
%%% TeX-master: t
%%% End: