PD_Layer.PDOCConfig (Acrobat)

	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
	`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
	PDOCConfigEnumProc A callback used for enumerating optional-content configurations. Enumeration stops when all configurations have been enumerated, or when the callback returns false.

	Method
	PDOCConfig PDOCConfigCreate(PDDoc pdDoc) Creates a new optional-content configuration object.
	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.
	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.
	CosObj PDOCConfigGetCosObj(PDOCConfig pdOCCfg) Gets the Cos object associated with the optional-content configuration.
	ASText PDOCConfigGetCreator(PDOCConfig pdOCCfg) 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.
	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.
	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.
	ASText PDOCConfigGetName(PDOCConfig pdOCCfg) 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.
	PDDoc PDOCConfigGetPDDoc(PDOCConfig pdOCCfg) Gets the document to which the optional-content configuration belongs.
	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.
	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.
	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.
	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.
	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.
	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

PDDocEnumOCConfigs

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

PDOCConfigDestroy

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

PDOCConfigCreate

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().

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

PDOCConfigSetCreator
PDOCConfigGetName

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.

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().

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().

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

PDOCConfigSetName
PDOCConfigGetCreator

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

PDOCConfigSetOCGOrder

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

PDDocGetOCConfig

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().

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.

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

PDOCConfigGetCreator
PDOCConfigSetName

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`.

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, ASAtom`NULL`.

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.

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

PDOCConfigGetName
PDOCConfigSetCreator

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

PDOCConfigGetOCGOrder

Since

PI_PDMODEL_VERSION >= 0x00060000

File: PDProcs.h

Line: 9931

Acrobat API Reference	All Layers \| All Objects \| Index \| Samples \| Frames No Frames
PDOCConfig	Typedefs \| Enumerations \| Callbacks \| Methods

	kPDOCBaseState_OFF,

	kPDOCBaseState_ON,

	kPDOCBaseState_Unchanged

Layer	PD_Layer
Object	PDOCConfig