LayerPD_Layer
ObjectPDOCConfig

The PDOCConfig object represents an optional-content configuration structure, used to maintain a set of visibility states and other optional-content information in a PDF file for future use. A document has a default configuration, saved in the D entry in the OCProperties dictionary, and can have a list of other configurations, saved as an array in the Configs entry in the OCProperties dictionary.

Configurations are typically used to initialize the optional-content group (PDOCG) ON-OFF states for an optional-content context (PDOCContext). The OCG order in the configuration is the order in which the groups appear in the Layers panel of Acrobat 6.0 and later. The configuration can define a set of mutually exclusive OCGs, called a radio button group.



Typedef Summary
 Typedef
 PDOCConfig
A PDOCConfig represents a set of states and other information that is saved in a PDF file for future use. 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. PDOCConfig objects are typically used to initialize the OCG states for a client's PDOCContext.
Enumeration Summary
 Enumeration
  PDOCConfigBaseState
PDOCBaseState enumerates the three legal values for the BaseState key in an optional content configuration dictionary (PDOCConfig). When initializing a PDOCContext using KOCCInit_FromConfig(), this enumeration represents the starting state of the Optional Content Groups (OCGs) before the contents of the config's ON and OFF OCG lists are processed. If the BaseState is Unchanged, and the PDOCConfig is just being constructed, the current states of the OCGs from the PDDoc's own PDOCConfig are used.
Callback Summary
 Callback
 PDOCConfigEnumProc
A callback used for enumerating optional-content configurations. Enumeration stops when all configurations have been enumerated, or when the callback returns false.
Method Summary
 Method
 
PDOCConfig PDOCConfigCreate(PDDoc pdDoc)
Creates a new optional-content configuration object.
 
Removes an optional-content configuration object and destroys the Cos objects associated with it. If you pass this method the document's default configuration object (as returned by PDDocGetOCConfig()), nothing happens.
 
Returns an array of pointers to sets of optional-content groups in the configuration that are configured to be mutually exclusive. A set behaves like a radio button group, where only one member can be ON at one time.
 
Gets the Cos object associated with the optional-content configuration.
 
Gets the creator property for an optional-content configuration.
 
void PDOCConfigGetInitState(PDOCConfig pdOCCfg, PDOCConfigBaseState* bs, PDOCG** onOCGs, PDOCG** offOCGs)
Gets the initial ON-OFF states of optional-content groups in an optional-content configuration.
 
Gets the Intent entry for an optional-content configuration. An intent is an ASAtom value broadly describing the intended use, either View or Design. A group's content is considered to be optional (that is, the group's state is considered in its visibility) if any intent in its list matches an intent of the context. The intent list of the context is usually set from the intent list of the document configuration.
 
Returns a PDOCConfig object's list of locked OCGs. The on/off state of a locked OCG cannot be toggled by the user through the user interface.
 
Gets the name of an optional-content configuration.
 
ASBool PDOCConfigGetOCGOrder(PDOCConfig pdOCCfg, CosObj* orderObj)
Gets the user interface display order of optional-content groups (OCGs) in an optional-content configuration. This is the order in which the group names are displayed in the Layers panel of Acrobat 6.0 and later.
 
Gets the document to which the optional-content configuration belongs.
 
Returns an array of optional-content groups in the configuration that contains the specified group, and is configured to behave like a radio button group, where only one member of the set can be ON at one time.
 
Configures a mutually exclusive set of optional-content groups in an optional-content configuration. The set behaves like a radio button group, where only one OCG from the set can be ON at a time. A client must enforce this in the user interface-level code, not the PD-level code.
 
Sets the creator property of an optional-content configuration. Stores the specified string as the Creator entry in the configuration's Cos dictionary.
 
void PDOCConfigSetInitState(PDOCConfig pdOCCfg, PDOCConfigBaseState bs, PDOCG* onOCGs, PDOCG* offOCGs)
Sets the initial ON-OFF states of optional-content groups to be saved in an optional-content configuration.
 
void PDOCConfigSetIntent(PDOCConfig pdOCCfg, ASAtom* intent)
Sets the Intent entry in an optional-content configuration's Cos dictionary. An intent is an ASAtom value broadly describing the intended use, either View or Design.
 
void PDOCConfigSetLockedArray(PDOCConfig pdOCCfg, PDOCG* lockedOCGs)
Sets a PDOCConfig's list of locked OCGs. The on/off state of a locked OCG cannot be toggled by the user through the user interface.
 
Sets the name of an optional-content configuration. It stores the specified string as the Name entry in the configuration's Cos dictionary.
 
void PDOCConfigSetOCGOrder(PDOCConfig pdOCCfg, CosObj orderArray)
Sets the user interface display order of optional-content groups (OCGs) in an optional-content configuration. This is the order in which the group names are displayed in the Layers panel of Acrobat 6.0 and later.

Typedefs Detail
PDOCConfig 
Product availability: All
Platform availability: All

Syntax

typedef struct _t_PDOCConfig* PDOCConfig;

A PDOCConfig represents a set of states and other information that is saved in a PDF file for future use. 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. PDOCConfig objects are typically used to initialize the OCG states for a client's PDOCContext.


File: PDExpT.h
Line: 5551

Enumeration Detail
PDOCConfigBaseState
Product availability: All
Platform availability: All

Syntax

enum PDOCConfigBaseState {
 kPDOCBaseState_OFF,
 
 kPDOCBaseState_ON,
 
 kPDOCBaseState_Unchanged
}

File: PDExpT.h
Line: 5591


Callbacks Detail
PDOCConfigEnumProc 
Product availability: All
Platform availability: All

Syntax

ASBool (*PDOCConfigEnumProc)(PDOCConfig occonfig, void *clientData)

A callback used for enumerating optional-content configurations. Enumeration stops when all configurations have been enumerated, or when the callback returns false.

See Also


File: PDExpT.h
Line: 5728

Method Detail
PDOCConfigCreate()
Product availability: All
Platform availability: All

Syntax

PDOCConfig PDOCConfigCreate(PDDoc pdDoc)

Creates a new optional-content configuration object.

Parameters

pdDoc — 

The document in which the configuration is used.

Returns

The newly created configuration object.

See Also

Since

PI_PDMODEL_VERSION >= 0x00060000

File: PDProcs.h
Line: 9870
PDOCConfigDestroy() 
Product availability: All
Platform availability: All

Syntax

void PDOCConfigDestroy(PDOCConfig pdOCCfg)

Removes an optional-content configuration object and destroys the Cos objects associated with it. If you pass this method the document's default configuration object (as returned by PDDocGetOCConfig()), nothing happens.

Parameters

pdOCCfg — 

The configuration to destroy.

See Also

Since

PI_PDMODEL_VERSION >= 0x00060000

File: PDProcs.h
Line: 9881
PDOCConfigGetAllRadioButtonGroups() 
Product availability: All
Platform availability: All

Syntax

PDOCG PDOCConfigGetAllRadioButtonGroups(PDOCConfig pdOCCfg)

Returns an array of pointers to sets of optional-content groups in the configuration that are configured to be mutually exclusive. A set behaves like a radio button group, where only one member can be ON at one time.

Parameters

pdOCCfg — 

The configuration.

Returns

A NULL-terminated array of pointers to NULL-terminated arrays of optional-content groups (OCGs). The client is responsible for freeing all arrays using ASfree().

See Also

Since

PI_PDMODEL_VERSION >= 0x00060000

File: PDProcs.h
Line: 9997
PDOCConfigGetCosObj() 
Product availability: All
Platform availability: All

Syntax

CosObj PDOCConfigGetCosObj(PDOCConfig pdOCCfg)

Gets the Cos object associated with the optional-content configuration.

Parameters

pdOCCfg — 

The configuration for which a CosObj representation is desired.

Returns

A CosObj representation of pdOCCfg.

Since

PI_PDMODEL_VERSION >= 0x00060000

File: PDProcs.h
Line: 9916
PDOCConfigGetCreator() 
Product availability: All
Platform availability: All

Syntax

ASText PDOCConfigGetCreator(PDOCConfig pdOCCfg)

Gets the creator property for an optional-content configuration.

Parameters

pdOCCfg — 

The configuration for which a creator is desired.

Returns

An ASText object containing the creator string from the Creator entry in the configuration's Cos dictionary, or NULL if there is no such entry. The client is responsible for freeing the ASText using ASTextDestroy().

See Also

Since

PI_PDMODEL_VERSION >= 0x00060000

File: PDProcs.h
Line: 10093
PDOCConfigGetInitState() 
Product availability: All
Platform availability: All

Syntax

void PDOCConfigGetInitState(PDOCConfig pdOCCfg, PDOCConfigBaseState* bs, PDOCG** onOCGs, PDOCG** offOCGs)

Gets the initial ON-OFF states of optional-content groups in an optional-content configuration.

The client is responsible for freeing storage for the arrays using ASfree().

Parameters

pdOCCfg — 

The configuration for which the initial state is desired.

 
bs — 

(Filled by the method) An existing PDOCConfigBaseState structure in which to store the initialization information.

 
onOCGs — 

(Filled by the method) A NULL-terminated array of OCGs that have an initial state of ON, or NULL if there are no such groups.

 
offOCGs — 

(Filled by the method) A NULL-terminated array of OCGs that have an initial state of OFF, or NULL if there are no such groups.

See Also

Since

PI_PDMODEL_VERSION >= 0x00060000

File: PDProcs.h
Line: 10039
PDOCConfigGetIntent() 
Product availability: All
Platform availability: All

Syntax

ASAtom PDOCConfigGetIntent(PDOCConfig pdOCCfg)

Gets the Intent entry for an optional-content configuration. An intent is an ASAtom value broadly describing the intended use, either View or Design. A group's content is considered to be optional (that is, the group's state is considered in its visibility) if any intent in its list matches an intent of the context. The intent list of the context is usually set from the intent list of the document configuration.

The intent array contains entries (atoms) terminated by ASAtomNull.

If the configuration has no Intent entry, the default value of View is used. In this case, optional content is disabled for contexts initialized with this configuration.

Parameters

pdOCCfg — 

The configuration for which an intent list is desired.

Returns

The ASAtomNull-terminated intent array. The client is responsible for freeing it using ASfree().

See Also

Since

PI_PDMODEL_VERSION >= 0x00060000

File: PDProcs.h
Line: 10151
PDOCConfigGetLockedArray() 
Product availability: All
Platform availability: All

Syntax

PDOCG PDOCConfigGetLockedArray(PDOCConfig pdOCCfg)

Returns a PDOCConfig object's list of locked OCGs. The on/off state of a locked OCG cannot be toggled by the user through the user interface.

Parameters

pdOCCfg — 

The optional-content configuration.

Returns

A NULL-terminated array of PDOCG objects, or NULL if the specified configuration does not contain a list of locked OCGs. The client is responsible for freeing the array using ASfree().

See Also

Since

PI_PDMODEL_VERSION >= 0x00070000

File: PDProcs.h
Line: 11046
PDOCConfigGetName() 
Product availability: All
Platform availability: All

Syntax

ASText PDOCConfigGetName(PDOCConfig pdOCCfg)

Gets the name of an optional-content configuration.

Parameters

pdOCCfg — 

The configuration for which a name is desired.

Returns

An ASText object containing the name string from Name entry of the configuration's Cos dictionary, or NULL if there is no Name entry. The client is responsible for freeing the ASText object using ASTextDestroy().

See Also

Since

PI_PDMODEL_VERSION >= 0x00060000

File: PDProcs.h
Line: 10065
PDOCConfigGetOCGOrder() 
Product availability: All
Platform availability: All

Syntax

ASBool PDOCConfigGetOCGOrder(PDOCConfig pdOCCfg, CosObj* orderObj)

Gets the user interface display order of optional-content groups (OCGs) in an optional-content configuration. This is the order in which the group names are displayed in the Layers panel of Acrobat 6.0 and later.

Parameters

pdOCCfg — 

The configuration for which an OCG display order is desired.

 
orderObj — 

(Filled by the method) A pointer to the Cos object containing the OCG order array. For more information, see the PDF Reference.

Returns

true if the order belongs directly to this configuration, false if it is inherited from the document's default configuration.

See Also

Since

PI_PDMODEL_VERSION >= 0x00060000

File: PDProcs.h
Line: 9949
PDOCConfigGetPDDoc() 
Product availability: All
Platform availability: All

Syntax

PDDoc PDOCConfigGetPDDoc(PDOCConfig pdOCCfg)

Gets the document to which the optional-content configuration belongs.

Parameters

pdOCCfg — 

The configuration for which a document is desired.

Returns

The document object.

See Also

Since

PI_PDMODEL_VERSION >= 0x00060000

File: PDProcs.h
Line: 9906
PDOCConfigGetRadioButtonGroupForOCG() 
Product availability: All
Platform availability: All

Syntax

PDOCG PDOCConfigGetRadioButtonGroupForOCG(PDOCConfig pdOCCfg, PDOCG ocg)

Returns an array of optional-content groups in the configuration that contains the specified group, and is configured to behave like a radio button group, where only one member of the set can be ON at one time.

Parameters

pdOCCfg — 

The optional-content configuration.

 
ocg — 

The optional-content group for which to obtain the radio-button group.

Returns

A NULL-terminated array of PDOCG objects, or NULL if the specified group does not belong to any radio button group. The client is responsible for freeing the array using ASfree().

See Also

Since

PI_PDMODEL_VERSION >= 0x00060000

File: PDProcs.h
Line: 9982
PDOCConfigMakeRadioButtonGroup() 
Product availability: All
Platform availability: All

Syntax

void PDOCConfigMakeRadioButtonGroup(PDOCConfig pdOCCfg, PDOCG* ocgs)

Configures a mutually exclusive set of optional-content groups in an optional-content configuration. The set behaves like a radio button group, where only one OCG from the set can be ON at a time. A client must enforce this in the user interface-level code, not the PD-level code.

Parameters

pdOCCfg — 

The optional-content configuration.

 
ocgs — 

A NULL-terminated array of optional-content groups to be included in the group.

See Also

Since

PI_PDMODEL_VERSION >= 0x00060000

File: PDProcs.h
Line: 9964
PDOCConfigSetCreator() 
Product availability: All
Platform availability: All

Syntax

void PDOCConfigSetCreator(PDOCConfig pdOCCfg, ASConstText creator)

Sets the creator property of an optional-content configuration. Stores the specified string as the Creator entry in the configuration's Cos dictionary.

Parameters

pdOCCfg — 

The configuration for which to set a creator.

 
creator — 

The new creator string.

See Also

Since

PI_PDMODEL_VERSION >= 0x00060000

File: PDProcs.h
Line: 10078
PDOCConfigSetInitState() 
Product availability: All
Platform availability: All

Syntax

void PDOCConfigSetInitState(PDOCConfig pdOCCfg, PDOCConfigBaseState bs, PDOCG* onOCGs, PDOCG* offOCGs)

Sets the initial ON-OFF states of optional-content groups to be saved in an optional-content configuration.

Parameters

pdOCCfg — 

The configuration for which to set the initial state.

 
bs — 

An existing PDOCConfigBaseState structure containing the initialization information.

 
onOCGs — 

A NULL-terminated array of optional-content groups (OCGs) that have an initial state of ON when that is not the base state, or NULL.

 
offOCGs — 

A NULL-terminated array of OCGs that have an initial state of OFF when that is not the base state, or NULL.

See Also

Since

PI_PDMODEL_VERSION >= 0x00060000

File: PDProcs.h
Line: 10016
PDOCConfigSetIntent() 
Product availability: All
Platform availability: All

Syntax

void PDOCConfigSetIntent(PDOCConfig pdOCCfg, ASAtom* intent)

Sets the Intent entry in an optional-content configuration's Cos dictionary. An intent is an ASAtom value broadly describing the intended use, either View or Design.

A group's content is considered to be optional (that is, the group's state is considered in its visibility) if any intent in its list matches an intent of the context. The intent list of the context is usually set from the intent list of the document configuration.

If the configuration has no Intent entry, the default value of View is used. In this case, optional content is disabled for contexts initialized with this configuration.

Parameters

pdOCCfg — 

The configuration for which to set an intent.

 
intent — 

The new Intent entry value, an array of atoms terminated with ASAtomNull. To remove the Intent entry, pass an array with only one element, ASAtomNULL.

See Also

Since

PI_PDMODEL_VERSION >= 0x00060000

File: PDProcs.h
Line: 10122
PDOCConfigSetLockedArray() 
Product availability: All
Platform availability: All

Syntax

void PDOCConfigSetLockedArray(PDOCConfig pdOCCfg, PDOCG* lockedOCGs)

Sets a PDOCConfig's list of locked OCGs. The on/off state of a locked OCG cannot be toggled by the user through the user interface.

Parameters

pdOCCfg — 

The optional-content configuration.

 
lockedOCGs — 

A NULL-terminated array of PDOCG objects to be used as the locked OCGs for the specified configuration, or NULL if the configuration should not contain a list of locked OCGs.

See Also

Since

PI_PDMODEL_VERSION >= 0x00070000

File: PDProcs.h
Line: 11061
PDOCConfigSetName() 
Product availability: All
Platform availability: All

Syntax

void PDOCConfigSetName(PDOCConfig pdOCCfg, ASConstText name)

Sets the name of an optional-content configuration. It stores the specified string as the Name entry in the configuration's Cos dictionary.

Parameters

pdOCCfg — 

The configuration for which to set the name.

 
name — 

The new name string.

See Also

Since

PI_PDMODEL_VERSION >= 0x00060000

File: PDProcs.h
Line: 10052
PDOCConfigSetOCGOrder() 
Product availability: All
Platform availability: All

Syntax

void PDOCConfigSetOCGOrder(PDOCConfig pdOCCfg, CosObj orderArray)

Sets the user interface display order of optional-content groups (OCGs) in an optional-content configuration. This is the order in which the group names are displayed in the Layers panel of Acrobat 6.0 and later.

Parameters

pdOCCfg — 

The configuration for which a OCG is desired.

 
orderArray — 

The Cos object containing the OCG order array. For more information, see the PDF Reference. Pass NULL to remove any existing order entry.

See Also

Since

PI_PDMODEL_VERSION >= 0x00060000

File: PDProcs.h
Line: 9931