PDF SDK Documentation

Comprehensive Guide for Developers: Features, Integration, and API Reference

Loading...
Searching...
No Matches
Typedefs | Enumerations | Functions
optional_content.h File Reference

Optional Content API. More...

#include <pdfsdk/core/api_macro.h>
#include <pdfsdk/core/atoms.h>
#include <pdfsdk/errors.h>
#include <pdfsdk/math_types.h>

Go to the source code of this file.

Typedefs

typedef struct PDOCGRec_ * PDOCG
 Represents an optional content group (OCG) in a PDF document.
typedef struct PDOCMDRec_ * PDOCMD
 Represents an optional content membership dictionary.
typedef struct PDOCConfigRec_ * PDOCConfig
typedef struct PDOCContextRec_ * PDOCContext
 A runtime optional-content visibility context.
typedef void(PDFSDK_CALLCONV * PDOCConfigChangedProc) (void *clientData)
typedef PDErrCode(PDFSDK_CALLCONV * PDOCRuntimeUsageProc) (PDOCG ocg, PDOCUsageCategory category, bool *pApply, bool *pState, void *userData)

Enumerations

enum  PDOCDrawMode { kPDOCDrawVisibleOC , kPDOCDrawAllOC , kPDOCDrawNoOC }
 Controls how optional content is drawn or enumerated for a context. More...
enum  PDOCUsageEvent { kPDOCUsageView , kPDOCUsagePrint , kPDOCUsageExport }
 A usage event: the situation in which a document is being used — viewed on screen, printed, or exported. More...
enum  PDOCUsageCategory {
  kPDOCUsageCategoryCreatorInfo , kPDOCUsageCategoryLanguage , kPDOCUsageCategoryExport , kPDOCUsageCategoryZoom ,
  kPDOCUsageCategoryPrint , kPDOCUsageCategoryView , kPDOCUsageCategoryUser , kPDOCUsageCategoryPageElement
}
 A category of an optional-content group's usage (/Usage) dictionary. More...
enum  PDOCVisibilityPolicy { kPDOCVisibilityPolicyAnyOn , kPDOCVisibilityPolicyAllOn , kPDOCVisibilityPolicyAnyOff , kPDOCVisibilityPolicyAllOff }
 The visibility policy of an optional content membership dictionary (OCMD). More...
enum  PDOCGStateOperation { kPDOCGStateOperationOff , kPDOCGStateOperationOn , kPDOCGStateOperationToggle }
 Specifies whether the targeted Optional Content Group (OCG) should be visible or hidden when the action (operation) is executed. More...

Functions

PDF_CORE_API PDErrCode PDFSDK_CALLCONV PDDocAttachOCConfigChangedCallback (PDDoc doc, PDOCConfigChangedProc proc, void *clientData)
PDF_CORE_API PDErrCode PDFSDK_CALLCONV PDDocDetachOCConfigChangedCallback (PDDoc doc, PDOCConfigChangedProc proc, void *clientData)
PDF_CORE_API PDErrCode PDFSDK_CALLCONV PDDocNotifyOCConfigChanged (PDDoc doc)
PDF_CORE_API PDErrCode PDFSDK_CALLCONV PDDocSetOCConfig (PDDoc doc, PDOCConfig config)
PDF_CORE_API PDErrCode PDFSDK_CALLCONV PDDocGetOCConfig (PDDoc doc, PDOCConfig *pConfig)
PDF_CORE_API PDErrCode PDFSDK_CALLCONV PDDocGetNumOCAltConfigs (PDDoc doc, size_t *pNumConfigs)
PDF_CORE_API PDErrCode PDFSDK_CALLCONV PDDocGetOCAltConfig (PDDoc doc, size_t index, PDOCConfig *pConfig)
PDF_CORE_API PDErrCode PDFSDK_CALLCONV PDDocCreateOCG (PDDoc doc, const wchar_t *name, size_t nameSize, PDOCG *pOCG)
PDF_CORE_API PDErrCode PDFSDK_CALLCONV PDDocGetNumOCGs (PDDoc doc, size_t *pNumOCGs)
PDF_CORE_API PDErrCode PDFSDK_CALLCONV PDDocGetOCG (PDDoc doc, size_t index, PDOCG *pOCG)
PDF_CORE_API PDErrCode PDFSDK_CALLCONV PDOCGFromPDObject (PDObject object, PDOCG *pOCG)
PDF_CORE_API PDErrCode PDFSDK_CALLCONV PDOCGGetPDObject (PDOCG ocg, PDObject *pObject)
PDF_CORE_API PDErrCode PDFSDK_CALLCONV PDOCGSetName (PDOCG ocg, const wchar_t *name, size_t nameSize)
PDF_CORE_API PDErrCode PDFSDK_CALLCONV PDOCGGetName (PDOCG ocg, wchar_t *buffer, size_t bufSize, size_t *pSize)
PDF_CORE_API PDErrCode PDFSDK_CALLCONV PDOCGSetUsageEntry (PDOCG ocg, PDOCUsageCategory category, PDObject entry)
PDF_CORE_API PDErrCode PDFSDK_CALLCONV PDOCGGetUsageEntry (PDOCG ocg, PDOCUsageCategory category, PDObject *pEntry)
PDF_CORE_API PDErrCode PDFSDK_CALLCONV PDOCMDFromPDObject (PDObject object, PDOCMD *pOCMD)
PDF_CORE_API PDErrCode PDFSDK_CALLCONV PDOCMDGetPDObject (PDOCMD ocmd, PDObject *pObject)
PDF_CORE_API PDErrCode PDFSDK_CALLCONV PDOCMDCreateFromOCG (PDOCG ocg, PDOCMD *pOCMD)
PDF_CORE_API PDErrCode PDFSDK_CALLCONV PDOCMDCreateFromOCGs (const PDOCG *ocgs, size_t ocgCount, PDOCVisibilityPolicy policy, PDOCMD *pOCMD)
PDF_CORE_API PDErrCode PDFSDK_CALLCONV PDOCMDIsVisible (PDOCMD ocmd, PDOCContext ctx, bool *pVisible)
PDF_CORE_API PDErrCode PDFSDK_CALLCONV PDOCMDGetVisibilityPolicy (PDOCMD ocmd, PDOCVisibilityPolicy *pPolicy)
PDF_CORE_API PDErrCode PDFSDK_CALLCONV PDOCMDSetVisibilityPolicy (PDOCMD ocmd, PDOCVisibilityPolicy policy)
PDF_CORE_API PDErrCode PDFSDK_CALLCONV PDOCMDGetNumOCGs (PDOCMD ocmd, size_t *pNumOCGs)
PDF_CORE_API PDErrCode PDFSDK_CALLCONV PDOCMDGetOCG (PDOCMD ocmd, size_t index, PDOCG *pOCG)
PDF_CORE_API PDErrCode PDFSDK_CALLCONV PDOCConfigFromPDObject (PDObject object, PDOCConfig *pOCG)
PDF_CORE_API PDErrCode PDFSDK_CALLCONV PDOCConfigGetPDObject (PDOCConfig ocg, PDObject *pObject)
PDF_CORE_API PDErrCode PDFSDK_CALLCONV PDOCConfigGetOrder (PDOCConfig config, PDObject *pOrder)
PDF_CORE_API PDErrCode PDFSDK_CALLCONV PDOCConfigSetInitialState (PDOCConfig config, PDOCG ocg, bool state, bool preserveRB)
PDF_CORE_API PDErrCode PDFSDK_CALLCONV PDOCConfigGetInitialState (PDOCConfig config, PDOCG ocg, bool *pState)
PDF_CORE_API PDErrCode PDFSDK_CALLCONV PDOCConfigAddOrderEntry (PDOCConfig config, PDOCG ocg)
PDF_CORE_API PDErrCode PDFSDK_CALLCONV PDOCConfigAddAutoState (PDOCConfig config, PDOCUsageEvent event, const PDOCG *ocgs, size_t ocgCount, const PDOCUsageCategory *categories, size_t categoryCount)
PDF_CORE_API PDErrCode PDFSDK_CALLCONV PDOCConfigSetLocked (PDOCConfig config, PDOCG ocg, bool locked)
PDF_CORE_API PDErrCode PDFSDK_CALLCONV PDOCConfigIsLocked (PDOCConfig config, PDOCG ocg, bool *pLocked)
PDF_CORE_API PDErrCode PDFSDK_CALLCONV PDOCContextCreate (PDOCConfig config, PDOCContext *pCtx)
PDF_CORE_API PDErrCode PDFSDK_CALLCONV PDOCContextCopy (PDOCContext src, PDOCContext *pCtx)
PDF_CORE_API PDErrCode PDFSDK_CALLCONV PDOCContextGetOCGState (PDOCContext ctx, PDOCG ocg, bool *pState)
PDF_CORE_API PDErrCode PDFSDK_CALLCONV PDOCContextSetOCGState (PDOCContext ctx, PDOCG ocg, bool state, bool preserveRB)
PDF_CORE_API PDErrCode PDFSDK_CALLCONV PDOCContextResetStates (PDOCContext ctx, bool all_on)
PDF_CORE_API PDErrCode PDFSDK_CALLCONV PDOCContextApplyAutoStates (PDOCContext ctx, PDOCUsageEvent event, PDOCRuntimeUsageProc proc, void *userData, bool *pApplied)
PDF_CORE_API PDErrCode PDFSDK_CALLCONV PDOCContextSetOCDrawMode (PDOCContext ctx, PDOCDrawMode mode)
PDF_CORE_API PDErrCode PDFSDK_CALLCONV PDOCContextGetOCDrawMode (PDOCContext ctx, PDOCDrawMode *pMode)
PDF_CORE_API PDErrCode PDFSDK_CALLCONV PDOCContextSetNonOCDrawing (PDOCContext ctx, bool draw)
PDF_CORE_API PDErrCode PDFSDK_CALLCONV PDOCContextGetNonOCDrawing (PDOCContext ctx, bool *pDraw)
PDF_CORE_API PDErrCode PDFSDK_CALLCONV PDOCContextCommitTo (PDOCContext ctx, PDOCConfig config)
PDF_CORE_API PDErrCode PDFSDK_CALLCONV PDOCContextEnterOptionalContent (PDOCContext ctx)
PDF_CORE_API PDErrCode PDFSDK_CALLCONV PDOCContextLeaveOptionalContent (PDOCContext ctx)

Detailed Description

Optional Content API.

Typedef Documentation

◆ PDOCConfig

typedef struct PDOCConfigRec_* PDOCConfig

A PDOCConfig represents a set of states and other information from a OCProperties dictionary.

There is a document default configuration, saved in the /D entry in the OCProperties dictionary, and a list of other client configurations, saved as an array of configurations in the /Configs entry in the OCProperties dictionary.

Layers are generally displayed as Optional Content Groups.

See 8.11.4 Configuring Optional Content in PDF32000_2008.pdf

See also
PDOCConfigGetOrder
PDOCConfigSetInitialState
PDOCConfigGetInitialState

◆ PDOCContext

typedef struct PDOCContextRec_* PDOCContext

A runtime optional-content visibility context.

A PDOCContext holds the ON-OFF states of the optional content groups (OCGs) for a single rendering or enumeration pass. It is created from a PDOCConfig, is owned by the caller, and is never serialized into the PDF. Unlike a PDOCConfig (the persisted /D or /Configs entry), a context represents live state that may be freely toggled, reset, or have automatic state changes applied to it for a usage event, without affecting the document.

◆ PDOCG

typedef struct PDOCGRec_* PDOCG

Represents an optional content group (OCG) in a PDF document.

An optional content group (OCG) is a collection of content that can be displayed or hidden in a PDF document.

For more information refer to section 8.11.2 Optional content groups,

◆ PDOCMD

typedef struct PDOCMDRec_* PDOCMD

Represents an optional content membership dictionary.

An optional content membership dictionary (OCMD) is a dictionary that specifies the optional content groups (OCGs) that are to be displayed or hidden in a PDF document. It is used to control the visibility of layers in the document.

For more information refer to section 8.11.2.2 Optional content membership dictionaries

Enumeration Type Documentation

◆ PDOCDrawMode

enum PDOCDrawMode

Controls how optional content is drawn or enumerated for a context.

Together with the OCG/OCMD visibility states this selects whether content marked as optional content is drawn or enumerated.

Enumerator
kPDOCDrawVisibleOC 

Draw optional content according to the OCG/OCMD states (default).

kPDOCDrawAllOC 

Draw all optional content regardless of its visibility state.

kPDOCDrawNoOC 

Draw no optional content regardless of its visibility state.

◆ PDOCGStateOperation

enum PDOCGStateOperation

Specifies whether the targeted Optional Content Group (OCG) should be visible or hidden when the action (operation) is executed.

For more information refer to section 12.6.4.13 Set-OCG-state actions, key State, from the from the ISO 32000-2:2020 (PDF 2.0) Standard.

Enumerator
kPDOCGStateOperationOff 

Hides the specified OCGs.

kPDOCGStateOperationOn 

Makes the specified OCGs visible.

kPDOCGStateOperationToggle 

Reverses the state of the specified OCGs.

◆ PDOCUsageCategory

enum PDOCUsageCategory

A category of an optional-content group's usage (/Usage) dictionary.

ISO 32000-2:2020, 8.11.4.4 Usage and usage application dictionaries, ISO 32000-2:2020, Table 100 Entries in an optional content usage dictionary

Enumerator
kPDOCUsageCategoryCreatorInfo 

Application that created the group.

kPDOCUsageCategoryLanguage 

Language and locale of the group's content.

kPDOCUsageCategoryExport 

Recommended state when exporting.

kPDOCUsageCategoryZoom 

Magnification range for which the group is intended.

kPDOCUsageCategoryPrint 

Recommended state when printing.

kPDOCUsageCategoryView 

Recommended state for on-screen viewing.

kPDOCUsageCategoryUser 

User(s) for whom the group is intended.

kPDOCUsageCategoryPageElement 

Pagination artifact the group represents (HF, FG, BG, L).

◆ PDOCUsageEvent

enum PDOCUsageEvent

A usage event: the situation in which a document is being used — viewed on screen, printed, or exported.

ISO 32000-2:2020, 8.11.4.4 Usage and usage application dictionaries ISO 32000-2:2020, Table 101 Entries in a usage application dictionary

Enumerator
kPDOCUsageView 

Interactive on-screen viewing.

kPDOCUsagePrint 

Printing.

kPDOCUsageExport 

Export or conversion to another representation.

◆ PDOCVisibilityPolicy

enum PDOCVisibilityPolicy

The visibility policy of an optional content membership dictionary (OCMD).

Determines how the ON-OFF states of the optional content groups (OCGs) listed in an OCMD combine into a single visibility decision. Applies when the OCMD has no visibility expression (/VE); a /VE expression, when present, takes precedence over the policy.

ISO 32000-2:2020, 8.11.2.2 Optional content membership dictionaries, Table 97 (the /P entry, the /VE entry)

Enumerator
kPDOCVisibilityPolicyAnyOn 

Visible if any of the groups is ON (default).

kPDOCVisibilityPolicyAllOn 

Visible only if all of the groups are ON.

kPDOCVisibilityPolicyAnyOff 

Visible if any of the groups is OFF.

kPDOCVisibilityPolicyAllOff 

Visible only if all of the groups are OFF.

Function Documentation

◆ PDOCConfigGetOrder()

PDF_CORE_API PDErrCode PDFSDK_CALLCONV PDOCConfigGetOrder ( PDOCConfig config,
PDObject * pOrder )

Gets the user interface display order of optional-content groups (OCGs) in an optional-content configuration.

Parameters
configThe configuration for which an OCG display order is desired.
[out]pOrderA pointer to the PDOCOrderNode object containing the OCG order array.