summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/ocgx2/README.txt
blob: e1788656734faba2af8aa24c84aeb645e7b7d9df (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
==================================
 The `ocgx2' LaTeX Package

 https://gitlab.com/agrahn/ocgx2

 (C) 2015--\today Alexander Grahn
==================================


1. Introduction
===============

This package serves as a drop-in replacement for the already existing
packages `ocgx' by Paul Gaborit and `ocg-p' by Werner Moshammer for the
creation of PDF Layers.

It re-implements the functionality of the `ocg', `ocgx' and `ocg-p'
packages and adds support for all known engines and back-ends including

  *  LaTeX --> dvips --> ps2pdf/Distiller
  *  (Xe)LaTeX --> (x)dvipdfmx
  *  pdfLaTeX, luaLaTeX

To enable dvipdfmx support, pass `dvipdfmx' globally as a class option.

Also, it adds some minor improvements and bug fixes, such as package
options, remembering option settings of re-opened ocgs, correct behaviour
of layer switching links that were themselves placed on layers, correct
listing of (nested) ocgs in the layers tab of PDF viewers, compatibility
with the `animate' and `media9' packages.

  * New features:

    +  PDF layers extending over page breaks
    +  grouping PDF layers into Radio Button Groups
    +  additional keys for the TikZ interface of package `ocgx'
    +  re-implementing `hyperref's `ocgcolorlinks' option for creating
       OCG coloured links, which are printed on paper in the default
       text colour and which can, unlike the original `hyperref'
       implementation, extend over line and page breaks.


2. Usage
========

\usepackage[<options>]{ocgx2}

\begin{ocg}[<options>]{<layer name>}{<layer id>}{<initial visibility>}
  ... material to be put on a PDF layer ...
\end{ocg}

With <initial visibility> = ( on | true | 1 )  |  ( off | false | 0 )

and <options> : viewocg = always | never | ifvisible
                printocg =  always | never | ifvisible
                exportocg =  always | never | ifvisible

    not in ocgx, ocg-p:

                showingui (to be preferred over `listintoolbar' of ocgx/ocg-p)
                radiobtngrp = <group name> (string; environment-only option)

                tikz  (package-only option)
                ocgcolorlinks  (package-only option)

Package options have global scope. Environment options override package
options locally.

Layers can be added to one or several Radio Button Groups using the new
option `radiobtngrp'. From all layers within a Radio Button Group only
one can be enabled at a time. Enabling a layer, e. g. in the Layers tab
of the PDF viewer, automatically hides the previously visible layer.
Option `radiobtngrp' can be used repeatedly for the same OCG in order
to add the layer to more than one Radio Button Group.

`ocg' environments can be nested and span multiple pages.

See the `ocg-p' manual about the environment usage and the meaning of
the remaining options:

  texdoc ocg-p

Clickable links for switching PDF layer visibility are created with:

  \switchocg[<trigger>]{<layer IDs to toggle, space separated>}{<link text>}
  \showocg[<trigger>]{<layer IDs to switch ON, space separated>}{<link text>}
  \hideocg[<trigger>]{<layer IDs to switch OFF, space separated>}{<link text>}
  \actionsocg[<trigger>]{<IDs to toggle>}{<IDs to switch ON>}{<IDs to switch OFF>}{<link text>}

For details about their usage, read the `ocgx' package manual:

  texdoc ocgx

By default, links are triggered on mouse-click. Other triggers are possible
with `ocgx2'. For this, `ocgx2' provides the optional argument [<trigger>] to
the commands listed above. Choose one of

  onmousenter, onmouseexit, onmousedown, onmouseup, onmouseall

for  <trigger>. In order to listen to more than one mouse event, use
`onmouseall'. Layer IDs in the mandatory argument(s) must then be grouped with
commas as follows:

  <mouse-enter group>, <mouse-exit group>, <mouse-down group>, <mouse-up group>

Any of these groups may be left empty in order to configure only some
mouse triggers. Inside the groups, layer IDs are separated by space.


3. Package option `ocgcolorlinks'
=================================

Is a re-implementation of the same `hyperref' option for creating OCG-
coloured links, which are printed on paper in the default text colour.

  \usepackage{hyperref} % do NOT set [ocgcolorlinks] here!
  \usepackage[ocgcolorlinks]{ocgx2}

Unlike the original `hyperref' implementation, OCG-coloured links are now
allowed to extend over line and page breaks. Moreover, with pdfLaTeX/LuaLaTeX,
OCG coloured links can be nested.

Breakable OCG coloured links work best with normal text as link text. If
the link text is mixed with graphical content, such as from external files or
inline graphics (e. g. TikZ) and even \fbox-ed text, these graphical parts must
be enclosed in

  \ocglinkprotect{...}

For example:

  \href{http://ctan.org}{Visit me on
                    \ocglinkprotect{\includegraphics{ctan-lion}}!}


4. Usage with TikZ
==================

`ocgx2' uses code from file `tikzlibraryocgx.code.tex' by P. Gaborit to
enable TikZ styles for creating PDF Layers and clickable layer switching
links in the `tikzpicture' context.

Just say:

  \usepackage[tikz]{ocgx2}

instead of

  \usepackage{tikz}
  \usetikzlibrary{ocgx}

to enable these TikZ styles and read the `ocgx' documentation about
their usage:

  texdoc ocgx

The key `/tikz/ocg/opts' was added to the list in section
`How to add TikZ scopes into OCGs' in the `ocgx' manual:

  /tikz/ocg/opts={<ocg options>}

It allows passing `ocg'-environment options (`viewocg', `printocg', `exportocg',
`showingui', `radiobtngrp') to the TikZ scope.

Moreover, TikZ objects to be turned into OCG switching hyperlinks (section "How
to transform nodes or paths into clickable links" in the `ocgx' manual) accept
the additional key

  /tikz/trigger ocg = onmousenter | onmouseexit | onmousedown | onmouseup
                      | onmouseall

which makes them listen to various mouse events, as explained above.


                     * * *


This material is subject to the LaTeX Project Public License. See

   http://mirrors.ctan.org/macros/latex/base/lppl.txt

for the details of that license.