% 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{}\}} 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{}}\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{}}\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{}}\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{}\}} 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{}\}} 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{}\}} 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{}\}\{\emph{}\}\{\emph{}\}} 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{}\}\{\emph{}\}} \noindent\style+/tikz/switch ocg with mark off+\argument{=\{\emph{>}\}\{\emph{}\}} 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: