| Components | All | New | MacOS | Windows | Linux | iOS | ||||
| Examples | Mac & Win | Server | Client | Guides | Statistic | FMM | Blog | Deprecated | Old | |
DynaPDF.CreateOCG
Creates an Optional Content Group (OCG) also called layer.
| Component | Version | macOS | Windows | Linux | Server | iOS SDK |
| DynaPDF | 11.5 | ✅ Yes | ✅ Yes | ✅ Yes | ✅ Yes | ✅ Yes |
MBS( "DynaPDF.CreateOCG"; PDF; Name; DisplayInUI; Visible; Intent ) More
Parameters
| Parameter | Description | Example |
|---|---|---|
| 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. |
1 |
| Visible | Intitial state of the OCG. Pass 1 to show and 0 to hide. |
1 |
| Intent | The intent for the layer. Pass Design, View or All. |
"all" |
Result
Returns handle number or error.
Description
Creates 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.
The parameter DisplayInUI specifies whether the OCG should be displayed in the user interface of a PDF viewer. The state of invisible layers (the ones which are not displayed in the user interface) can only be changed programmatically, e.g. with a DynaPDF.SetOCGState or Javascript actions. Also if DisplayInUI is set to false, the parameter Name is still required.
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 Visible specifies the initial state of the OCG. If set to false, contents that belongs to this OCG remains invisible until the state will be changed due to interaction with the user interface or programmatically with a DynaPDF.SetOCGState or Javascript action.
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.
See also
Release notes
- Version 11.5
- Added DynaPDF.CreateOCG function.
Blog Entries
This function checks for a license.
Created 5th October 2021, last changed 5th October 2021
