Value options for PDOCContextChangeType.
kPDOCGState | The OCGs' states are changing.
|
kPDOCContextDrawEnumType | The PDOCContext object's PDDrawEnumType is changing.
|
kPDOCContextNonOCDrawing | The PDOCContext object's non-optional content drawing is changing.
|
kPDOCContextIntent | The PDOCContext object's intent is changing.
|
kPDOCContextInit | The PDOCContext is being reset using PDOCContextInit().
|
kPDOC_LastContextChangeType=kPDOCContextInit |
kOCCInit_OFF | |
kOCCInit_ON | |
kOCCInit_FromOtherContext | |
kOCCInit_FromConfig |
NonOCDrawing value, controls drawing or enumerating content on a page with optional content:NonOCDrawing is true, and not drawn when NonOCDrawing is false.kPDOC_VisibleOC=0 | Draw or enumerate optional content that is visible, according to the current state of Optional Content Groups (OCGs) and Optional Content Membership Dictionaries (OCMDs). This is the normal default mode.
|
kPDOC_AllOC | Draw or enumerate all optional content, regardless of its visibility state. If the context's
NonOCDrawing is true, all contents of document are shown. |
kPDOC_NoOC | Draw or enumerate no optional content, regardless of its visibility state. If the context's
NonOCDrawing is false, nothing is drawn, resulting in a blank page. |
kPDOC_LastDrawEnumType=kPDOC_NoOC |
typedef struct _t_PDOCContext *PDOCContext; For value options see PDOCContextChangeTypes.
typedef ASUns8 PDOCContextChangeType; For value options see PDOCContextInitPolicies.
typedef ASUns8 PDOCContextInitPolicy; NonOCDrawing value, controls drawing or enumerating content on a page with optional content:NonOCDrawing is true, and not drawn when NonOCDrawing is false.typedef ASUns8 PDOCDrawEnumType; Calls PDOCContextFindAutoStateChanges() to find optional-content groups whose ON-OFF states should be toggled, based on usage application directives contained in the configuration's AS array, and applies the changes within the given context.
The 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 description of the Optional Content Groups (OCG) in the ISO 32000-1:2008, Document Management-Portable Document Format-Part 1: PDF 1.7, section 8.11.2, page 222.
You can find this document on the web store of the International Standards Organization (ISO).
ASBool PDOCContextApplyAutoStateChanges(PDOCContext ctx, PDOCConfig cfg, ASAtom event); ctx | The context for which the visibility state is changed.
|
cfg | The configuration whose usage directives are used.
|
event | The event for which an
ON-OFF state is automatically changed. Events are View, Export, and Print. |
Removes usage override marks in all optional-content groups in the given context.
When an optional-content group is marked as having had its state set explicitly in a specified context, 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 description of the Optional Content Groups (OCG) in the ISO 32000-1:2008, Document Management-Portable Document Format-Part 1: PDF 1.7, section 8.11.2, page 222.
You can find this document on the web store of the International Standards Organization (ISO).
void PDOCContextClearAllUserOverrides(PDOCContext ctx); ctx | The context for which the user override marks are removed.
|
Tests whether content is visible in the optional-content context. The method considers the context's current OCMD stack, the group ON-OFF states, the non-OC drawing status, the drawing and enumeration type, and the intent.
Use this method in conjunction with the OCMD stack methods.
ASBool PDOCContextContentIsVisible(PDOCContext ocContext); ocContext | The context for which the visibility state is desired.
|
Finds optional-content groups whose ON-OFF states should be toggled in the context, based on usage application directives contained in the configuration's AS array.
The 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.
PDOCG *PDOCContextFindAutoStateChanges(PDOCContext ctx, PDOCConfig cfg, ASAtom event); ctx | The context for which the visibility state should be changed.
|
cfg | The configuration whose usage directives are used.
|
event | The event for which an
ON-OFF state is automatically changed. Events are View, Export, and Print. |
void PDOCContextFree(PDOCContext ocContext); ocContext | The context object to free.
|
Gets the intent list for an optional-content context. 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.
ASAtom *PDOCContextGetIntent(PDOCContext ocContext); ocContext | The context for which an intent is desired.
|
Gets the non-OC drawing status for an optional-content context. Content that is not marked as optional content is drawn when NonOCDrawing is true, and not drawn when NonOCDrawing is false.
Together, this value and the PDOCDrawEnumType value of the context determine how both optional and non-optional content on a page is drawn or enumerated. See PDOCDrawEnumType().
ASBool PDOCContextGetNonOCDrawing(PDOCContext ocContext); ocContext | The context for which the non-OC drawing status is desired.
|
Gets the drawing and enumeration type for an optional-content context. This type, together with the visibility determined by the OCG and Optional Content Membership Dictionary (OCMD) states, controls whether content that is marked as optional content is drawn or enumerated.
Together, this value and the NonOCDrawing value of the context determine how both optional and non-optional content on a page is drawn or enumerated. See PDOCDrawEnumType().
PDOCDrawEnumType PDOCContextGetOCDrawEnumType(PDOCContext ocContext); ocContext | The context for which the drawing and enumeration type is desired.
|
ON-OFF states for the given optional-content groups (OCGs) in the given optional-content context. It returns the states in the states array, which must be large enough to hold as many ASBool values as there are OCGs. void PDOCContextGetOCGStates(PDOCContext ocContext, PDOCG *pdocgs, ASBool *states); ocContext | The context for which the OCG states are desired.
|
pdocgs | A
NULL-terminated array of optional-content groups whose states are obtained. |
states |
PDDoc PDOCContextGetPDDoc(PDOCContext ocContext); ocContext | The context for which a document is desired.
|
ON-OFF states of all optional-content groups (OCGs) within an existing context. void PDOCContextInit(PDOCContext ocContext, PDOCContextInitPolicy policy, PDOCContext otherCtx, PDOCConfig pdOCCfg); ocContext | The context to initialize.
|
policy | The initialization policy for the context. This value determines whether optional-content groups are initially
ON or OFF. |
otherCtx | Another context from which to take initial OCG states when the policy is kOCCInit_FromOtherContext. It is ignored for other policies.
|
pdOCCfg | A configuration from which to take initial OCG states when the policy is kOCCInit_FromConfig. It is ignored for other policies.
|
Creates a new context object to represent an optional-content state of the document, using an existing context as a template.
This is the same as the following call:
PDOCCOntextNew(kOCCInit_FromOtherContext, ocContext, NULL, PDOCContextGetPDDoc(ocContext));
PDOCContext PDOCContextMakeCopy(PDOCContext ocContext); ocContext | The context to copy.
|
Creates a new context object that represents an optional-content state of the document, using an existing context as a template, but applying an automatic state change for the specified event. An automatic state change toggles all groups' ON-OFF states when the triggering event occurs.
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.
PDOCContext PDOCContextMakeCopyWithAutoStateChanges(PDOCContext inCtx, PDOCConfig cfg, ASAtom event); inCtx | The context to copy.
|
cfg | The configuration in which the automatic state change applies.
|
event | The event for which state will automatically change. Events are
View, Export, and Print. |
PDOCContext PDOCContextNew(PDOCContextInitPolicy policy, PDOCContext otherCtx, PDOCConfig pdOCCfg, PDDoc pdDoc); policy | The initialization policy for the new context. This value determines whether optional-content groups (OCGs) are initially
ON or OFF. |
otherCtx | Another context from which to take initial OCG states when the policy is kOCCInit_FromOtherContext. It is ignored for other policies.
|
pdOCCfg | A configuration from which to take initial OCG states when the policy is kOCCInit_FromConfig. It is ignored for other policies.
|
pdDoc | The document for which to create a context.
|
PDDocGetOCConfig(pdDoc)). PDOCContext PDOCContextNewWithInitialState(PDDoc pdDoc); pdDoc | The document for which to create a context.
|
Creates a context object that represents an optional-content state of the document, with the PDOCDrawEnumType property set to kPDOC_NoOC, so that no content marked as optional content is drawn, regardless of the visibility according to the OCGs and OCMDs.
Content that is not marked as optional content may still be drawn, depending on the NonOCDrawing property.
PDOCContext PDOCContextNewWithOCDisabled(PDDoc pdDoc); pdDoc | The document for which to create a context.
|
To track nested content that is not for optional content, pass in NULL for pdOCMD when pushing the OCMD stack for BMC, patterns, and charprocs, for BDC with no optional content, or for forms or annotations that do not have an OC entry. When finished processing any of these objects, you can call PDOCContextPopOCMD() without worrying about whether the content was optional.
void PDOCContextPopOCMD(PDOCContext ocContext); ocContext | The context for which to pop the OCMD stack.
|
Pushes a new optional-content membership dictionary (OCMD) onto the stack for an optional-content context.
The stack is used to track nesting of optional-content states as contents are enumerated or drawn. Call this method when entering the BDC for optional content or beginning to process a form or annotation that has a OC entry. Call PDOCContextPopOCMD() when encountering an EMC, or finishing the processing of a form or annotation appearance.
To make it easier to track nested content that is not for optional content, pass NULL for pdOCMD when encountering BMC, patterns, and charprocs. Also pass NULL for a BDC with no optional content or for forms or annotations that do not have an OC entry. When finished processing any of these objects, you can call PDOCContextPopOCMD() without worrying about whether the content was optional.
void PDOCContextPushOCMD(PDOCContext pdOCContext, PDOCMD pdOCMD); pdOCContext | The context containing the OCMD stack.
|
pdOCMD | The OCMD to push onto the stack.
|
Clears the Optional Content Membership Dictionary (OCMD) stack for an optional-content context, and resets the current visibility for the context based on the context's non-OC drawing setting (see PDOCContextSetNonOCDrawing()). Call this method at the start of an enumeration or drawing operation that uses a given context.
The OCMD stack contains optional-content membership dictionary objects. The OCMD stack methods and the various methods that test visibility (such as PDAnnotIsCurrentlyVisible()) work together as content is being enumerated or drawn to determine whether particular graphical elements are visible or not. Visibility is based on the context's collection of ON-OFF states for optional-content groups, the context's current settings for NonOCDrawing and PDOCDrawEnumType, and the state of the OCMD stack.
Any custom drawing or enumerating code that needs to keep track of visibility of content must make a private copy of the PDOCContext if that context could be accessed by some other client, in order to avoid conflicting state changes. In particular, you must copy the document's default context (as returned by PDDocGetOCContext()). To enforce this, this reset method does nothing when given a document's default context. Similarly, the push and pop stack operations raise an error for the default context.
If you are using the PD-level draw and enumeration methods, you do not need to copy the context or explicitly call the OCMD stack methods, as the PD-level methods do this internally.
Clients of PDFEdit and other libraries that enumerate contents need to use these three methods when traversing the PDEContent structure. When entering a new PDEContent, call PDOCContextPushOCMD() (passing an OCMD object or NULL). Upon finishing the traversal, call PDOCContextPopOCMD().
void PDOCContextResetOCMDStack(PDOCContext pdOCContext); pdOCContext | The context for which to reset the OCMD stack.
|
Sets the Intent entry in an optional-content context'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.
It raises an exception if the context is busy.
void PDOCContextSetIntent(PDOCContext ocContext, ASAtom *intent); ocContext | The context for which to set the intent.
|
intent | The new Intent entry value, an array of atoms terminated with ASAtomNull.
|
Sets the non-OC status for an optional-content context. Content that is not marked as optional content is drawn when NonOCDrawing is true, and not drawn when NonOCDrawing is false.
Together, this value and the PDOCDrawEnumType value of the context determine how both optional and non-optional content on a page is drawn or enumerated. See PDOCDrawEnumType().
void PDOCContextSetNonOCDrawing(PDOCContext ocContext, ASBool drawNonOC); ocContext | The context for which to set the non-OC drawing status.
|
drawNonOC |
Sets the drawing and enumeration type for an optional-content context. This type, together with the visibility determined by the OCG and OCMD states, controls whether content that is marked as optional content is drawn or enumerated.
Together, this value and the NonOCDrawing value of the context determine how both optional and non-optional content on a page is drawn or enumerated. See PDOCDrawEnumType().
void PDOCContextSetOCDrawEnumType(PDOCContext ocContext, PDOCDrawEnumType dt); ocContext | The context for which the drawing and enumeration type is desired.
|
dt | The new drawing and enumeration type.
|
ON-OFF states for the given optional-content groups (OCGs) in the given optional-content context. The newStates array must be large enough to hold as many ASBool values as there are OCGs. void PDOCContextSetOCGStates(PDOCContext ocContext, PDOCG *pdocgs, ASBool *newStates); ocContext | The context for which the OCG states are set.
|
pdocgs | A
NULL-terminated array of optional-content groups. |
newStates |
Tests whether an XObject form or image contained in obj is visible in the optional-content context. The method considers the context's current OCMD stack, optional-content group ON-OFF states, the non-OC drawing status, the drawing and enumeration type, the intent, and the specific OCG.
Use this method in conjunction with the OCMD stack methods.
ASBool PDOCContextXObjectIsVisible(PDOCContext pdOCContext, CosObj obj); pdOCContext | The context for which to test visibility.
|
obj | The external object.
|