| Layer | PD_Layer |
| Object | PDOCG |
The PDOCCG object represents an optional-content group. This corresponds to a PDF OCG dictionary representing a collection of graphic objects that can be made visible or invisible. Any graphic content of the PDF can be made optional, including page contents, XObjects, and annotations. The specific content objects in the group have an OC entry in the PDF. The group itself is a named object that you can manipulate in the Layers panel of Acrobat 6.0 and later.
In the simplest case, the group's ON-OFF state makes the associated content visible or hidden. The ON-OFF state of a group can be toggled for a particular context (PDOCContext), and a set of states is kept in a configuration (PDOCConfig). The visibility can depend on more than one group in an optional-content membership dictionary (PDOCMD), and can also be affected by the context's or configuration's PDOCDrawEnumType.
A group has an Intent entry, 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.
A Usage dictionary entry provides more specific intended usage information than an intent entry. Possible key values are:
CreatorInfoLanguageExportZoomPrintViewUserPageElementThe usage value can act as a kind of metadata, describing the sort of things that belong to the group, such as text in French, fine detail on a map, or a watermark. The usage values can also be used by the AutoState mechanism to make decisions about what groups should be on and what groups should be off. The AutoState mechanism considers the usage information in the OCGs, the AS array of the configuration, and external factors; for example, the language the application is running in, the current zoom level on the page, or whether the page is being printed.
| Typedef | ||
|---|---|---|
| PDOCG
A PDOCG represents a named object whose state can be toggled in a user interface to affect changes in visibility of content.
|
||
| Callback | ||
|---|---|---|
| PDOCGEnumProc
A callback used for enumerating optional-content groups (OCGs). Enumeration stops when all OCGs have been enumerated, or when the callback returns false.
|
||
| Method | ||
|---|---|---|
|
Creates a new optional-content group (OCG) object in the document. The order of the groups (as returned by PDDocGetOCGs()) is not guaranteed, and is not the same as the display order (see PDOCConfigGetOCGOrder()).
|
||
|
PDOCG PDOCGCreateFromCosObj(CosObj ocgObj)
Creates a new optional-content group (OCG) object from a Cos object.
|
||
|
void PDOCGDestroy(PDOCG pdocg)
Destroys an optional-content group (OCG) object. This does not delete any content, but deletes the PDOCG object, destroys the corresponding Cos object, and invalidates references from optional-content membership dictionaries (OCMDs).
|
||
|
CosObj PDOCGGetCosObj(PDOCG pdocg)
Gets the Cos object associated with the optional-content group (OCG) object.
|
||
|
Gets the current ON-OFF state of the optional-content group (OCG) object in a given context.
|
||
|
PDOCG PDOCGGetFromCosObj(CosObj obj)
Gets an optional-content group (OCG) object from the associated Cos object. If you call this multiple times for the same PDOCG, it returns the same object.
|
||
|
Gets a initial state (ON or OFF) of the optional-content group (OCG) object in a given configuration. If the configuration has a BaseState of Unchanged, and the OCG is not listed explicitly in its ON list or OFF list, then the initial state is taken from the OCG's current state in the document's default context, and the method returns false.
|
||
|
ASAtom* PDOCGGetIntent(PDOCG pdocg)
Gets the intent list for an optional-content group. An intent is an ASAtom value broadly describing the intended use, either View or Design.
|
||
|
Returns the locked state of an OCG in a given configuration. The on/off state of a locked OCG cannot be toggled by the user through the user interface.
|
||
|
ASText PDOCGGetName(PDOCG pdocg)
Gets the name of an optional-content group. The returned ASText is a copy of the OCG's name. The client is free to modify it and responsible for destroying it.
|
||
|
PDDoc PDOCGGetPDDoc(PDOCG pdocg)
Gets the document that contains an optional-content group.
|
||
|
Gets usage information from an optional-content group (OCG) object. A Usage dictionary entry provides more specific intended usage information than an intent entry. The possible key values are:
|
||
|
Tests whether the optional-content group is marked as having had its state set directly by client code in the specified context (as opposed to automatically by the optional-content AutoState mechanism).
|
||
|
ASBool PDOCGHasUsageInfo(PDOCG pdocg)
Tests whether an optional-content group (OCG) object is associated with a Usage dictionary.
|
||
|
Removes the initial ON-OFF state information for the optional-content group (OCG) object in a given configuration.
|
||
|
Sets the current ON-OFF state of the optional-content group (OCG) object in a given context.
|
||
|
Sets the initial state (ON or OFF) of the optional-content group (OCG) object in a given configuration.
|
||
|
Sets the Intent entry in an optional-content group's Cos dictionary. An intent is an ASAtom value broadly describing the intended use, which can be either View or Design.
|
||
|
Sets the locked state of an OCG in a given configuration. 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 group.
|
||
|
Sets a Usage dictionary entry in an optional-content group (OCG) object. The entry associates usage information with an entry key for retrieval. If a dictionary does not exist, the method creates one.
|
||
|
Marks the optional-content group as having had its state set directly by client code in the specified context (as opposed to automatically by the optional-content AutoState mechanism).
|
||
|
Tests whether an optional-content group (OCG) object is used in a context initialized using the given configuration.
|
||
|
Tests whether an optional-content group (OCG) object is used in a given context.
|
||
| PDOCG |
| Product availability: All |
| Platform availability: All |
typedef struct _t_PDOCG* PDOCG;
A PDOCG represents a named object whose state can be toggled in a user interface to affect changes in visibility of content.
| File: PDExpT.h |
| Line: 5524 |
| PDOCGEnumProc |
| Product availability: All |
| Platform availability: All |
A callback used for enumerating optional-content groups (OCGs). Enumeration stops when all OCGs have been enumerated, or when the callback returns false.
See Also
| File: PDExpT.h |
| Line: 5715 |
| PDOCGCreate | () |
| Product availability: All |
| Platform availability: All |
PDOCG PDOCGCreate(PDDoc pdDoc, ASConstText name)
Creates a new optional-content group (OCG) object in the document. The order of the groups (as returned by PDDocGetOCGs()) is not guaranteed, and is not the same as the display order (see PDOCConfigGetOCGOrder()).
Parameters
pdDoc — | The document in which the group is used. |
|
name — | The name of the optional-content group. |
The newly created group object. |
See Also
Since
| File: PDProcs.h |
| Line: 8676 |
| PDOCGCreateFromCosObj | () |
| Product availability: All |
| Platform availability: All |
Creates a new optional-content group (OCG) object from a Cos object.
Parameters
ocgObj — | The Cos object. |
The newly created OCG object. |
See Also
Since
| File: PDProcs.h |
| Line: 8688 |
| PDOCGDestroy | () |
| Product availability: All |
| Platform availability: All |
void PDOCGDestroy(PDOCG pdocg)
Destroys an optional-content group (OCG) object. This does not delete any content, but deletes the PDOCG object, destroys the corresponding Cos object, and invalidates references from optional-content membership dictionaries (OCMDs).
Parameters
pdocg — | The optional-content group object. |
See Also
Since
| File: PDProcs.h |
| Line: 8700 |
| PDOCGGetCosObj | () |
| Product availability: All |
| Platform availability: All |
Gets the Cos object associated with the optional-content group (OCG) object.
Parameters
pdocg — | The optional-content group object. |
The Cos object. |
See Also
Since
| File: PDProcs.h |
| Line: 8710 |
| PDOCGGetCurrentState | () |
| Product availability: All |
| Platform availability: All |
ASBool PDOCGGetCurrentState(PDOCG pdocg, PDOCContext ocContext)
Gets the current ON-OFF state of the optional-content group (OCG) object in a given context.
Parameters
pdocg — | The optional-content group object. |
|
ocContext — | The context for which to get the group's state. |
|
See Also
Since
| File: PDProcs.h |
| Line: 8964 |
| PDOCGGetFromCosObj | () |
| Product availability: All |
| Platform availability: All |
Gets an optional-content group (OCG) object from the associated Cos object. If you call this multiple times for the same PDOCG, it returns the same object.
Parameters
obj — | The Cos object. |
The OCG object. |
See Also
Since
| File: PDProcs.h |
| Line: 8724 |
| PDOCGGetInitialState | () |
| Product availability: All |
| Platform availability: All |
ASBool PDOCGGetInitialState(PDOCG pdocg, PDOCConfig pdOCCfg, ASBool* initState)
Gets a initial state (ON or OFF) of the optional-content group (OCG) object in a given configuration. If the configuration has a BaseState of Unchanged, and the OCG is not listed explicitly in its ON list or OFF list, then the initial state is taken from the OCG's current state in the document's default context, and the method returns false.
Parameters
pdocg — | The optional-content group object. |
|
pdOCCfg — | The configuration for which to get the group's initial state. |
|
initState — | (Filled by the method) The initial state, |
|
See Also
Since
| File: PDProcs.h |
| Line: 8799 |
| PDOCGGetIntent | () |
| Product availability: All |
| Platform availability: All |
Gets the intent list for an optional-content group. 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.
Parameters
pdocg — | The optional-content group object for which the intent is desired. |
An array containing intent entries (ASAtom objects) terminated by ASAtomNull. The client is responsible for freeing it using ASfree(). |
See Also
Since
| File: PDProcs.h |
| Line: 8948 |
| PDOCGGetLocked | () |
| Product availability: All |
| Platform availability: All |
ASBool PDOCGGetLocked(PDOCG ocg, PDOCConfig pdOCCfg)
Returns the locked state of an OCG in a given configuration. The on/off state of a locked OCG cannot be toggled by the user through the user interface.
Parameters
ocg — | ||
pdOCCfg — | IN The optional-content configuration. |
An ASBool that is |
See Also
Since
| File: PDProcs.h |
| Line: 11016 |
| PDOCGGetName | () |
| Product availability: All |
| Platform availability: All |
Gets the name of an optional-content group. The returned ASText is a copy of the OCG's name. The client is free to modify it and responsible for destroying it.
Parameters
pdocg — | The optional-content group object for which the name is desired. |
The name string. |
See Also
Since
| File: PDProcs.h |
| Line: 8757 |
| PDOCGGetPDDoc | () |
| Product availability: All |
| Platform availability: All |
Gets the document that contains an optional-content group.
Parameters
pdocg — | The optional-content group object for which the document is desired. |
The document object. |
See Also
Since
| File: PDProcs.h |
| Line: 8736 |
| PDOCGGetUsageEntry | () |
| Product availability: All |
| Platform availability: All |
Gets usage information from an optional-content group (OCG) object. A Usage dictionary entry provides more specific intended usage information than an intent entry. The possible key values are:
CreatorInfo
Language
Export
Zoom
Print
View
User
PageElement
Parameters
pdocg — | The optional-content group object. |
|
entry — | The usage key in the usage dictionary entry. |
The usage information associated with the given key in the Usage dictionary for the group, or a |
See Also
Since
| File: PDProcs.h |
| Line: 8899 |
| PDOCGGetUserOverride | () |
| Product availability: All |
| Platform availability: All |
ASBool PDOCGGetUserOverride(PDOCG ocg, PDOCContext ctx)
Tests whether the optional-content group is marked as having had its state set directly by client code in the specified context (as opposed to automatically by the optional-content AutoState mechanism).
When a group is so marked, automatic state changes caused by the View event are prevented. When a group's automatic state change is caused by the Export or Print event, the user-override setting for the group is ignored.
A configuration's AS array defines how usage entries are used to automatically manipulate the OCG states. It associates an event (View, Print, or Export) with a list of OCGs and a category, or list of usage keys identifying OCG usage dictionary entries. See the PDF Reference, and the OCTextAutoStateSnip example in the Snippet Runner.
Parameters
ocg — | The optional-content group object. |
|
ctx — | The context for which the group is tested. |
|
See Also
Since
| File: PDProcs.h |
| Line: 10299 |
| PDOCGHasUsageInfo | () |
| Product availability: All |
| Platform availability: All |
Tests whether an optional-content group (OCG) object is associated with a Usage dictionary.
Parameters
pdocg — | The optional-content group object. |
|
See Also
Since
| File: PDProcs.h |
| Line: 8869 |
| PDOCGRemoveInitialState | () |
| Product availability: All |
| Platform availability: All |
void PDOCGRemoveInitialState(PDOCG pdocg, PDOCConfig pdOCCfg)
Removes the initial ON-OFF state information for the optional-content group (OCG) object in a given configuration.
Parameters
pdocg — | The optional-content group object. |
|
pdOCCfg — | The configuration for which to remove the group's initial state. |
See Also
Since
| File: PDProcs.h |
| Line: 8816 |
| PDOCGSetCurrentState | () |
| Product availability: All |
| Platform availability: All |
void PDOCGSetCurrentState(PDOCG pdocg, PDOCContext ocContext, ASBool newState)
Sets the current ON-OFF state of the optional-content group (OCG) object in a given context.
Parameters
pdocg — | The optional-content group object. |
|
ocContext — | The context for which to set the group's state. |
|
newState — | The new state. |
See Also
Since
| File: PDProcs.h |
| Line: 8982 |
| PDOCGSetInitialState | () |
| Product availability: All |
| Platform availability: All |
void PDOCGSetInitialState(PDOCG pdocg, PDOCConfig pdOCCfg, ASBool onOff)
Sets the initial state (ON or OFF) of the optional-content group (OCG) object in a given configuration.
Parameters
pdocg — | The optional-content group object. |
|
pdOCCfg — | The configuration for which to set the group's initial state. |
|
onOff — | The new initial state, |
See Also
Since
| File: PDProcs.h |
| Line: 8775 |
| PDOCGSetIntent | () |
| Product availability: All |
| Platform availability: All |
Sets the Intent entry in an optional-content group's Cos dictionary. An intent is an ASAtom value broadly describing the intended use, which can be 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.
Parameters
pdocg — | The optional-content group object for which the intent is desired. |
|
intent — | The new Intent entry value, an array of atoms terminated with ASAtomNull. |
See Also
Since
| File: PDProcs.h |
| Line: 8923 |
| PDOCGSetLocked | () |
| Product availability: All |
| Platform availability: All |
void PDOCGSetLocked(PDOCG ocg, PDOCConfig pdOCCfg, ASBool locked)
Sets the locked state of an OCG in a given configuration. The on/off state of a locked OCG cannot be toggled by the user through the user interface.
Parameters
ocg — | ||
pdOCCfg — | IN/OUT The optional-content configuration. |
|
locked — | IN An ASBool that is |
See Also
Since
| File: PDProcs.h |
| Line: 11031 |
| PDOCGSetName | () |
| Product availability: All |
| Platform availability: All |
void PDOCGSetName(PDOCG pdocg, ASConstText name)
Sets the name of an optional-content group.
Parameters
pdocg — | The optional-content group object. |
|
name — | The new name string. |
See Also
Since
| File: PDProcs.h |
| Line: 8745 |
| PDOCGSetUsageDictEntry | () |
| Product availability: All |
| Platform availability: All |
Sets a Usage dictionary entry in an optional-content group (OCG) object. The entry associates usage information with an entry key for retrieval. If a dictionary does not exist, the method creates one.
A Usage dictionary entry provides more specific intended usage information than an intent entry. The possible key values are:
CreatorInfo
Language
Export
Zoom
Print
View
User
PageElement
The usage value can act as a kind of metadata, describing the sort of things that belong to the group, such as text in French, fine detail on a map, or a watermark. The usage values can also be used by the AutoState mechanism to make decisions about what groups should be on and what groups should be off. The AutoState mechanism considers the usage information in the OCGs, the AS array of the configuration, and external factors; for example, the language the application is running in, the current zoom level on the page, or if the page is being printed.
Parameters
pdocg — | The optional-content group object. |
|
usagekey — | The usage entry key. |
|
usageinfo — | The usage information to associate with the key. |
See Also
Since
| File: PDProcs.h |
| Line: 8857 |
| PDOCGSetUserOverride | () |
| Product availability: All |
| Platform availability: All |
void PDOCGSetUserOverride(PDOCG ocg, PDOCContext ctx, ASBool overridden)
Marks the optional-content group as having had its state set directly by client code in the specified context (as opposed to automatically by the optional-content AutoState mechanism).
When a group is so marked, automatic state changes caused by the View event are prevented. When a group's automatic state change is caused by the Export or Print event, the user-override setting for the group is ignored.
A configuration's AS array defines how usage entries are used to automatically manipulate the OCG states. It associates an event (View, Print, or Export) with a list of OCGs and a category, or list of usage keys identifying OCG usage dictionary entries. See the PDF Reference, and the OCTextAutoStateSnip example in the Snippet Runner.
Parameters
ocg — | The optional-content group object. |
|
ctx — | The context for which the group is marked. |
|
overridden — |
|
See Also
Since
| File: PDProcs.h |
| Line: 10268 |
| PDOCGUsedInOCConfig | () |
| Product availability: All |
| Platform availability: All |
ASBool PDOCGUsedInOCConfig(PDOCG pdocg, PDOCConfig pdoccfg)
Tests whether an optional-content group (OCG) object is used in a context initialized using the given configuration.
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.
Parameters
pdocg — | The optional-content group object. |
|
pdoccfg — | The optional-content configuration. |
|
See Also
Since
| File: PDProcs.h |
| Line: 9028 |
| PDOCGUsedInOCContext | () |
| Product availability: All |
| Platform availability: All |
ASBool PDOCGUsedInOCContext(PDOCG pdocg, PDOCContext pdocctx)
Tests whether an optional-content group (OCG) object is used in a given context.
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.
Parameters
pdocg — | The optional-content group object. |
|
pdocctx — | The optional-content context. |
|
See Also
Since
| File: PDProcs.h |
| Line: 9005 |