Show / Hide Table of Contents

Class Group

The OCG.Group object represents an optional-content group. This corresponds to a PDF OCG dictionary representing a collection of graphic objects that can be made visible or invisible (Section 4.10.1 'Optional Content Groups' in PDF Reference). Any graphic content of the PDF can be made optional, including page contents, XObjects, and annotations. The specific content objects in the group have an OC entry in the PDF as part of the surrounding marked content or in the XObject dictionary. The group itself is a named object that can be typically manipulated through a Layers panel in a PDF viewer.

In the simplest case, the group's ON-OFF state makes the associated content visible or hidden. The ON-OFF state of a group can be toggled for a particular context (OCG.Context), and a set of states is kept in a configuration (OCG.Config). The visibility can depend on more than one group in an optional-content membership dictionary (OCG.OCMD), and can also be affected by the context's draw mode (OCGContext.OCDrawMode).

A group has an Intent entry, broadly describing the intended use. A group's content is considered to be optional (that is, the group's state is considered in its visibility) if any intent in its list matches an intent of the context. The intent list of the context is usually set from the intent list of the document configuration.

A Usage dictionary entry provides more specific intended usage information than an intent entry. Possible key values are: CreatorInfo, Language, Export, Zoom, Print, View, User, PageElement. The usage value can act as a kind of metadata, describing the sort of things that belong to the group, such as text in French, fine detail on a map, or a watermark. The usage values can also be used by the AutoState mechanism to make decisions about what groups should be on and what groups should be off. The AutoState mechanism considers the usage information in the OCGs, the AS array of the configuration, and external factors; for example, the language the application is running in, the current zoom level on the page, or whether the page is being printed.

Inheritance
System.Object
Group
Inherited Members
System.Object.Equals(System.Object)
System.Object.Equals(System.Object, System.Object)
System.Object.GetHashCode()
System.Object.GetType()
System.Object.MemberwiseClone()
System.Object.ReferenceEquals(System.Object, System.Object)
System.Object.ToString()
Namespace: pdftron.PDF.OCG
Assembly: PDFTronDotNet.dll
Syntax
public class Group

Constructors

Group(Obj)

Creates a new optional-content group (OCG) object from an existing SDF/Cos object.

Declaration
public Group(Obj ocg)
Parameters
Type Name Description
Obj ocg

the ocg

Methods

Create(PDFDoc, String)

Creates a new optional-content group (OCG) object in the document.

Declaration
public static Group Create(PDFDoc doc, string name)
Parameters
Type Name Description
PDFDoc doc

The document in which the new OCG will be created.

System.String name

The name of the optional-content group.

Returns
Type Description
Group

The newly created OCG.Group object.

Exceptions
Type Condition
PDFNetException

PDFNetException the PDFNet exception

GetCurrentState(Context)

Gets the current state.

Declaration
public bool GetCurrentState(Context context)
Parameters
Type Name Description
Context context

The context for which to get the group's state.

Returns
Type Description
System.Boolean

true if this OCG object is in the ON state in a given context, false otherwise.

Exceptions
Type Condition
PDFNetException

PDFNetException the PDFNet exception

GetInitialState(Config)

Gets the initial state.

Declaration
public bool GetInitialState(Config config)
Parameters
Type Name Description
Config config

The configuration for which to get the group's initial state.

Returns
Type Description
System.Boolean

The initial state (ON or OFF) of the optional-content group (OCG) object in a given configuration.

Remarks

If the configuration has a BaseState of Unchanged, and the OCG is not listed explicitly in its ON list or OFF list, then the initial state is taken from the OCG's current state in the document's default context.

Exceptions
Type Condition
PDFNetException

PDFNetException the PDFNet exception

GetIntent()

Gets the intent.

Declaration
public Obj GetIntent()
Returns
Type Description
Obj

OCG intent. An intent is a name object (or an array of name objects) broadly describing the intended use, which can be either "View" or "Design". A group's content is considered to be optional (that is, the group's state is considered in its visibility) if any intent in its list matches an intent of the context. The intent list of the context is usually set from the intent list of the document configuration.

Exceptions
Type Condition
PDFNetException

PDFNetException the PDFNet exception

GetName()

Gets the name.

Declaration
public string GetName()
Returns
Type Description
System.String

the name of this optional-content group (OCG).

Exceptions
Type Condition
PDFNetException

PDFNetException the PDFNet exception

GetSDFObj()

Gets the SDFObj.

Declaration
public Obj GetSDFObj()
Returns
Type Description
Obj

Pointer to the underlying SDF/Cos object.

Exceptions
Type Condition
PDFNetException

PDFNetException the PDFNet exception

GetUsage(String)

Gets the usage.

Declaration
public Obj GetUsage(string key)
Parameters
Type Name Description
System.String key

The usage key in the usage dictionary entry. The possible key values are: CreatorInfo, Language, Export, Zoom, Print, View, User, PageElement.

Returns
Type Description
Obj

The usage information associated with the given key in the Usage dictionary for the group, or a NULL if the entry is not present. A Usage dictionary entry provides more specific intended usage information than an intent entry.

Exceptions
Type Condition
PDFNetException

PDFNetException the PDFNet exception

HasUsage()

Checks for usage.

Declaration
public bool HasUsage()
Returns
Type Description
System.Boolean

true if this group is associated with a Usage dictionary, false otherwise.

Exceptions
Type Condition
PDFNetException

PDFNetException the PDFNet exception

IsLocked(Config)

Checks if is locked.

Declaration
public bool IsLocked(Config config)
Parameters
Type Name Description
Config config

The OC configuration.

Returns
Type Description
System.Boolean

true if this OCG is locked in a given configuration, false otherwise. The on/off state of a locked OCG cannot be toggled by the user through the user interface.

Exceptions
Type Condition
PDFNetException

PDFNetException the PDFNet exception

IsValid()

Checks if is valid.

Declaration
public bool IsValid()
Returns
Type Description
System.Boolean

True if this is a valid (non-null) OCG, false otherwise.

Exceptions
Type Condition
PDFNetException

PDFNetException the PDFNet exception

SetCurrentState(Context, Boolean)

Sets the current ON-OFF state of the optional-content group (OCG) object in a given context.

Declaration
public void SetCurrentState(Context context, bool state)
Parameters
Type Name Description
Context context

The context for which to set the group's state.

System.Boolean state

The new state.

Exceptions
Type Condition
PDFNetException

PDFNetException the PDFNet exception

SetInitialState(Config, Boolean)

Sets the initial state (ON or OFF) of the optional-content group (OCG) object in a given configuration.

Declaration
public void SetInitialState(Config config, bool state)
Parameters
Type Name Description
Config config

The configuration for which to set the group's initial state.

System.Boolean state

The new initial state, true if the state is ON, false if it is OFF.

Exceptions
Type Condition
PDFNetException

PDFNetException the PDFNet exception

SetIntent(Obj)

Sets the Intent entry in an optional-content group's SDF/Cos dictionary. For more information, see GetIntent().

Declaration
public void SetIntent(Obj intent)
Parameters
Type Name Description
Obj intent

The new Intent entry value (a name object or an array of name objects).

Exceptions
Type Condition
PDFNetException

PDFNetException the PDFNet exception

SetLocked(Config, Boolean)

Sets the locked state of an OCG in a given configuration. The on/off state of a locked OCG cannot be toggled by the user through the user interface.

Declaration
public void SetLocked(Config config, bool locked)
Parameters
Type Name Description
Config config

IN/OUT The optional-content configuration.

System.Boolean locked

true if the OCG should be locked, false otherwise.

Exceptions
Type Condition
PDFNetException

PDFNetException the PDFNet exception

SetName(String)

Sets the name of this optional-content group (OCG).

Declaration
public void SetName(string name)
Parameters
Type Name Description
System.String name

The new name.

Exceptions
Type Condition
PDFNetException

PDFNetException the PDFNet exception

Back to top Generated by DocFX