Xojo Developer Conference
25/27th April 2018 in Denver.
MBS Xojo Conference
6/7th September 2018 in Munich, Germany.

DynaPDF Manual - Page 123

Previous Page 122   Index   Next Page 124

Function Reference
Page 123 of 750
AddLayerToDisplTree
Syntax:
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
manually.
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 interactively.
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: AddObjectToLayer