LayerPD_Layer
ObjectPDOCMD

The PDOCMD object represents an optional-content membership dictionary (OCMD) that allows the visibility of optional content to depend on the states in a set of optional-content groups (PDOCG). The object corresponds to the PDF OCMD dictionary.

An OCMD collects a set of OCGs. It sets a visibility policy, so that content in the member groups is visible only when all groups are ON or OFF, or when any of the groups is ON or OFF. This makes it possible to set up complex dependencies among groups.

An optional-content context can contain a stack of OCMD objects, which you can manipulate with PDOCContextPopOCMD(), PDOCContextPushOCMD(), and PDOCContextResetOCMDStack().

An OCMD can be associated with an annotation (PDAnnotSetOCMD()) or a PDE element (PDEElementSetOCMD()).



Typedef Summary
 Typedef
 PDOCMD
A PDOCMD is an object that is attached to content to indicate membership in an OCG or group of OCGs.
Enumeration Summary
 Enumeration
  PDOCMDVisPolicy
PDOCMDVisPolicy represents the four legal values for the /P key in an Optional Content Membership Dictionary (OCMD) dictionary. They specify the visibility of content with respect to the on/off state of the Optional Content Groups (OCGs) listed in the OCMD.
Method Summary
 Method
 
PDOCMD PDOCMDCreate(PDDoc pdDoc, PDOCG* ocgs, PDOCMDVisPolicy policy)
Creates a new optional-content membership dictionary (OCMD) object in the given document for the given groups and visibility policy.
 
PDOCMD PDOCMDFindOrCreate(PDDoc pdDoc, PDOCG* ocgs, PDOCMDVisPolicy policy)
Locates an existing optional-content membership dictionary (OCMD) object that references the given groups, and that uses the same visibility policy. If no such dictionary is found, the method creates one.
 
PDOCMD PDOCMDFindOrCreateEx(PDDoc pdDoc, PDOCG* ocgs, PDOCMDVisPolicy policy, CosObj veObj)
Locates an existing optional-content membership dictionary (PDOCMD) object that references the given groups, uses the same visibility policy, and uses the same visibility expression. If no such PDOCMD is found, the method creates one.
 
CosObj PDOCMDGetCosObj(PDOCMD pdocmd)
Gets the Cos object associated with the optional-content membership dictionary (OCMD) object.
 
Gets an optional-content membership dictionary (OCMD) object from the associated Cos object.
 
PDOCG* PDOCMDGetOCGs(PDOCMD pdocmd)
Gets the optional-content groups listed in a membership dictionary.
 
PDDoc PDOCMDGetPDDoc(PDOCMD pdocmd)
Gets the document that contains an optional-content membership dictionary.
 
If the PDOCMD has a visibility expression entry, the function returns true, and if veObj is non-NULL, *veObj is set to the CosObj for the visibility expression. If the PDOCMD does not have a visibility expression entry, the function returns false.
 
PDOCMDVisPolicy PDOCMDGetVisPolicy(PDOCMD pdocmd)
Gets the optional-content membership dictionary's visibility policy, which determines the visibility of content with respect to the ON-OFF state of OCGs listed in the dictionary.
 
ASBool PDOCMDIsCurrentlyVisible(PDOCMD pdocmd, PDOCContext ocContext)
Based on the optional-content groups listed in the dictionary, the current ON-OFF state of those groups within the specified context, and the dictionary's visibility policy, test whether the content tagged with this dictionary would be visible.
 
ASBool PDOCMDsAreCurrentlyVisible(PDOCMD* pdocmds, PDOCContext ocContext)
Tests a set of optional-content membership dictionaries to determine whether contents tagged with any of them is visible in a given optional-content context. The method calls PDOCMDIsCurrentlyVisible() on each of the dictionaries. If content is visible in the given context in any of the dictionaries, this method returns true.
 
ASBool PDOCMDsMakeContentVisible(PDOCMD* ocmds, PDOCContext ocContext)
Makes content that uses any of a set of optional-content membership dictionaries visible in a given optional-content context. The method manipulates the states of optional-content groups in the dictionaries so that any content controlled by any of the dictionaries will be visible in the given context. There can be more than one combination of states that satisfies the request. The particular combination of states is not guaranteed from one call to the next.

Typedefs Detail
PDOCMD 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

typedef struct _t_PDOCMD* PDOCMD;

A PDOCMD is an object that is attached to content to indicate membership in an OCG or group of OCGs.


File: PDExpT.h
Line: 5531

Enumeration Detail
PDOCMDVisPolicy
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

enum PDOCMDVisPolicy {
 kOCMDVisibility_AllOn,
 
 kOCMDVisibility_AnyOn,
 
 kOCMDVisibility_AnyOff,
 
 kOCMDVisibility_AllOff
}

File: PDExpT.h
Line: 5559



Method Detail
PDOCMDCreate()
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

PDOCMD PDOCMDCreate(PDDoc pdDoc, PDOCG* ocgs, PDOCMDVisPolicy policy)

Creates a new optional-content membership dictionary (OCMD) object in the given document for the given groups and visibility policy.

To add a group to an existing OCMD, get the current OCG list, modify it, then create a new OCMD with the new list of groups.

Parameters

pdDoc — 

The document in which the dictionary is used.

 
ocgs — 

A NULL-terminated array of optional-content groups (OCGs) to be members of the dictionary.

 
policy — 

The visibility policy that determines the visibility of content with respect to the ON-OFF state of OCGs listed in the dictionary.

Returns

The newly created dictionary object, or NULL if no groups are supplied.

See Also

Since

PI_PDMODEL_VERSION >= 0x00060000

File: PDProcs.h
Line: 9099
PDOCMDFindOrCreate() 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

PDOCMD PDOCMDFindOrCreate(PDDoc pdDoc, PDOCG* ocgs, PDOCMDVisPolicy policy)

Locates an existing optional-content membership dictionary (OCMD) object that references the given groups, and that uses the same visibility policy. If no such dictionary is found, the method creates one.

If only one group is supplied, the policy is kOCMDVisibility_AnyOn or kOCMDVisibility_AllOn, and no matching dictionary is found, the method creates an OCMD that directly contains the group without the level of indirection normally introduced by an OCMD. If the indirection is needed to add more groups to the OCMD, use PDOCMDCreate().

To add a group to an existing OCMD, get the current OCG list, modify it, then create a new OCMD with the new list of groups.

Parameters

pdDoc — 

The document in which the dictionary is used.

 
ocgs — 

A NULL-terminated array of optional-content groups (OCGs) to be members of the dictionary.

 
policy — 

The visibility policy that determines the visibility of content with respect to the ON-OFF state of OCGs listed in the dictionary.

Returns

The newly created or existing dictionary object, or NULL if no groups are supplied.

See Also

Since

PI_PDMODEL_VERSION >= 0x00060000

File: PDProcs.h
Line: 9133
PDOCMDFindOrCreateEx() 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

PDOCMD PDOCMDFindOrCreateEx(PDDoc pdDoc, PDOCG* ocgs, PDOCMDVisPolicy policy, CosObj veObj)

Locates an existing optional-content membership dictionary (PDOCMD) object that references the given groups, uses the same visibility policy, and uses the same visibility expression. If no such PDOCMD is found, the method creates one.

The fourth parameter, veObj must be a CosNull object or a CosArray object. If it is a CosNull object, this call is identical to PDOCMDFindOrCreate(). If it is an array object, it is used as the OCMD's visibility expression.

Parameters

pdDoc — 

The PDDoc in which to create the PDOCMD.

 
ocgs — 

A list of OCGs, or NULL if only a visibility expression is to be used.

 
policy — 

The visibility policy to use. unused if ocgs is NULL.

 
veObj — 

A CosObj containing a visibility expression.

Returns

See Also

Since

PI_PDMODEL_VERSION >= 0x00070000

File: PDProcs.h
Line: 11085
PDOCMDGetCosObj() 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

CosObj PDOCMDGetCosObj(PDOCMD pdocmd)

Gets the Cos object associated with the optional-content membership dictionary (OCMD) object.

Parameters

pdocmd — 

The dictionary object.

Returns

The Cos object.

See Also

Since

PI_PDMODEL_VERSION >= 0x00060000

File: PDProcs.h
Line: 9143
PDOCMDGetFromCosObj() 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

PDOCMD PDOCMDGetFromCosObj(CosObj obj)

Gets an optional-content membership dictionary (OCMD) object from the associated Cos object.

Parameters

obj — 

The Cos object.

Returns

The dictionary object.

See Also

Since

PI_PDMODEL_VERSION >= 0x00060000

File: PDProcs.h
Line: 9166
PDOCMDGetOCGs() 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

PDOCG PDOCMDGetOCGs(PDOCMD pdocmd)

Gets the optional-content groups listed in a membership dictionary.

Parameters

pdocmd — 

The membership dictionary whose OCGs are obtained.

Returns

A NULL-terminated array of the document's optional-content groups. The client is responsible for freeing the array using ASfree().

Since

PI_PDMODEL_VERSION >= 0x00060000

File: PDProcs.h
Line: 9178
PDOCMDGetPDDoc() 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

PDDoc PDOCMDGetPDDoc(PDOCMD pdocmd)

Gets the document that contains an optional-content membership dictionary.

Parameters

pdocmd — 

The dictionary for which the document is desired.

Returns

The document object.

See Also

Since

PI_PDMODEL_VERSION >= 0x00060000

File: PDProcs.h
Line: 9155
PDOCMDGetVisibilityExpression() 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

ASBool PDOCMDGetVisibilityExpression(PDOCMD ocmd, CosObj* veObj)

If the PDOCMD has a visibility expression entry, the function returns true, and if veObj is non-NULL, *veObj is set to the CosObj for the visibility expression. If the PDOCMD does not have a visibility expression entry, the function returns false.

Parameters

ocmd — 

The PDOCMD in which to check for a visibility expression.

 
veObj — 

The cos object in which to return the visibility expression.

Returns

true if there is a visibility expression, false otherwise.

See Also

Since

PI_PDMODEL_VERSION >= 0x00070000

File: PDProcs.h
Line: 11099
PDOCMDGetVisPolicy() 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

PDOCMDVisPolicy PDOCMDGetVisPolicy(PDOCMD pdocmd)

Gets the optional-content membership dictionary's visibility policy, which determines the visibility of content with respect to the ON-OFF state of OCGs listed in the dictionary.

Parameters

pdocmd — 

The dictionary whose policy is obtained.

Returns

The visibility policy.

See Also

Since

PI_PDMODEL_VERSION >= 0x00060000

File: PDProcs.h
Line: 9191
PDOCMDIsCurrentlyVisible() 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

ASBool PDOCMDIsCurrentlyVisible(PDOCMD pdocmd, PDOCContext ocContext)

Based on the optional-content groups listed in the dictionary, the current ON-OFF state of those groups within the specified context, and the dictionary's visibility policy, test whether the content tagged with this dictionary would be visible.

It ignores the context's current PDOCDrawEnumType and NonOCDrawing settings.

Parameters

pdocmd — 

The dictionary.

 
ocContext — 

The context in which the visibility of content is tested.

Returns

true if content tagged with this dictionary is visible in the given context, false if it is hidden.

See Also

Since

PI_PDMODEL_VERSION >= 0x00060000

File: PDProcs.h
Line: 9251
PDOCMDsAreCurrentlyVisible() 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

ASBool PDOCMDsAreCurrentlyVisible(PDOCMD* pdocmds, PDOCContext ocContext)

Tests a set of optional-content membership dictionaries to determine whether contents tagged with any of them is visible in a given optional-content context. The method calls PDOCMDIsCurrentlyVisible() on each of the dictionaries. If content is visible in the given context in any of the dictionaries, this method returns true.

Parameters

pdocmds — 

A NULL-terminated array of dictionaries to test.

 
ocContext — 

The context in which visibility is tested.

Returns

true if content using any of the dictionaries is visible in the given context, false if it is hidden for all of the dictionaries.

See Also

Since

PI_PDMODEL_VERSION >= 0x00060000

File: PDProcs.h
Line: 9270
PDOCMDsMakeContentVisible() 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

ASBool PDOCMDsMakeContentVisible(PDOCMD* ocmds, PDOCContext ocContext)

Makes content that uses any of a set of optional-content membership dictionaries visible in a given optional-content context. The method manipulates the states of optional-content groups in the dictionaries so that any content controlled by any of the dictionaries will be visible in the given context. There can be more than one combination of states that satisfies the request. The particular combination of states is not guaranteed from one call to the next.

The method returns false if it is not possible to make the content visible (for example, if there are nested dictionaries where one specifies "show if the group state is ON" and the other specifies "show if the group state is OFF"). In such a case, visibility is always off, so no state setting can make the content visible.

This method ignores the context's draw type.

Parameters

ocmds — 

A NULL-terminated array of dictionaries to act upon.

 
ocContext — 

The context in which the contents are made visible.

Returns

true if successful or if the OCMD list is empty, false otherwise.

See Also

Since

PI_PDMODEL_VERSION >= 0x00060000

File: PDProcs.h
Line: 9318