LayerPD_Layer
ObjectPDOCContext

The PDOCContext object represents an optional-content context in a document, within which document objects such as words or annotations are visible or hidden. The context keeps track of the ON-OFF states of all of the optional-content groups (OCGs, represented by the PDOCG object) in a document. Content is or is not visible with respect to the OCG states stored in a specific context. The context does not correspond to any explicit PDF specification.

The PDDoc has a default context that it uses for on-screen drawing and that determines the default state for any other drawing or content enumeration. The context has flags that control whether to draw or enumerate content that is marked as optional (PDOCDrawEnumType), and whether to draw content that is not marked as optional (NonOCDrawing).

There can be more than one PDOCContext object, representing different combinations of OCG states. You can change the states of OCGs within any context. You can build contexts with your own combination of OCG states, and issue drawing or enumeration commands using that context instead of the document's default context. For example, you can pass an optional-content context to PDPageDrawContentsWithParams() through the PDDrawParams structure. You can save the resulting state information as part of the configuration, but the context itself has no corresponding PDF form, and is not saved.



Typedef Summary
 Typedef
 PDOCContext
A PDOCContext is an object that keeps track the on/off states of all of the OCGs in a document. There can be more than one PDOCContext object, representing different combinations of OCG states. The PDDoc contains an internal PDOCContext that is used for on-screen drawing and as the default state used for any other drawing or content enumeration. Clients can change the states of OCGs within any PDOCContext. Clients can build (and save in the PDF file) PDOCContext objects with their own combination of OCG states, and issue drawing or enumeration commands using their own PDOCContext instead of the document's internal PDOCContext. All discussion of visibility of content is therefore meant to be with respect to the OCG states stored in a specific PDOCContext.
Enumeration Summary
 Enumeration
  PDOCContextChangeType
The optional-content group (OCG) state is changing.
  PDOCContextInitPolicy
PDOCContextInitPolicy is used to specify how to initialize the states of Optional Content Groups (OCGs) when calling PDOCContextNew() or PDOCContextInit().
Method Summary
 Method
 
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.
 
Removes usage override marks in all optional-content groups in the given context.
 
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.
 
void PDOCContextDidChange(PDOCContext ocContext, PDOCContextChangeType whatHappened, void* objects, ASErrorCode error, void* clientData)
An optional-content context changed in a way that could affect the visibility state of content.
 
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.
 
Destroys an optional-content context object and frees the associated memory as needed.
 
Gets the intent list for an optional-content context. An intent is an ASAtom value broadly describing the intended use, either View or Design.
 
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.
 
PDOCDrawEnumType PDOCContextGetOCDrawEnumType(PDOCContext ocContext)
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.
 
void PDOCContextGetOCGStates(PDOCContext ocContext, PDOCG* pdocgs, ASBool* states)
Gets the 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.
 
Gets the document that contains an optional-content context.
 
void PDOCContextInit(PDOCContext ocContext, PDOCContextInitPolicy policy, PDOCContext otherCtx, PDOCConfig pdOCCfg)
Initializes the ON-OFF states of all optional-content groups (OCGs) within an existing context.
 
PDOCContext PDOCContextMakeCopy(PDOCContext ocContext)
Creates a new context object to represent an optional-content state of the document, using an existing context as a template.
 
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.
 
PDOCContext PDOCContextNew(PDOCContextInitPolicy policy, PDOCContext otherCtx, PDOCConfig pdOCCfg, PDDoc pdDoc)
Creates a context object that represents an optional-content state of the document, initializing it in the same way as PDOCContextInit().
 
Creates a context object that represents an optional-content state of the document, using the current state as the initial state for each group (OCG), as determined by the document's optional-content configuration (returned by PDDocGetOCConfig(pdDoc)).
 
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.
 
Pops the optional-content membership dictionary (OCMD) stack for an optional-content context. The stack is used to track nesting of optional-content states as contents are enumerated or drawn:
 
void PDOCContextPushOCMD(PDOCContext pdOCContext, PDOCMD pdOCMD)
Pushes a new optional-content membership dictionary (OCMD) onto the stack for an optional-content context.
 
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.
 
void PDOCContextSetIntent(PDOCContext ocContext, ASAtom* intent)
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.
 
void PDOCContextSetNonOCDrawing(PDOCContext ocContext, ASBool drawNonOC)
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.
 
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.
 
void PDOCContextSetOCGStates(PDOCContext ocContext, PDOCG* pdocgs, ASBool* newStates)
Sets the 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 PDOCContextWillChange(PDOCContext ocContext, PDOCContextChangeType whatWillHappen, void* objects, void* clientData)
An optional-content context is changing in a way that could affect the visibility state of content.
 
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.

Typedefs Detail
PDOCContext 
Product availability: All
Platform availability: All

Syntax

typedef struct _t_PDOCContext* PDOCContext;

A PDOCContext is an object that keeps track the on/off states of all of the OCGs in a document. There can be more than one PDOCContext object, representing different combinations of OCG states. The PDDoc contains an internal PDOCContext that is used for on-screen drawing and as the default state used for any other drawing or content enumeration. Clients can change the states of OCGs within any PDOCContext. Clients can build (and save in the PDF file) PDOCContext objects with their own combination of OCG states, and issue drawing or enumeration commands using their own PDOCContext instead of the document's internal PDOCContext. All discussion of visibility of content is therefore meant to be with respect to the OCG states stored in a specific PDOCContext.


File: PDExpT.h
Line: 5542

Enumeration Detail
PDOCContextChangeType
Product availability: All
Platform availability: All

Syntax

enum PDOCContextChangeType {
 kPDOCGState,
 
 kPDOCContextDrawEnumType,
 
 kPDOCContextNonOCDrawing,
 
 kPDOCContextIntent,
 
 kPDOCContextInit,
 
 kPDOC_LastContextChangeType = kPDOCContextInit
}

File: PDExpT.h
Line: 5643

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

 
PDOCContextInitPolicy 
Product availability: All
Platform availability: All

Syntax

enum PDOCContextInitPolicy {
 kOCCInit_OFF,
 
 kOCCInit_ON,
 
 kOCCInit_FromOtherContext,
 
 kOCCInit_FromConfig
}

File: PDExpT.h
Line: 5572



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

Syntax

ASBool PDOCContextApplyAutoStateChanges(PDOCContext ctx, PDOCConfig cfg, ASAtom event)

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 PDF Reference, and the OCTextAutoStateSnip example in the Snippet Runner.

Parameters

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.

Returns

true if successful, false otherwise.

See Also

Since

PI_PDMODEL_VERSION >= 0x00060000

File: PDProcs.h
Line: 9580
PDOCContextClearAllUserOverrides() 
Product availability: All
Platform availability: All

Syntax

void PDOCContextClearAllUserOverrides(PDOCContext ctx)

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 PDF Reference, and the OCTextAutoStateSnip example in the Snippet Runner.

Parameters

ctx — 

The context for which the user override marks are removed.

See Also

Since

PI_PDMODEL_VERSION >= 0x00060000

File: PDProcs.h
Line: 10327
PDOCContextContentIsVisible() 
Product availability: All
Platform availability: All

Syntax

ASBool PDOCContextContentIsVisible(PDOCContext ocContext)

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.

Parameters

ocContext — 

The context for which the visibility state is desired.

Returns

true if the content is visible, false otherwise.

See Also

Since

PI_PDMODEL_VERSION >= 0x00060000

File: PDProcs.h
Line: 9838
PDOCContextDidChange() 
Product availability: All
Platform availability: All

Syntax

void PDOCContextDidChange(PDOCContext ocContext, PDOCContextChangeType whatHappened, void* objects, ASErrorCode error, void* clientData)

An optional-content context changed in a way that could affect the visibility state of content.

Parameters

ocContext — 

The PDOCContext whose visibility state changed.

 
whatHappened — 

The type of change that occurred.

 
objects — 

A pointer to the object that changed. The kind of object this can be depends on the type of change that occurred:

Value

Type of object

kPDOCGCreate

PDOCG

kPDOCGDestroy

NULL

kPDOCGProperties

PDOCG

kPDOCConfigChange

PDOCConfig

kPDOCConfigCreate

PDOCConfig

kPDOCConfigDestroy

NULL

kPDOCGReplace

PDOCG (the replacement)

kPDDocRemoveOC

NULL

 
error — 

If non-zero, indicates an error that occurred while setting the optional-content context.

 
clientData — 

A pointer to a block of user-supplied data that was passed when the client registered for this notification using AVAppRegisterNotification() .


File: PIPokes.h
Line: 2345
PDOCContextFindAutoStateChanges() 
Product availability: All
Platform availability: All

Syntax

PDOCG PDOCContextFindAutoStateChanges(PDOCContext ctx, PDOCConfig cfg, ASAtom event)

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. See the PDF Reference, and the OCTextAutoStateSnip example in the Snippet Runner.

Parameters

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.

Returns

A NULL-terminated array of optional-content group objects. The client is responsible for freeing it using ASfree().

See Also

Since

PI_PDMODEL_VERSION >= 0x00060000

File: PDProcs.h
Line: 9551
PDOCContextFree() 
Product availability: All
Platform availability: All

Syntax

void PDOCContextFree(PDOCContext ocContext)

Destroys an optional-content context object and frees the associated memory as needed.

Parameters

ocContext — 

The context object to free.

See Also

Since

PI_PDMODEL_VERSION >= 0x00060000

File: PDProcs.h
Line: 9352
PDOCContextGetIntent() 
Product availability: All
Platform availability: All

Syntax

ASAtom PDOCContextGetIntent(PDOCContext ocContext)

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.

Parameters

ocContext — 

The context for which an intent is desired.

Returns

An array containing intent entries (ASAtom objects) terminated by ASAtomNull. The client is responsible for freeing it using ASfree().

See Also

Since

PI_PDMODEL_VERSION >= 0x00060000

File: PDProcs.h
Line: 9668
PDOCContextGetNonOCDrawing() 
Product availability: All
Platform availability: All

Syntax

ASBool PDOCContextGetNonOCDrawing(PDOCContext ocContext)

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

Parameters

ocContext — 

The context for which the non-OC drawing status is desired.

Returns

true if the context's NonOCDrawing is true, false otherwise.

See Also

Since

PI_PDMODEL_VERSION >= 0x00060000

File: PDProcs.h
Line: 9709
PDOCContextGetOCDrawEnumType() 
Product availability: All
Platform availability: All

Syntax

PDOCDrawEnumType PDOCContextGetOCDrawEnumType(PDOCContext ocContext)

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

Parameters

ocContext — 

The context for which the drawing and enumeration type is desired.

Returns

The drawing and enumeration type value.

See Also

Since

PI_PDMODEL_VERSION >= 0x00060000

File: PDProcs.h
Line: 9618
PDOCContextGetOCGStates() 
Product availability: All
Platform availability: All

Syntax

void PDOCContextGetOCGStates(PDOCContext ocContext, PDOCG* pdocgs, ASBool* states)

Gets the 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.

Parameters

ocContext — 

The context for which the OCG states are desired.

 
pdocgs — 

A NULL-terminated array of optional-content groups whose states are obtained.

 
states — 

(Filled by the method) An array of OCG states corresponding to the array of OCGs, true for ON and false for OFF. The array must be large enough to hold as many states as there are non-NULL OCGs.

See Also

Since

PI_PDMODEL_VERSION >= 0x00060000

File: PDProcs.h
Line: 9475
PDOCContextGetPDDoc() 
Product availability: All
Platform availability: All

Syntax

PDDoc PDOCContextGetPDDoc(PDOCContext ocContext)

Gets the document that contains an optional-content context.

Parameters

ocContext — 

The context for which a document is desired.

Returns

The document object.

See Also

Since

PI_PDMODEL_VERSION >= 0x00060000

File: PDProcs.h
Line: 9376
PDOCContextInit() 
Product availability: All
Platform availability: All

Syntax

void PDOCContextInit(PDOCContext ocContext, PDOCContextInitPolicy policy, PDOCContext otherCtx, PDOCConfig pdOCCfg)

Initializes the ON-OFF states of all optional-content groups (OCGs) within an existing context.

Parameters

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 kPDOCInit_FromOtherContext. It is ignored for other policies.

 
pdOCCfg — 

A configuration from which to take initial OCG states when the policy is kPDOCInit_FromConfig. It is ignored for other policies.

See Also

Since

PI_PDMODEL_VERSION >= 0x00060000

File: PDProcs.h
Line: 9395
PDOCContextMakeCopy() 
Product availability: All
Platform availability: All

Syntax

PDOCContext PDOCContextMakeCopy(PDOCContext ocContext)

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));

Parameters

ocContext — 

The context to copy.

Returns

The new PDOCContext object. The client is responsible for freeing the context using PDOCContextFree().

See Also

Since

PI_PDMODEL_VERSION >= 0x00060000

File: PDProcs.h
Line: 9414
PDOCContextMakeCopyWithAutoStateChanges() 
Product availability: All
Platform availability: All

Syntax

PDOCContext PDOCContextMakeCopyWithAutoStateChanges(PDOCContext inCtx, PDOCConfig cfg, ASAtom event)

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. See the PDF Reference, and the OCTextAutoStateSnip example in the Snippet Runner.

Parameters

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.

Returns

The new PDOCContext object. The client is responsible for freeing the context using PDOCContextFree().

See Also

Since

PI_PDMODEL_VERSION >= 0x00060000

File: PDProcs.h
Line: 9523
PDOCContextNew() 
Product availability: All
Platform availability: All

Syntax

PDOCContext PDOCContextNew(PDOCContextInitPolicy policy, PDOCContext otherCtx, PDOCConfig pdOCCfg, PDDoc pdDoc)

Creates a context object that represents an optional-content state of the document, initializing it in the same way as PDOCContextInit().

Parameters

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 kPDOCInit_FromOtherContext. It is ignored for other policies.

 
pdOCCfg — 

A configuration from which to take initial OCG states when the policy is kPDOCInit_FromConfig. It is ignored for other policies.

 
pdDoc — 

The document for which to create a context.

Returns

The new PDOCContext object. The client is responsible for freeing the context using PDOCContextFree().

See Also

Since

PI_PDMODEL_VERSION >= 0x00060000

File: PDProcs.h
Line: 9342
PDOCContextNewWithInitialState() 
Product availability: All
Platform availability: All

Syntax

PDOCContext PDOCContextNewWithInitialState(PDDoc pdDoc)

Creates a context object that represents an optional-content state of the document, using the current state as the initial state for each group (OCG), as determined by the document's optional-content configuration (returned by PDDocGetOCConfig(pdDoc)).

Parameters

pdDoc — 

The document for which to create a context.

Returns

The new PDOCContext object. The client is responsible for freeing the context using PDOCContextFree().

See Also

Since

PI_PDMODEL_VERSION >= 0x00060000

File: PDProcs.h
Line: 9457
PDOCContextNewWithOCDisabled() 
Product availability: All
Platform availability: All

Syntax

PDOCContext PDOCContextNewWithOCDisabled(PDDoc pdDoc)

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.

Parameters

pdDoc — 

The document for which to create a context.

Returns

The new PDOCContext object. The client is responsible for freeing the context using PDOCContextFree().

See Also

Since

PI_PDMODEL_VERSION >= 0x00060000

File: PDProcs.h
Line: 9439
PDOCContextPopOCMD() 
Product availability: All
Platform availability: All

Syntax

void PDOCContextPopOCMD(PDOCContext ocContext)

Pops the optional-content membership dictionary (OCMD) stack for an optional-content context. The stack is used to track nesting of optional-content states as contents are enumerated or drawn:

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.

Parameters

ocContext — 

The context for which to pop the OCMD stack.

See Also

Since

PI_PDMODEL_VERSION >= 0x00060000

File: PDProcs.h
Line: 9818
PDOCContextPushOCMD() 
Product availability: All
Platform availability: All

Syntax

void PDOCContextPushOCMD(PDOCContext pdOCContext, PDOCMD pdOCMD)

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.

Parameters

pdOCContext — 

The context containing the OCMD stack.

 
pdOCMD — 

The OCMD to push onto the stack.

See Also

Since

PI_PDMODEL_VERSION >= 0x00060000

File: PDProcs.h
Line: 9786
PDOCContextResetOCMDStack() 
Product availability: All
Platform availability: All

Syntax

void PDOCContextResetOCMDStack(PDOCContext pdOCContext)

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

Parameters

pdOCContext — 

The context for which to reset the OCMD stack.

See Also

Since

PI_PDMODEL_VERSION >= 0x00060000

File: PDProcs.h
Line: 9756
PDOCContextSetIntent() 
Product availability: All
Platform availability: All

Syntax

void PDOCContextSetIntent(PDOCContext ocContext, ASAtom* intent)

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.

Parameters

ocContext — 

The context for which to set the intent.

 
intent — 

The new Intent entry value, an array of atoms terminated with ASAtomNull.

See Also

Since

PI_PDMODEL_VERSION >= 0x00060000

File: PDProcs.h
Line: 9644
PDOCContextSetNonOCDrawing() 
Product availability: All
Platform availability: All

Syntax

void PDOCContextSetNonOCDrawing(PDOCContext ocContext, ASBool drawNonOC)

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

Parameters

ocContext — 

The context for which to set the non-OC drawing status.

 
drawNonOC — 

The new value for the non-OC drawing status, true or false.

See Also

Since

PI_PDMODEL_VERSION >= 0x00060000

File: PDProcs.h
Line: 9688
PDOCContextSetOCDrawEnumType() 
Product availability: All
Platform availability: All

Syntax

void PDOCContextSetOCDrawEnumType(PDOCContext ocContext, PDOCDrawEnumType dt)

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

Parameters

ocContext — 

The context for which the drawing and enumeration type is desired.

 
dt — 

The new drawing and enumeration type.

See Also

Since

PI_PDMODEL_VERSION >= 0x00060000

File: PDProcs.h
Line: 9599
PDOCContextSetOCGStates() 
Product availability: All
Platform availability: All

Syntax

void PDOCContextSetOCGStates(PDOCContext ocContext, PDOCG* pdocgs, ASBool* newStates)

Sets the 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.

Parameters

ocContext — 

The context for which the OCG states are set.

 
pdocgs — 

A NULL-terminated array of optional-content groups.

 
newStates — 

An array of new OCG states corresponding to the array of OCGs, true for ON and false for OFF. The array must contain as many states as there are non-NULL OCGs in the pdocgs array.

See Also

Since

PI_PDMODEL_VERSION >= 0x00060000

File: PDProcs.h
Line: 9493
PDOCContextWillChange() 
Product availability: All
Platform availability: All

Syntax

void PDOCContextWillChange(PDOCContext ocContext, PDOCContextChangeType whatWillHappen, void* objects, void* clientData)

An optional-content context is changing in a way that could affect the visibility state of content.

Parameters

ocContext — 

The PDOCContext whose visibility state will change.

 
whatWillHappen — 

The type of change that will occur.

 
objects — 

A pointer to the object that will change. The kind of object this can be depends on the type of change that will occur:

Value

Type of object

kPDOCGCreate

PDOCG

kPDOCGDestroy

NULL

kPDOCGProperties

PDOCG

kPDOCConfigChange

PDOCConfig

kPDOCConfigCreate

PDOCConfig

kPDOCConfigDestroy

NULL

kPDOCGReplace

PDOCG (the replacement)

kPDDocRemoveOC

NULL

 
clientData — 

A pointer to a block of user-supplied data that was passed when the client registered for this notification using AVAppRegisterNotification() .


File: PIPokes.h
Line: 2318
PDOCContextXObjectIsVisible() 
Product availability: All
Platform availability: All

Syntax

ASBool PDOCContextXObjectIsVisible(PDOCContext pdOCContext, CosObj obj)

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.

Parameters

pdOCContext — 

The context for which to test visibility.

 
obj — 

The external object.

Returns

true if the external object is visible, false otherwise.

See Also

Since

PI_PDMODEL_VERSION >= 0x00060000

File: PDProcs.h
Line: 9860