• Create BookmarkCreate Bookmark
  • Create Note or TagCreate Note or Tag
  • PrintPrint
Share this Page URL
Help

Chapter 4. Graphics > Optional Content

4.10. Optional Content

Optional content (PDF 1.5) refers to sections of content in a PDF document that can be selectively viewed or hidden by document authors or consumers. This capability is useful in items such as CAD drawings, layered artwork, maps, and multi-language documents.

The following sections describe the PDF structures used to implement optional content:

  • Section 4.10.1, “Optional Content Groups,” describes the primary structures used to control the visibility of content.

  • Section 4.10.2, “Making Graphical Content Optional,” describes how individual pieces of content in a document may declare themselves as belonging to one or more optional content groups.

  • Section 4.10.3, “Configuring Optional Content,” describes how the states of optional content groups are set.

4.10.1. Optional Content Groups

An optional content group is a dictionary representing a collection of graphics that can be made visible or invisible dynamically by users of viewer applications. The graphics belonging to such a group can reside anywhere in the document: they need not be consecutive in drawing order, nor even belong to the same content stream. Table 4.48 shows the entries in an optional content group dictionary.

Table 4.48. Entries in an optional content group dictionary
KEYTYPEVALUE
TYPEname(Required) The type of PDF object that this dictionary describes; must be OCG for an optional content group dictionary.
Nametext string(Required) The name of the optional content group, suitable for presentation in a viewer application's user interface.
Intentname or array(Optional) A single intent name or an array containing any combination of names. PDF 1.5 defines two names, View and Design, that indicate the intended use of the graphics in the group. Future versions may define others. A processing application can choose to use only groups that have a specific intent and ignore others. Default value: View. See “Intent” on page 340 for more information.
Usagedictionary(Optional) A usage dictionary describing the nature of the content controlled by the group. It may be used by features that automatically control the state of the group based on outside factors. See “Usage and Usage Application Dictionaries” on page 352 for more information.


In its simplest form, each dictionary contains a TYPE entry and a Name for presentation in a user interface. It may also have an Intent entry that describes its intended use (see “Intent” on page 340) and a Usage entry that describes the nature of its content (see “Usage and Usage Application Dictionaries” on page 352).

Individual content elements in a document specify the optional content group or groups that affect their visibility (see Section 4.10.2, “Making Graphical Content Optional”). Any content whose visibility can be affected by a given optional content group is said to belong to that group.

A group is assigned a state, which is either ON or OFF. States are not themselves part of the PDF document but can be set programmatically or through the viewer user interface to change the visibility of content. When a document is first opened, the groups' states are initialized based on the document's default configuration dictionary (see “Optional Content Configuration Dictionaries” on page 347).

In the typical case, content belonging to a group is visible when the group is ON and invisible when it is OFF. In more complex cases, content can belong to multiple groups, which may have conflicting states. These cases are described by the use of optional content membership dictionaries, described in the next section.

Optional Content Membership Dictionaries

As mentioned above, content typically belongs to a single optional content group and is visible when the group is ON and invisible when it is OFF. To express more complex visibility policies, content should declare itself not to belong directly to an optional content group but rather to an optional content membership dictionary, whose entries are shown in Table 4.49. (Section 4.10.2 describes how content declares its membership in a group or membership dictionary.)

Table 4.49. Entries in an optional content membership dictionary
KEYTYPEVALUE
TYPEname(Required) The type of PDF object that this dictionary describes; must be OCMD for an optional content membership dictionary.
OCGsdictionary or array(Optional) A dictionary or array of dictionaries specifying the optional content groups whose states determine the visibility of content controlled by this membership dictionary.

Note

Null values or references to deleted objects are ignored. If this entry is not present, is an empty array, or contains references only to null or deleted objects, the membership dictionary has no effect on the visibility of any content.

Pname(Optional) A name specifying the visibility policy for content belonging to this membership dictionary. Valid values are:
  • All On: visible only if all of the entries in OCGs are ON

  • AnyOn: visible if any of the entries in OCGs are ON

  • AnyOff: visible if any of the entries in OCGs are OFF

  • AllOff: visible only if all of the entries in OCGs are OFF

Default value: AnyOn
VEarray(Optional; PDF 1.6) An array specifying a visibility expression, used to compute visibility of content based on a set of optional content groups; see discussion below.


An optional content membership dictionary can express its visibility policy in two ways:

  • The P entry specifies a simple boolean expression indicating how the optional content groups specified by the OCGs entry determine the visibility of content controlled by the membership dictionary.

  • PDF 1.6 introduces the VE entry, which is a visibility expression that can specify an arbitrary boolean expression for computing the visibility of content from the states of optional content groups.

Note

Since the VE entry is more general, if it is present and supported by the PDF consumer software, it should be used in preference to OCGs and P. However, for compatibility purposes, PDF creators should use OCGs and P entries where possible. When the use of VE is necessary to express the intended behavior, OCGs and P entries should also be provided to approximate the behavior in older consumer software.


A visibility expression is an array with the following characteristics:

  • Its first element is a name representing a boolean operator (And, Or, or Not).

  • Subsequent elements are either optional content groups or other visibility expressions.

  • If the first element is Not, it should have only one subsequent element. If the first element is And or Or, it may have one or more subsequent elements.

  • In evaluating a visibility expression, the ON state of an optional content group is equated to the boolean value true; OFF is equated to false.

Examples 4.33 and 4.34 illustrate the use of visibility expressions.

Membership dictionaries are useful in cases such as these:

  • Some content may choose to be invisible when a group is ON and visible when it is OFF. In this case, the content would belong to a membership dictionary whose OCGs entry consists of a single optional content group and whose P entry is AnyOff or AllOff.

    Note

    It is legal to have an OCGs entry consisting of a single group and a P entry that is AnyOn or AllOn. However, in this case it is preferable to use an optional content group directly because it uses fewer objects.


  • Some content may belong to more than one group and must specify its policy when the groups are in conflicting states. In this case, the content would belong to a membership dictionary whose OCGs entry consists of an array of optional content groups and whose P entry specifies the visibility policy, as illustrated in Example 4.32 below. (Example 4.33 shows the equivalent policy using visibility expressions.)

Example 4.32.

<< /Type /OCMD                       % Content belonging to this optional content
           % membership dictionary is controlled by the states
   /OCGs [12 0 R 13 0 R 14 0 R]      % of three optional content groups.
   /P /AllOn                         % Content is visible only if the state of all three
>>                                   % groups is ON; otherwise it's hidden.


					  

Example 4.33.

<< /Type /OCMD
   /VE  [/And 12 0 R 13 0 R 14 0 R]  % Visibility expression equivalent to Example 4.32.
>>


					  

Example 4.34 shows a more complicated visibility expression based on five optional content groups, represented by objects 1 through 5. It is equivalent to

“OCG 1” OR (NOT “OCG 2”) OR (“OCG 3” AND “OCG 4” AND “OCG 5”)

Example 4.34.

<< /Type /OCMD
   /VE [/Or                          % Visibility expression: OR
    1 0 R                            % OCG 1
    [/Not 2 0 R]                     % NOT OCG 2
    [/And 3 0 R 4 0 R 5 0 R]         % OCG 3 AND OCG 4 AND OCG 5
   ]
>>

Intent

The Intent entry in Table 4.48 provides a way to distinguish between different intended uses of optional content. For example, many document design applications, such as CAD packages, offer layering features for collecting groups of graphics together and selectively hiding or viewing them for the convenience of the author. However, this layering may be different (at a finer granularity, for example) than would be useful to consumers of the document. Therefore, it is possible to specify different intents for optional content groups within a single document. A given application may decide to use only groups that are of a specific intent.

PDF 1.5 defines two intents: Design, which is intended to represent a document designer's structural organization of artwork, and View, which is intended for interactive use by document consumers. More intents may be added in future PDF versions; for compatibility with future versions, PDF consumers should allow unrecognized Intent values.

Configuration dictionaries (see “Optional Content Configuration Dictionaries” on page 347) also contain an Intent entry. If one or more of a group's intents is contained in the current configuration's set of intents, the group is used in determining visibility. If there is no match, the group has no effect on visibility.

Note

If the configuration's Intent is an empty array, no groups are used in determining visibility; therefore, all content is considered visible.


4.10.2. Making Graphical Content Optional

Graphical content in a PDF file can be made optional by specifying membership in an optional content group or optional content membership dictionary. Two primary mechanisms are available:

When a piece of optional content in a PDF file is determined to be hidden, the following occurs:

  • The content is not drawn.

  • Graphics state operations, such as setting the color, transformation matrix, and clipping, are still applied. In addition, graphics state side effects that arise from drawing operators are applied; in particular, the current text position is updated even for text wrapped in optional content. In other words, graphics state parameters that persist past the end of a marked-content section must be the same whether the optional content is visible or not. For example, hiding a section of optional content does not change the color of objects that do not belong to the same optional content group.

    Note

    This rule also applies to operators that set state that is not strictly graphics state; for example, BX and EX.


  • Objects such as form XObjects and annotations that are made optional may be skipped entirely, because their contents are encapsulated such that no changes to the graphics state (or other state) persist beyond the processing of their content stream.

Other features in PDF consuming applications, such as searching and editing, may be affected by the ability to selectively show or hide content. Features must choose whether to use the document's current state of optional content groups (and, correspondingly, the document's visible graphics) or to supply their own states of optional content groups to control the graphics they process. For example, tools to select and move annotations should honor the current on-screen visibility of annotations when performing cursor tracking and mouse-click processing. A full text search engine, however, may need to process all content in a document, regardless of its current visibility on-screen. Export filters might choose the current on-screen visibility, the full content, or present the user with a selection of OCGs to control visibility.

Note

All optional content-related PDF structures are unknown to, and hence ignored by, PDF 1.4 and earlier consumers, which therefore draw and otherwise process all content in the document.


Optional Content in Content Streams

Sections of content in a content stream (including a page's Contents stream, a form or pattern's content stream, glyph descriptions a Type 3 font as specified by its CharProcs entry, or an annotation's appearance) can be made optional by enclosing them between the marked-content operators BDC and EMC (see Section 10.5, “Marked Content”) with a marked-content tag of OC. In addition, a DP marked-content operator can be placed in a page's content stream to force a reference to an optional content group or groups on the page, even when the page has no current content in that layer.

The property list associated with the marked content specifies either an optional content group or optional content membership dictionary to which the content belongs. Because a group must be an indirect object and a membership dictionary contains references to indirect objects, the property list must be a named resource listed in the Properties subdictionary of the current resource dictionary (see Section 10.5.1, “Property Lists”), as shown in Examples 4.35 and 4.36.

Note

Although the marked-content tag must be OC, other applications of marked content are not precluded from using OC as a tag. The marked content is considered to be for optional content only if the tag is OC and the dictionary operand is a valid optional content group or optional content membership dictionary.


To avoid conflict with other features that used marked content (such as logical structure; see Section 10.6, “Logical Structure”), the following strategy is recommended:

  • Where content is to be tagged with optional content markers as well as other markers, the optional content markers should be nested inside the other marked content.

  • Where optional content and the other markers would overlap but there is not strict containment, the optional content should be broken up into two or more BDC/EMC sections, nesting the optional content sections inside the others as necessary. Breaking up optional content spans does not damage the nature of the visibility of the content, whereas the same guarantee cannot be made for all other uses of marked content.

Note

Any marked content tagged for optional content that is nested inside other marked content tagged for optional content is visible only if all the levels indicate visibility. In other words, if the settings that apply to the outer level indicate that the content should be hidden, the inner level is hidden regardless of its settings.


In the following example, the state of the Show Greeting optional content group directly controls the visibility of the text string “Hello” on the page. When the group is ON, the text is visible; when the group is OFF, the text is hidden.

Example 4.35.

% Within a content stream
...
/OC /oc1 BDC                         % Optional content follows
 BT
  /F1 1 Tf
  12 0 0 12 100 600 Tm
  (Hello) Tj
 ET
EMC                                 % End of optional content
...
<<                                   % In the resources dictionary
 /Properties << /oc1 5 0 R >>        % This dictionary maps the name oc1 to an  ...                       % optional content group (object 5)
>>

5 0 obj                              % The OCG controlling the visibility
<<                                   % of the text.
   /Type /OCG
   /Name (Show Greeting)
>>
endobj


					  

The example above shows one piece of content associated with one optional content group. There are other possibilities:

  • More than one section of content can refer to the same group or membership dictionary, in which case the visibility of both sections is always the same.

  • Equivalently, although less space-efficient, different sections can have separate membership dictionaries with the same OCGs and P entries. The sections will have identical visibility behavior.

  • Two sections of content can belong to membership dictionaries that refer to the same group(s) but with different P settings. For example, if one section has no P entry, and the other has a P entry of AllOff, the visibility of the two sections of content are opposite. That is, the first section is visible when the second is hidden, and vice versa.

The following example demonstrates both the direct use of optional content groups and the indirect use of groups through a membership dictionary. The content (a black rectangle frame) is drawn if either of the images controlled by the groups named Image A or Image B is shown. If both groups are hidden, the rectangle frame is hidden.

Example 4.36.

% Within a content stream
...
/OC /OC2 BDC                         % Draws a black rectangle frame
 0 g
 4 w
 100 100 412 592 re s
EMC
/OC /OC3 BDC                         % Draws an image XObject
    q
    412 0 0 592 100 100 cm
    /Im3 Do
    Q
EMC
/OC /OC4 BDC                         % Draws an image XObject
   q
   412 0 0?592 100 100 cm
   /Im4 Do
   Q
EMC
...
<<                                   % The resource dictionary
  /Properties << /OC2 20 0 R /OC3 30 0 R /OC4 40 0 R >>
  /XObject << /lm3 50 0 R /lm4 /60 0 R >>
>>

20 0 obj
<<                                   % Optional content membership dictionary
   /Type /OCMD
   /OCGs [30 0 R 40 0 R]
   /P /AnyOn
>>
endobj
30 0 obj                             % Optional content group "Image A"
<<
   /Type /OCG
   /Name (Image A)
>>
endobj
40 0 obj                             % Optional content group "Image B"
<<
   /Type /OCG
   /Name (Image B)
>>
endobj


					  

Optional Content in XObjects and Annotations

In addition to marked content within content streams, form XObjects and image XObjects (see Section 4.7, “External Objects”) and annotations (see Section 8.4, “Annotations”) may contain an OC entry, which is an optional content group or an optional content membership dictionary.

A form or image XObject's visibility is determined by the state of the group or those of the groups referenced by the membership dictionary in conjunction with its P (or VE) entry, along with the current visibility state in the context in which the XObject is invoked (that is, whether objects are visible in the contents stream at the place where the Do operation occurred).

Annotations have various flags controlling on-screen and print visibility (see Section 8.4.2, “Annotation Flags”). If an annotation contains an OC entry, it is visible for screen or print only if the flags have the appropriate settings and the group or membership dictionary indicates it is visible.

4.10.3. Configuring Optional Content

A PDF document containing optional content can specify the default states for the optional content groups in the document and indicate which external factors should be used to alter the states. The following sections describe the PDF structures that are used to specify this information.

Optional Content Properties Dictionary

The optional OCProperties entry in the document catalog (see Section 3.6.1, “Document Catalog”) holds the optional content properties dictionary, which contains a list of all the optional content groups in the document, as well as information about the default and alternate configurations for optional content. This dictionary is required if the file contains any optional content; if it is missing, a PDF consumer should ignore any optional content structures in the document.

This dictionary contains the following entries:

Table 4.50. Entries in the optional content properties dictionary
KEYTYPEVALUE
OCGsarray(Required) An array of indirect references to all the optional content groups in the document (see Section 4.10.1, “Optional Content Groups”), in any order. Every optional content group must be included in this array.
Ddictionary(Required) The default viewing optional content configuration dictionary (see “Optional Content Configuration Dictionaries,” below).
Configsarray(Optional) An array of alternate optional content configuration dictionaries (see “Optional Content Configuration Dictionaries,” below) for PDF processing applications or features.


Optional Content Configuration Dictionaries

The D and Configs entries in Table 4.50 are configuration dictionaries, which represent different presentations of a document's optional content groups for use by PDF processing applications or features. The D configuration dictionary specifies the initial state of the optional content groups when a document is first opened. Configs lists other configurations that may be used under particular circumstances. The entries in a configuration dictionary are shown in Table 4.51.

Table 4.51. Entries in an optional content configuration dictionary
KEYTYPEVALUE
Nametext string(Optional) A name for the configuration, suitable for presentation in a user interface.
Creatortext string(Optional) Name of the application or feature that created this configuration dictionary.
BaseStatename(Optional) Used to initialize the states of all the optional content groups in a document when this configuration is applied. The value of this entry must be one of the following names:
  • ON: The states of all groups are turned ON.

  • OFF: The states of all groups are turned OFF.

  • Unchanged: The states of all groups are left unchanged.

After this initialization, the contents of the ON and OFF arrays are processed, overriding the state of the groups included in the arrays.

Default value: ON.

Note

If BaseState is present in the document's default configuration dictionary, its value must be ON.

ONarray(Optional) An array of optional content groups whose state should be set to ON when this configuration is applied.

Note

If the BaseState entry is ON, this entry is redundant.

OFFarray(Optional) An array of optional content groups whose state should be set to OFF when this configuration is applied.

Note

If the BaseState entry is OFF, this entry is redundant.

Intentname or array(Optional) A single intent name or an array containing any combination of names. It is used to determine which optional content groups' states to consider and ignore in calculating the visibility of content (see “Intent” on page 340). PDF 1.5 defines two intent names, View and Design. Future versions may define others. In addition, the name All indicates the set of all intents, including those not yet defined. Default value: View. The value must be View for the document's default configuration.
ASarray(Optional) An array of usage application dictionaries (see Table 4.53) specifying which usage dictionary categories (see Table 4.52) should be consulted by viewer applications to automatically set the states of optional content groups based on external factors, such as the current system language or viewing magnification, and when they should be applied.
Orderarray(Optional) An array specifying the recommended order for presentation of optional content groups in a user interface. The array elements may include the following objects:
  • Optional content group dictionaries, whose Name entry is to be displayed in the user interface.

  • Arrays of optional content groups to allow nesting as in a tree or outline structure. Each nested array may optionally have as its first element a text string to be used as a non-selectable label in the user interface.

Note

Text labels in nested arrays should be used to present collections of related optional content groups, and not to communicate actual nesting of content inside multiple layers of groups (see Example 4.37). To reflect actual nesting of groups in the content, such as for layers with sublayers, nested arrays of groups without a text label should be used (see Example 4.38).

An empty array [] explicitly specifies that no groups should be presented.

In the default configuration dictionary, the default value is an empty array; in other configuration dictionaries, the default is the Order value from the default configuration dictionary.

Note

Any groups not listed in this array should not be presented in any user interface that uses the configuration.

ListModename(Optional) A name specifying which optional content groups in the Order array should be displayed to the user. Valid values are:
  • AllPages: Display all groups in the Order array.

  • VisiblePages: Display only those groups in the Order array that are referenced by one or more visible pages.

Default value: AllPages.
RBGroupsarray(Optional) An array consisting of one or more arrays, each of which represents a collection of optional content groups whose states are intended to follow a radio button paradigm. That is, the state of at most one optional content group in each array should be ON at a time. If one group is turned ON, all others must be turned OFF. However, turning a group from ON to OFF does not force any other group to be turned ON.

An empty array [] explicitly indicates that no such collections exist.

In the default configuration dictionary, the default value is an empty array; in other configuration dictionaries, the default is the RBGroups value from the default configuration dictionary.
Lockedarray(Optional; PDF 1.6) An array of optional content groups that should be locked when this configuration is applied. The state of a locked group cannot be changed through the user interface of a viewer application. Producers can use this entry to prevent the visibility of content that depends on these groups from being changed by users. Default value: an empty array.

Note

This entry does not prevent the states of optional content groups from being changed by means other than the user interface, such as JavaScript or items in the AS entry of a configuration dictionary.


Examples 4.37 and 4.38 illustrates the use of the Order entry to control the display of groups in a user interface.

Example 4.37.

Given the following PDF objects:

   1 0 obj <</Type /OCG /Name (Skin)>> endobj      % Optional content groups
   2 0 obj <</Type /OCG /Name (Bones)>> endobj
   3 0 obj <</Type /OCG /Name (Bark)>> endobj
   4 0 obj <</Type /OCG /Name (Wood)>> endobj

   5 0 obj                                         % Configuration dictionary
     << /Order [[(Frog Anatomy) 1 0 R 2 0 R] [(Tree Anatomy) 3 0 R 4 0 R] ] >>


					  

A PDF viewer should display the optional content groups as follows:

Frog Anatomy

Skin

Bones

Tree Anatomy

Bark

Wood

Example 4.38.

Given the following PDF objects:
                                     % Page contents
   /OC /L1 BDC                       % Layer 1
      /OC /L1a BDC                   % Sublayer A of layer 1
         0 0 100 100 re f
      EMC
     /OC /L1b BDC                    % Sublayer B of layer 1
        0 100 100 100 re f
     EMC
   EMC
   ...
   << /L1 1 0 R                      % Resource names
      /L1a 2 0 R
      /L1b 3 0 R
   >>
   ...                                %Optional content groups
   1 0 obj <</Type /OCG /Name (Layer 1)>> endobj
   2 0 obj <</Type /OCG /Name (Sublayer A)>> endobj
   3 0 obj <</Type /OCG /Name (Sublayer B)>> endobj
   ...
   4 0 obj                           % Configuration dictionary
     << /Order [1 0 R [2 0 R 3 0 R]] >>



					  

A PDF viewer should display the OCGs as follows:

Layer 1

Sublayer A

Sublayer B

The AS entry is an auto state array consisting of one or more usage application dictionaries that specify how viewer applications should automatically set the state of optional content groups based on external factors, as discussed in the following section.

Usage and Usage Application Dictionaries

Optional content groups are typically constructed to control the visibility of graphic objects that are related in some way. Objects can be related in several ways; for example, a group may contain content in a particular language or content suitable for viewing at a particular magnification.

An optional content group's usage dictionary (the value of the Usage entry in an optional content group dictionary; see Table 4.48) contains information describing the nature of the content controlled by the group. This dictionary can contain any combination of the entries shown in Table 4.52.

Table 4.52. Entries in an optional content usage dictionary
KEYTYPEVALUE
CreatorInfodictionary(Optional) A dictionary used by the creating application to store application-specific data associated with this optional content group. It contains two required entries:
  • Creator : A text string specifying the application that created the group.

  • Subtype: A name defining the type of content controlled by the group. Suggested values include but are not limited to Artwork, for graphic-design or publishing applications, and Technical, for technical designs such as building plans or schematics.

Additional entries may be included to present information relevant to the creating application or related applications.

Note

Groups whose Intent entry contains Design typically include a CreatorInfo entry.

Languagedictionary(Optional) A dictionary specifying the language of the content controlled by this optional content group. It has two entries:
  • Lang (required): A language string (see Section 10.8.1, “Natural Language Specification”) that specifies a language and possibly a locale (for example, es-MX represents Mexican Spanish).

  • Preferred (optional): A name whose values may be ON or OFF. Default value: OFF. It is used by viewer applications when there is a partial match but no exact match between the system language and the language strings in all usage dictionaries. See “Usage and Usage Application Dictionaries” on page 352 for more information.

Exportdictionary(Optional) A dictionary containing one entry, ExportState, a name whose value may be ON or OFF. This value indicates the recommended state for content in this group when the document (or part of it) is saved by a viewer application to a format that does not support optional content (for example, an earlier version of PDF or a raster image format).
Zoomdictionary(Optional) A dictionary specifying a range of magnifications at which the content in this optional content group is best viewed. It may contain one or both of the following entries:
  • min: The minimum recommended magnification factor at which the group should be ON. Default value: 0.

  • max: The magnification factor below which the group should be ON. Default value: infinity.

Printdictionary(Optional) A dictionary specifying that the content in this group is intended for use in printing. It contains the following optional entries:
  • Subtype: A name object specifying the kind of content controlled by the group; for example, Trapping, PrintersMarks and Watermark.

  • PrintState: A name that may be ON or OFF, indicating that the group should be set to that state when the document is printed from a viewer application.

Viewdictionary(Optional) A dictionary that has a single entry, ViewState, a name that may have a value of ON or OFF, indicating that the group should be set to that state when the document is opened in a viewer application.
Userdictionary(Optional) A dictionary specifying one or more users for whom this optional content group is primarily intended. Each dictionary has two required entries:
  • TYPE: A name object that can be Ind (individual), Ttl (title), or Org (organization).

  • Name: A text string or array of text strings representing the name(s) of the individual, position or organization.

PageElementdictionary(Optional) A dictionary declaring that the group contains a pagination artifact. It contains one entry, Subtype, whose value is a name that can be HF (header/footer), FG (foreground image or graphic), BG (background image or graphic), or L (logo).


While the data in the usage dictionary can be viewed as information for a document user to examine, it can also be used by viewer applications to automatically manipulate the state of optional content groups based on external factors such as current system language settings or zoom level. Document authors can use usage application dictionaries to specify which entries in the usage dictionary should be consulted to automatically set the state of optional content groups based on such factors. Usage application dictionaries are listed in the AS entry in an optional content configuration dictionary (see Table 4.51). If no AS entry is present, states are not automatically adjusted based on usage information.

A usage application dictionary specifies the rules for which usage entries should be used by viewer applications to automatically manipulate the state of optional content groups, which groups should be affected, and under which circumstances. Table 4.53 shows the entries in a usage application dictionary.

Note

Usage application dictionaries are only intended for use by interactive viewer applications, not for applications that use PDF as final form output (see “Determining the State of Optional Content Groups” on page 357 for more information).


Table 4.53. Entries in a usage application dictionary
KEYTYPEVALUE
Eventname(Required) A name defining the situation in which this usage application dictionary should be used. May be View, Print, or Export.
OCGsarray(Optional) An array listing the optional content groups that should have their states automatically managed based on information in their usage dictionary (see “Usage and Usage Application Dictionaries” on page 352). Default value: an empty array, indicating that no groups are affected.
Categoryarray(Required) An array of names, each of which corresponds to a usage dictionary entry (see Table 4.52). When managing the states of the optional content groups in the OCGs array, each of the corresponding categories in the group's usage dictionary should be considered.


The Event entry specifies whether the usage settings should be applied during viewing, printing, or exporting the document. The OCGs entry specifies the set of optional content groups to which usage settings should be applied. For each of the groups in OCGs, the entries in its usage dictionary (see Table 4.52) specified by Category are examined to yield a recommended state for the group. If all the entries yield a recommended state of ON, the group's state is set to ON; otherwise, its state is set to OFF.

The entries in the usage dictionary are used as follows:

  • View: The recommended state is the value of the ViewState entry. This entry allows a document to contain content that is relevant only when the document is viewed interactively, such as instructions for how to interact with the document.

  • Print: The recommended state is the value of the PrintState entry. If PrintState is not present, the state of the optional content group is left unchanged.

  • Export: The recommended state is the value of the ExportState entry.

  • Zoom: If the current magnification level of the document is greater than or equal to min and less than max, an ON state is recommended; otherwise, OFF is recommended.

  • User: The Name entry specifies a name or names to match with the user's identification. The TYPE entry determines how the Name entry is interpreted (name, title, or organization). If there is an exact match, an ON state is recommended; otherwise OFF is recommended.

  • Language: This category allows the selection of content based on the language and locale of the application. If an exact match to the language and locale is found among the Lang entries of the optional content groups in the usage application dictionary's OCGs list, all groups that have exact matches receive an ON recommendation. If no exact match is found, but a partial match is found (that is, the language matches but not the locale), all partially matching groups that have Preferred entries with a value of ON receive an ON recommendation. All other groups receive an OFF recommendation.

Example 4.39 shows the use of an auto state array with usage application dictionaries. The AS entry in the default configuration dictionary is an array of three usage application dictionaries, one for each of the Event values View, Print, and Export.

Note

While this case is typical, there is no restriction on multiple entries with the same value of Event, which allows documents with incompatible usage application dictionaries to be combined into larger documents and have their behavior preserved. If a given optional content group appears in more than one OCGs array, its state is ON only if all categories in all the usage application dictionaries it appears in recommend a state of ON.


Example 4.39.

/OCProperties                        % OCProperties dictionary in document catalog
  << /OCGs [1 0 R 2 0 R 3 0 R 4 0 R]
     /D  << /BaseState /OFF          % The default configuration
            /ON [1 0 R]
            /AS [                    % Auto state array of usage application dictionaries
               << /Event /View /Category [/Zoom] /OCGs [1 0 R 2 0 R 3 0 R 4 0 R] >>
               << /Event /Print /Category [/Print] /OCGs [4 0 R] >>
               << /Event /Export /Category [/Export] /OCGs [3 0 R 4 0 R] >>
               ]
         >>
    >>
...

1 0 obj
   << /Type /OCG
      /Name (20000 foot view)
      /Usage << /Zoom << /max 1.0 >> >>
   >>
endobj
2 0 obj
    << /Type /OCG
       /Name (10000 foot view)
       /Usage << /Zoom << /min 1.0 /max 2.0 >> >>
>>
endobj
3 0 obj
   << /Type /OCG
   /Name (1000 foot view)
   /Usage << /Zoom << /min 2.0 /max 20.0 >>
             /Export << /ExportState /OFF >> >>
   >>
endobj
4 0 obj
   << /Type /OCG
  /Name (Copyright notice)
  /Usage << /Print << /PrintState /ON >>
           /Export << /ExportState /ON>> >>
   >>
endobj


					  

In the example, the usage application dictionary with event type View specifies that all optional content groups are to have their states managed based on zoom level when viewing. Three groups (objects 1, 2, and 3) contain Zoom usage information. Object 4 has none; therefore, it is not affected by zoom level changes. Object 3 receives an OFF recommendation when exporting. When printing or exporting, object 4 receives an ON recommendation.

Determining the State of Optional Content Groups

This section summarizes the rules by which applications make use of the configuration and usage application dictionaries to set the state of optional content groups. For purposes of this discussion, it is useful to distinguish the following types of applications:

  • Viewer applications, such as Acrobat, which allow users to interact with the document in various ways.

  • Design applications, which offer layering features for collecting groups of graphics together and selectively hiding or viewing them.

Note

The following rules are not meant to apply to design applications; they may manage their states in an entirely different manner if they choose.


  • Aggregating applications, which import PDF files as graphics.

  • Printing applications, which print PDF files.

When a document is first opened, its optional content groups are assigned a state based on the D (default) configuration dictionary in the OCProperties dictionary:

1.
The value of BaseState is applied to all the groups.

2.
The groups listed in either the ON or OFF array (depending on which one is opposite to BaseState) have their states adjusted.

This state is the recommended state for printing and aggregating applications, which should not apply the changes based on usage application dictionaries described below. However, for more advanced functionality, they may provide user control for manipulating the individual states of optional content groups.

Note

Viewer applications should also provide users with an option to view documents in this state (that is, to disable the automatic adjustments discussed below). This option permits an accurate preview of the content as it will appear when placed into an aggregating application or sent to a stand-alone printing system.


The remaining discussion in this section applies only to viewer applications. Such applications should examine the AS array for usage application dictionaries that have an Event of type View. For each one found, the groups listed in its OCGs array should be adjusted as described in “Usage and Usage Application Dictionaries” on page 352.

Subsequently, the document is ready for interactive viewing by a user. Whenever there is a change to a factor that the usage application dictionaries with event type View depend on (such as zoom level), the corresponding dictionaries should be reapplied.

The user may manipulate optional content group states manually or by triggering SetOCGState actions (see “Set-OCG-State Actions” on page 629) by, for example, clicking links or bookmarks. Manual changes override the states that were set automatically. The states of these groups remain overridden and are not readjusted based on usage application dictionaries with event type View as long as the document is open (or until the user reverts the document to its original state).

When a document is printed by a viewer application, usage application dictionaries with an event type Print are applied over the current states of optional content groups. These changes persist only for the duration of the print operation; then all groups revert to their prior states.

Similarly, when a document is exported to an earlier version of PDF or other format that does not support optional content, usage application dictionaries with an event type Export are applied over the current states of optional content groups. Changes persist only for the duration of the export operation; then all groups revert to their prior states.

Note

Although the event types Print and Export have identically named counterparts that are usage categories, the corresponding usage application dictionaries are permitted to specify that other categories may be applied.


  • Creative Edge
  • Create BookmarkCreate Bookmark
  • Create Note or TagCreate Note or Tag
  • PrintPrint