Namespace pdftron.PDF.OCG

Classes

Config

The OCG::Config object represents an optional-content (OC) configuration structure (see section 4.10.3 in PDF Reference), used to persist a set of visibility states and other optional-content information in a PDF file A document has a default configuration, saved in the D entry in the 'OCProperties' dictionary (that can be obtained using pdfdoc.GetOCConfig()), and can have a list of other configurations, saved as an array in the 'Configs' entry in the OCProperties dictionary.

Configurations are typically used to initialize the OCG ON-OFF states for an optional-content context (OCG::Context). The OCG order in the configuration is the order in which the groups appear in the Layers panel of a PDF viewer. The configuration can also define a set of mutually exclusive OCGs, called a radio button group.

Context

Begin processing a page.

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.

OCMD

            <p> The OCMD 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 (OCG::Group). The object directly corresponds to the OCMD dictionary (Section 4.10.1 'Optional Content Groups' in PDF Reference).

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. For example, an object can be visible only if some other conditions are met (such as if another layer is visible).

Enums

Context.OCDrawMode

OCDrawMode controls drawing or enumerating the page with respect to optional content. Together with the value of SetNonOCDrawing this mode controls drawing or enumerating content on a page with optional content:

  • Content that is marked as optional content is drawn or not drawn according to the OCDrawMode and the visibility state as determined by the Optional Content Groups (OCGs) and OCMDs.
  • Content that is not marked as optional content is drawn when GetNonOCDrawing() is true, and not drawn when GetNonOCDrawing() is false.

OCMD.VisibilityPolicyType

Visibility Policy Type. A Visibility Policy is used to determine whether an PDF::Element is visible in a given OCG::Context, depending on whether all groups in OCGs array are "ON" or "OFF", or when any of the groups is "ON" or "OFF".