Components Crossplatform Mac & Win Server Client Old Deprecated Guides Examples Videos
New in version: 10.2 10.3 10.4 10.5 11.0 11.1 11.2 11.3 11.4 11.5 Statistic FMM Blog
Creates an Optional Content Group (OCG) also called layer.
|DynaPDF||11.5||✅ Yes||✅ Yes||✅ Yes||✅ Yes||✅ Yes|
|The PDF reference returned from DynaPDF.New.|
|Name||Layer name (required)||"test"|
|DisplayInUI||Display the OCG in the user interface?
Pass 1 to show and 0 to hide.
|Visible||Intitial state of the OCG.
Pass 1 to show and 0 to hide.
|Intent||The intent for the layer.
Pass Design, View or All.
Returns handle number or error.
DescriptionCreates an Optional Content Group (OCG) also called layer.
Content that belongs to an OCG can be made visible or invisible dynamically by users of conforming readers. OCGs are mostly called Layers because Optional Content and Layers share the same basic functionality. A layer is a piece of content that is associated with an OCG.
If DisplayInUI is set to true the layer will be added to the root of the layer tree. To reflect nesting levels, layer groups and so on, it is also possible to configure the layer tree manually with DynaPDF.AddLayerToDisplTree. The parameter DisplayInUI should be set to false in this case so that the layer will not already be added to the tree.
The parameter Intent specifies the intended use of the graphics in the group. It provides a way to distinguish between different intended uses of optional content. For example, many document design applications, such as CAD packages, offer layering features for collecting groups of graphics together and selectively hiding or viewing them for the convenience of the author. However, this layering may be different (at a finer granularity, for example) than would be useful to consumers of the document. Therefore, it is possible to specify different intents for optional content groups within a single document. A conforming reader may decide to use only groups that are of a specific intent.
The Intent entry can be used to create different configurations for viewing and design applications. However, this functionality is not yet implemented in DynaPDF.
How to make content optional?
Page contents, such as text, images, and vector graphics can be associated with an OCG with DynaPDF.BeginLayer / DynaPDF.EndLayer. Anything that is drawn between these function calls becomes part of the layer or OCG.
Interactive objects such as Annotations and Form Fields can be added to a layer with DynaPDF.AddObjectToLayer. However, interactive objects can be associated with exactly one layer at time. In cases where the visibility should depend on more than one OCG it is possible to connect the object with an Optional Content Membership Dictionary (OCMD). OCMDs accept an array of OCG handles and a visibility expression that defines when the associated content should become visible or invisible (see DynaPDF.CreateOCMD for further information). OCMDs can also be used with DynaPDF.BeginLayer, e.g. if too many nested BeginLayer() calls would be required to achieve the same result.
Images and templates can be associated with an OCG or OCMD too. This can be useful if the object must be drawn outside of the parent layers or to achieve more complex visibility expressions.
If the function succeeds the return value is the OCG handle, a value greater or equal zero. If the function fails the return value is an error.
See also CreateOCG function in DynaPDF manual.
- Version 11.5
- Added DynaPDF.CreateOCG function.
Created 5th October 2021, last changed 5th October 2021
Feedback: Report problem or ask question.
MBS Xojo blog