PD_Layer.PDOCContext (Acrobat)

	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
	`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
	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.
	void PDOCContextClearAllUserOverrides(PDOCContext ctx) Removes usage override marks in all optional-content groups in the given context.
	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.
	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.
	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.
	void PDOCContextFree(PDOCContext ocContext) Destroys an optional-content context object and frees the associated memory as needed.
	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.
	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.
	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.
	PDDoc PDOCContextGetPDDoc(PDOCContext ocContext) 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.
	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.
	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().
	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)).
	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.
	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:
	void PDOCContextPushOCMD(PDOCContext pdOCContext, PDOCMD pdOCMD) Pushes a new optional-content membership dictionary (OCMD) onto the stack for an optional-content context.
	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.
	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.
	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.
	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.
	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.

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.

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.

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.

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.

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

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

PDOCContextInit
PDOCContextNew

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

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.

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.

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

PDOCContextSetOCGStates

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

PDDocGetOCContext

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

PDOCContextNew
PDOCContextFree

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

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.

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

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

PDOCContextInit
PDOCContextFree

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

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

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:

Call the PDOCContextPushOCMD() method when entering BDC for optional content or beginning to process a form or annotation that has a OC entry.
Call this method to pop the stack when encountering EMC, or finishing the processing of a form or annotation appearance.

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.

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.

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.

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.

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.

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

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.

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

PDOCContextGetOCGStates

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.

Since

PI_PDMODEL_VERSION >= 0x00060000

File: PDProcs.h

Line: 9860

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

	kPDOCGState,

	kPDOCContextDrawEnumType,

	kPDOCContextNonOCDrawing,

	kPDOCContextIntent,

	kPDOCContextInit,

	kPDOC_LastContextChangeType = kPDOCContextInit

	kOCCInit_OFF,

	kOCCInit_ON,

	kOCCInit_FromOtherContext,

	kOCCInit_FromConfig

Layer	PD_Layer
Object	PDOCContext