DynaPDF Manual - Page 130

Previous Page 129   Index   Next Page 131

Function Reference
Page 130 of 787
Return values:
If the function succeeds the return value is the handle of the JavaScript, a value greater or equal
zero. If the function fails the return value is a negative error code.
LGRP* pdfAddLayerToDisplTree(
const PPDF* IPDF,
// Instance pointer
LGRP* Parent,
// Parent node or NULL
SI32 Layer,
// Layer (OCG) handle or -1
const char* Title) // Group title or NULL
The function adds a layer or group to the layer display tree. The layer display tree is used in viewer
applications to show the available layers in a PDF file and to interactively hide or unhide layers.
If we talk about a layer then we mean a handle of an OCG (Optional Content Group, see section
Layers (Optional Content) for further information). OCMDs (Optional Content Membership
Dictionaries) cannot be added to the tree, since OCMDs represent a visibility expression and no
layer that can be displayed or hidden.
Note that the function CreateOCG() adds a layer automatically to the display tree if the parameter
DisplayInUI was set to true. So, the parameter must be set to false if you want to build the tree
The display tree consists of nested arrays. A sub array represents a new group which can optionally
contain a title, one or more layers, or both. The order in which layers are added or how they are
grouped can be freely choosen. However, it is usually best to create a layer tree with the same order
and nesting levels as in the document. Layers which were not added to the tree will not be
displayed in a viewer. This can be useful if a user should not be able to change the state of a layer
It is also possible to lock layers if necessary (see LockLayer() for further information).
As mentioned above, the parameters Layer and Title are both optional. This results in four possible
combinations which produce different results.
If no layer is provided then the function creates a new group (a new sub array). However, the parent
node cannot be empty (with one exception). At least one element must be added to an empty group
before a new group can be added to it.
Take a look on the examples on the next page to understand how it works.
Return values:
If the function succeeds then the return value is a pointer of the newly created group. If no new
group was created then the return value is the pointer of the parent group that was passed to the
function. If the function fails then the return value is NULL.

Previous topic: AddJavaScript

Next topic: AddMaskImage, AddObjectToLayer

Start Chat