% Copyright (C) 2012 by Werner Moshammer
% This file may be distributed and/or modified under the LaTeX Project Public License

%\documentclass[11pt]{article}
\documentclass[a4paper]{ltxdoc}

\usepackage{tikz}
\usetikzlibrary{arrows,automata}

\usepackage{hyperref}
\usepackage{fancyvrb}
%\usepackage{ocg-p}
\usepackage{framed}




\usepackage{listings}
%\usepackage{xcolor}

\lstset{
  language=[LaTeX]TeX,
  basicstyle=\footnotesize\ttfamily,
  upquote=true,
  frame=single,
  keywordstyle=\color{blue}\bfseries,
  emphstyle=\color{blue}\bfseries,
  backgroundcolor=\color{black!05},
  fontadjust=true,
  flexiblecolumns=true,
  breaklines=true, 
  emph={ocg}
}

\newcommand{\TikZ}{Ti\emph{k}Z}

\newcommand*{\pkg}[1]{\textsf{#1}}
\newcommand*{\mail}[1]{\href{mailto:#1}{\texttt{#1}}}

\title{The \pkg{ocg-p} package\thanks{This manual correspondends to \pkg{ocg-p} v0.3, dated 2012/12/01}}
\author{DI Werner Moshammer\thanks{Contact me when you find mistakes in the manual: \mail{sendmail.werner@gmail.com}}}
\date{2012/12/01}

\begin{document}

\maketitle

\tableofcontents



\begin{abstract}
The \pkg{ocg-p} package provides the environment that allows to insert OCG (Optional Content Group) into PDF documents without JavaScript. These OCGs can be simply described as layers from the user's point of view. 

The \pkg{ocg-p} package is intended as a full replacement for the file |ocg.sty| which is part of the \pkg{asymptote} package. While |ocg.sty| is limited to be used with |pdflatex|, the \pkg{ocg-p} package can also be used with |xelatex|. Additionally nested OCGs (layers inside of another layer) are handled as such.

\end{abstract}
\newpage

\section{Introduction}
The \pkg{ocg-p} package provides the environment that allows to insert OCG (Optional Content Group) into PDF documents without JavaScript. These OCGs can be simply described as layers from the user's point of view.

OCGs are part of the PDF specification since version 1.5 and are described in the \href{http://wwwimages.adobe.com/www.adobe.com/content/dam/Adobe/en/devnet/pdf/pdfs/pdf_reference_archives/PDFReference15_v5.pdf}{PDF Reference} as:

\begin{quote}
Optional content (PDF 1.5) refers to sections of content in a PDF document that
can be selectively viewed or hidden by document authors or consumers. This capability
is useful in items such as CAD drawings, layered artwork, maps, and
multi-language documents.
\end{quote} 

The \pkg{ocg-p} package is intended as a full replacement for the file |ocg.sty| which is part of the \pkg{asymptote} package. While |ocg.sty| is limited to be used with |pdflatex|, the \pkg{ocg-p} package can also be used with |xelatex|. Additionally nested OCGs (layers inside of another layer) are handled as such.

\section{Usage}
Here is a quick summary of the usage of \pkg{ocg-p}.

\subsection{Package}
Just load the package placing
\begin{quote}
   |\usepackage{ocg-p}|
 \end{quote}
in the preamble of your \LaTeX{}  source file. There are no options available at the moment.

Important: If packages are used, which use the original \pkg{ocg} package then the \pkg{ocg-p} should be loaded after these packages. The |ocg| environment from the \pkg{ocg} package is replaced in this case.

\subsection{Commands and Environments}
At the moment the \pkg{package} has only one usable environment. To create a OCG layer you have to use the |ocg| environment with three required arguments. Because it is intended as a replacement for the file |ocg.sty| this command can be used in the same way as it is used in |ocg.sty|.
\begin{verbatim}
\begin{ocg}{layer name}{layer id}{initial visibility}
content ...
\end{ocg}
 \end{verbatim}
The arguments are:
 \begin{itemize} 
 \item \textit{layer name}:
This name is shown in in the layer toolbar of the (PDF) viewer, where the visiblity of the layers can be changed.
 \item \textit{layer id}:
A unique id which is internally used by the OCG environment to reference the layer. Only letters and numbers are allowed
 \item \textit{initial visibility}:
Sets the initial visibility when the document is opend. Only 0 and 1 are allowed (0 for invisible, 1 for visible)
 \item \textit{content}:
The content of the layer itself.
 \end{itemize}



\section{Examples}
A few examples follow, showing the usage of this package.

\subsection{Example 1: Three simple text layers}
Here is a simple example with three layers with text content, where the second layer is set invisible when the document is opened. 

\begin{lstlisting}
\documentclass{article}
\usepackage{ocg-p}
\begin{document}

\begin{ocg}{First layer}{oc1}{1}
  The first Layer is visible at start.
\end{ocg}

\begin{ocg}{Second layer}{oc2}{0}
  The second layer is not visible at start.
\end{ocg}

\begin{ocg}{Third layer}{oc3}{1}
 The third layer is visible at start.
\end{ocg}

This text is not inside of a layer and always visible.

\end{document}
\end{lstlisting}

This will produce the following output, where the text in the second layer is invisible when the document is opend:
\begin{framed}

 The first Layer is visible at start.

\makebox[1pt][l]{ }

The third layer is visible at start.

This text is not inside of a layer and always visible.

\end{framed}

The visiblity of the three layers can be changed with the layer toolbar of the viewer. If all layers are made invisible it looks like that:

\begin{framed}

\makebox[1pt][l]{ }

\makebox[1pt][l]{ }

\makebox[1pt][l]{ }

\makebox[1pt][l]{ }

This text is not inside of a layer and always visible.

\end{framed}


\subsection{Example 2: OGC and the \TikZ{} package}
Using the \pkg{ocg-p} package with the \pkg{Ti\emph{k}Z} package is very valuable, because it is possible to show or hide some parts of the picture with the layer toolbar of the viewer. Here a first code example:

\begin{lstlisting}
\begin{tikzpicture}[node distance=3cm,every state/.style={fill=green!20},auto]
\begin{ocg}{grid}{ocgridid}{1}
  \draw[black!20] (-1,-1) grid (4,2);
\end{ocg}

\begin{ocg}{states}{ocstatesid}{1}
  \node[state] (q_a) {$q_a$};
  \node[state] (q_b) [right of=q_a] {$q_b$};
\end{ocg}

\begin{ocg}{edges}{ocedgesid}{1}
  \path[->] 
  (q_a) edge node {0} (q_b)
        edge [loop above] node {0} ()
  (q_b) edge [loop above] node {1} ();
\end{ocg}
\end{tikzpicture}
\end{lstlisting}

When the document is opend the following is shown:

\begin{framed}
\begin{tikzpicture}[node distance=3cm,every state/.style={fill=green!20},auto]
  \draw[black!20] (-1,-1) grid (4,2);
  \node[state] (q_a) {$q_a$};
  \node[state] (q_b) [right of=q_a] {$q_b$};
  \path[->] 
  (q_a) edge node {0} (q_b)
        edge [loop above] node {0} ()
  (q_b) edge [loop above] node {1} ();
\end{tikzpicture}
\end{framed}

But, for example, the edges could be made invisible with the layer toolbar:
\begin{framed}
\begin{tikzpicture}[node distance=3cm,every state/.style={fill=green!20},auto]
  \draw[black!20] (-1,-1) grid (4,2);
  \node[state] (q_a) {$q_a$};
  \node[state] (q_b) [right of=q_a] {$q_b$};
\end{tikzpicture}
\end{framed}

Or the grid could be made invisible:
\begin{framed}
\begin{tikzpicture}[node distance=3cm,every state/.style={fill=green!20},auto]
  \draw[white!0] (-1,-1) grid (4,2);
  \node[state] (q_a) {$q_a$};
  \node[state] (q_b) [right of=q_a] {$q_b$};
  \path[->] 
  (q_a) edge node {0} (q_b)
        edge [loop above] node {0} ()
  (q_b) edge [loop above] node {1} ();
\end{tikzpicture}
\end{framed}


\subsection{Example 3: OGC and the \TikZ{} package again}
These example should show how the layers can be used within text.
\begin{lstlisting}
The following text can be toggled: 
\begin{tikzpicture}[baseline=0]
\tikzstyle{nome}=[anchor=base,outer sep=0,inner sep=0,minimum height=.45cm,minimum width=4.4cm]
\begin{ocg}{blue text}{ocblueid}{1}
  \node[nome,blue]        (p1)  {\parbox[b][][t]{4.4cm}{This text is written in blue.}};
\end{ocg}
\begin{ocg}{red text}{ocredid}{0}
  \node[overlay,nome,red] (p2)  {\parbox[b][][t]{4.4cm}{This text is written in red.}};
\end{ocg}
\end{tikzpicture}
And now the text is black again.
\end{lstlisting}

With the layer toolbar of the viewer it is possible to activate or deactivate the two layers, so there are three possibilities how it can be seen:
\begin{framed}
\noindent The following text can be toggled: \parbox[b][][t]{4.4cm}{\textcolor{blue}{This text is written in blue.}} And now the text is black again.
\end{framed}

\begin{framed}
\noindent The following text can be toggled: \parbox[b][][t]{4.4cm}{\textcolor{red}{This text is written in red.}} And now the text is black again.
\end{framed}




\begin{framed}
\noindent The following text can be toggled: 
\begin{tikzpicture}[baseline=0]
\tikzstyle{nome}=[anchor=base,outer sep=0,inner sep=0,minimum height=.45cm,minimum width=4.4cm]
  \node[nome,blue]        (p1)  {\parbox[b][][t]{4.4cm}{This text is written in blue.}};
  \node[overlay,nome,red] (p2)  {\parbox[b][][t]{4.4cm}{This text is written in red.}};
\end{tikzpicture}
And now the text is black again.
\end{framed}




\section{Possible future developement}

These ideas may appear in new versions of the \pkg{ocg-p} package:

\begin{itemize}
\item The package should work with dvips.
\item The |ocg| environment should accept options like |notprintable|, |alwaysprinted|, |notinlayertoolbar| (means that the visiblity is not changeable), |notexportable|, |alwaysexported|.
So it is for example possible that a layer is not visible but is printed.
\item Commands for buttons which make all layers visible or invisible.
\end{itemize}


\section{Implementation}
The implementation is rather standard. At first main switches are defined to distinguish between the possible drivers |pdflatex|, |xelatex| and |dvips| (not fully implemented yet). Then the environment is defined.


\lstinputlisting[firstline=1, lastline=320]{ocg-p.sty}

%\VerbatimInput[fontsize=\footnotesize,firstline=1,lastline=320]{ocg-p.sty}


\section{Change history}

 \begin{description}
\item[0.1] Initial version, only usable with xetex, not based on the \pkg{ocg} package and therefore the arguments were a little bit different.

\item[0.2] The \pkg{ocg-p} package was made compatible with the \pkg{ocg} package using the same environment name and arguments and using the |aux| file in the same way. Support for |pdflatex| was added. First public version.

\item[0.3] Fixed bug in |ocg| environment (missing \verb+\fi+). Fixed a bug if |xelatex| is used. Nestes OCGs (layers inside another layer) are now handled as such.

\item[0.4] Planned: Not in a |.sty| file anymore, now using |.dtx|.

\end{description}


\end{document}