Chapter 10. Optional Content
Optional content is a feature of PDF that allows specific graphic objects and/or annotations to be visible only when a certain set of criteria is met. These criteria can be specified by the author of the content—for example, that this content should only appear on the screen and never print—or can be specified by the user via some interaction with the viewer. This feature is useful for a variety of things, ranging from CAD drawings to maps to multilanguage documents and more.
Optional Content Groups
The basic building block for defining optional content is the optional content group (OCG), which is a dictionary that consists of the required Type (which is always OCG), the required Name of the group (which may be displayed by a viewer), and the Usage key, which declares how the group is to be used.
Content State
A group is assigned a state, which is either ON or OFF. States may be set automatically by the viewer (based on the Usage), programmatically, or through the viewer’s user interface. Content belonging to a group is visible when the group is ON and invisible when it is OFF.
Note
Content may belong to multiple groups, which may have conflicting states.
Usage
Content is usually grouped together because it shares some common feature. It may be the language of the content, or that it is only for use on screen. The optional content usage dictionary, which is the value of the Usage key in the optional content group dictionary, declares the commonality (see Example 10-1). This usage information is then used by the PDF viewer to determine whether to evaluate the group’s state based on external factors in conjunction with the value of the AS key in the optional content configuration dictionary (see Optional Content Configuration).
A Usage dictionary may contain any number of keys, if the group has multiple things in common. The most commonly used keys are the following:
-
Export -
The value of this key is a dictionary containing a single key,
ExportState, whose value (of type Name) is eitherONorOFF, declaring whether this content should be exported by the viewer into a nonoptional-content-aware format (such as raster images or Postscript). -
Print -
The key’s value is a dictionary containing a single key,
PrintState, whose value (of type Name) is eitherONorOFFdeclaring whether this content should be printed. -
View -
The value of this key is a dictionary containing a single key,
ViewState, whose value (of type Name) is eitherONorOFF, declaring whether this content should be displayed on the screen (or whatever the default “view” of the viewer is). -
Zoom -
The dictionary value of this key contains either the
minkey, themaxkey, or both. The values of these keys, if present, specify the minimum and maximum zoom/magnification (in percentage) at which the group should be consideredON. -
Language -
The value of this key is a dictionary that declares the natural language of the content in the group via its
Langkey.
Note
Although Language is a great way to group content, it is not automatically detected and assigned a group state by common viewers.
10 0 obj
<<
/Name (Watermark)
/Type OCG
/Usage <<
/Print << /PrintState /ON >>
/View << /ViewState /OFF >>
>>
>>
endobj
11 0 obj
<<
/Name (Do Not Print Or Export)
/Type OCG
/Usage <<
/Export << /ExportState /OFF >>
/Print << /PrintState /OFF >>
/View << /ViewState /ON >>
>>
>>
endobj
12 0 obj
<<
/Name (zoom = {0% 100%})
/Type OCG
/Usage <<
/Zoom <<
/max 1
>>
>>
>>
endobj
13 0 obj
<<
/Name (zoom = {100% 200%})
/Type OCG
/Usage <<
/Zoom <<
/max 2
/min 1
>>
>>
>>
endobjOptional Content Membership
While most content only needs to be a member of a single optional content group and its associated usage dictionary, sometimes content may belong to multiple groups, and those groups may have conflicting states. In order to provide the viewer with the necessary information to resolve such potential conflicts, this type of content should be associated with an optional content membership dictionary (OCMD) instead of an optional content group.
An OCMD is, at its heart, a list of the OCGs that specify the various potential visibility states along with either a visibility policy or a visibility expression that describes how to determine the state.
Visibility Policies
A visibility policy is the simplest way to specify how the various OCG states will be resolved (see Example 10-2). This is the preferred method and should be used in favor of visibility expressions if possible.
The policy is specified by a single name object with one of four possible values. This value is that of the P key in the OCMD. The available policy values are the following:
-
AllOn -
Visible only if all of the entries in the OCGs are
ON -
AnyOn -
Visible if any of the entries in the OCGs are
ON -
AnyOff -
Visible if any of the entries in the OCGs are
OFF -
AllOff -
Visible only if all of the entries in the OCGs are
OFF
<<
/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.
>>Visibility Expressions
A visibility expression, as the name implies, allows for more complex Boolean expressions in defining how the various OCG states should be resolved. When a viewer evaluates a visibility expression, if the expression evaluates to true, then the optional content group is in the ON state. If it evaluates to false, then the state is OFF.
The expression is an array whose first element is a name representing a Boolean operator (And, Or, or Not), while subsequent elements are either optional content groups or other visibility expressions. If the first element of the expression is Not, then there is only one subsequent element; otherwise (for And or Or), it can have one or more subsequent elements.
Note
It might seem strange that an And or Or expression could have only a single associated element, but that element can itself be a visibility expression instead of a reference to an OCG.
Example 10-3 shows what the visibility policy would look like as a visibility expression.
Example 10-4 shows a more complex expression that relates five different groups, represented by the objects 1 through 5 in the PDF, named OCG 1 through OCG 5, respectively. If written out, the example would read as "OCG 1"; OR (NOT "OCG 2") OR ("OCG 3" AND "OCG 4" AND "OCG 5")“.
Optional Content Configuration
An optional content configuration dictionary (OCCD) represents a preset configuration of the state for one or more groups. A PDF (that has OCGs) may contain several OCCDs, but must include at least one. The reason for the one is that when a document is first opened by a conforming reader, the groups’ states are initialized based on the document’s default OCCD.
Note
The default OCCD is specified as the value of the D key in the optional content properties dictionary, which is itself referenced from the document catalog dictionary (see Optional Content Membership and The Catalog Dictionary).
While all of the keys in the OCCD are optional, it is most common to have at least some combination of BaseState and ON or OFF present. BaseState is a name (either ON, OFF, or Unchanged) that represents the state of all groups to start with. This “base state” can then be adjusted through the use of the ON and/or OFF keys, which list specific OCGs whose state to set to ON or OFF. It is also common to give the OCCD a name via the Name key. Example 10-5 shows a simple optional content configuration dictionary.
2 0 obj
<<
/Name (Example)
/BaseState /ON % turn them all on
/OFF [ 1 0 R ] % except this one
>>
endobjOrder Key
In some cases, the choices about which content should be visible and which should not are made by the author of the content and remain stable throughout the content’s life. However, most content that is described with optional content groups is done so that a user can manually change the visibility of the content. For example, with a complex architectural or electrical diagram, the user may need to turn on or off various groups of graphic elements in order to see just the important ones.
To request that a PDF viewer present a list of user-configurable optional content to the user, the Order key is used. For a simple list of groups like the one in Figure 10-1, the value of the key is a one-dimensional array of OCGs.
% Present 6 OCGs in the list of OCGs
<<
/Order[
40 0 R 42 0 R 38 0 R 32 0 R 36 0 R 34 0 R
]
>>It is also possible to group the OCGs in various hierarchical groupings, in a way that might be helpful to the user or that just generally represents logical groupings of the content. For example, if there is a specialized subcategory of elements, they can be collected together.
The name of the group can be taken from the OCG that immediately precedes the subarray of elements, or it can be specified by a text string in the subarray. Figure 10-2 shows a few examples of hierarchical groupings of OCGs.
% Using the Name of an OCG for the name of the group
<<
/Order[
24 0 R 37 0 R 34 0 R 25 0 R
30 0 R [
32 0 R 31 0 R
]
22 0 R [
27 0 R 28 0 R 29 0 R 36 0 R 40 0 R 23 0 R 26 0 R 35 0 R 41
0 R 43 0 R 45 0 R 44 0 R 46 0 R 42 0 R 38 0 R 33 0 R 39 0 R
]
]
>>
% Using a text string for the name of the group
<<
/Order [
[(Group 1) 1 0 R 2 0 R]
[(Group 2) 3 0 R 4 0 R]
]
>>RBGroups
The OCGs that are listed in the array value of the Order key are simply presented as a (possibly hierarchical) list. Users can turn them on and off in any combination that they wish. For many use cases, such as architectural or electronical diagrams, this works well. If you were using optional content groups to allow the user to select a language for the content of the document, for example, it would not make sense to have text in multiple languages showing at the same time (with one version on top of another!). To apply the logic that only one of a group of items can be “on” at a time in the user interface of a view, the RBGroups key is used.
Note
The RB in RBGroups stands for radio button.
The value of the RBGroups key is an array of one or more arrays, where each one represents the collection of OCGs whose states should be grouped together using the radio button metaphor—just one at a time. Figure 10-3 illustrates the use of RBGroups.
<<
/RBGroups [
[ 55 0 R 57 0 R 59 0 R 61 0 R 63 0 R ]
]
>>AS (Automatic State)
The automatic state (AS) key in the OCCD declares which of the available usage values are to be checked by the PDF viewer and used to automatically adjust the state of various OCGs as illustrated in Example 10-6. The value of the AS key is an array of usage application dictionaries, each one stating which OCGs are to be checked for which type of event (or situation) and the category of usage.
Optional Content Properties
Even after all the OCGs, OCMDs, and OOCDs are added to the PDF, there is still one more dictionary that is required. This is the optional content properties dictionary; it is the value of the OCProperties key in the document catalog dictionary. Without this, a viewer will not be aware that there is any optional content in the PDF.
There are two required keys in the properties dictionary:
-
OCGs - This is an array of every single OCG in the PDF, regardless of how it is used, listed in any order. If it is not listed in this array, then the viewer can choose to ignore it when it is encountered later.
-
D - The value of this key is the default optional content configuration dictionary for the PDF.
Optionally, if the PDF contains multiple OCCDs, they can be listed as the value of the Configs key in this dictionary. A sample optional content properties dictionary is shown in Example 10-7.
Marking Content as Optional
So far in this chapter we’ve seen how to create optional content groups and all of the infrastructure for making them available to a PDF viewer and its users. However, a PDF containing all of the previously described objects is still missing one key component—how are the content elements connected to the optional content groups or optional content membership dictionaries that may affect their visibility? Any content whose visibility will be affected by a given optional content group is said to belong to (or have membership in) that group.
Optional Content in Content Streams
To specify which specific content elements of a content stream are to be associated with an optional content group or optional content membership dictionary, they need to be enclosed between the marked content operators BDC and EMC. The BDC operator will use the tag of OC, and the associated property list specifies the OCG or OCMD to which the content belongs. Since the reference to the group is via its indirect object, the property list must used the named resource form for property lists.
Example 10-8 shows a simple example of how to mark content in a stream as optional.
% (partial/incomplete) page object
18 0 obj
<<
/Type /Page
/Contents 19 0 obj
/CropBox [ 0 0 612 792 ]
/MediaBox [ 0 0 612 792 ]
/Resources <<
/Properties << /MC0 20 0 R >>
>>
>>
endobj
% (partial/incomplete) content stream object
19 0 obj
<<>>
stream
/OC /MC0 BDC % this group is part of the MC0 OCG
0 g
1 i
BT
/T1_0 1 Tf
12 0 0 12 234 364 Tm
(This page intentionally blank 00)Tj
ET
EMC
endstream
endobj
% optional content group
20 0 obj
<<
/Intent /View
/Name (Alternate Content)
/Type /OCG
>>
endobjContent can be associated with one or more OCGs and/or OCMDs, and the content of a group need not be contiguous in the content stream, or even in the same content stream (see Figure 10-4). This makes optional content extremely flexible for many purposes (see Figure 10-5).
% Content stream with each color in a separate OCG /OC /MC0 BDC % Red rectangles 1 0 0 rg 279 159.356 -211 86 re f EMC /OC /MC1 BDC % Green rectangles 0 1 0 rg 755 160.356 -211 86 re f EMC /OC /MC2 BDC % Blue rectangles 0 0 1 rg 519 159.356 -211 86 re f EMC /OC /MC0 BDC % Red rectangles 1 0 0 rg 279 62.356 -211 86 re f EMC /OC /MC1 BDC % Green rectangles 0 1 0 rg 755 63.356 -211 86 re f EMC /OC /MC2 BDC % Blue rectangles 0 0 1 rg 519 62.356 -211 86 re f EMC
% Content stream
% This content doesn't belong to any group
BT
0 0 0 rg
/T1_0 1 Tf
27 0 0 27 314.2861 142.3242 Tm
[(S)-6(ome R)-4(ec)-12.9(tangles)]TJ
ET
/OC /MC3 BDC % everything here is part of MC3
/OC /MC0 BDC % this belongs to MC3 *AND* MC0
1 0 0 rg
279 159.356 -211 86 re
f
EMC
/OC /MC1 BDC % this belongs to MC3 *AND* MC1
0 1 0 rg
755 160.356 -211 86 re
f
EMC
/OC /MC2 BDC % this belongs to MC3 *AND* MC2
0 0 1 rg
519 159.356 -211 86 re
f
EMC
EMCOptional Content for Form XObjects
For form XObjects or image XObjects that are used only in a single content stream, simply marking up the invoking stream can be done easily. However, when such objects are used in multiple content streams and will be consistently in the same group(s), it is easier to take advantage of the OC key in the XObject dictionary. The value of the OC key in the XObject dictionary is an indirect reference to the optional content group or optional content membership dictionary to which it belongs. Example 10-9 illustrates this usage.
35 0 obj
<<
/FormType 1
/Subtype/Form
/Length 91
/Matrix[1.0 0.0 0.0 1.0 0.0 0.0]
/BBox[0.0 -31.7999 79.9918 0.143921]
/Resources<</Font<</TT0 32 0 R>>>>
/OC 37 0 R
>>
stream
0 0.75 1 rg
0 i
BT
/TT0 1 Tf
0 Tc 0 Tw 0 Ts 100 Tz 0 Tr
24 0 0 24 0 -24 Tm
(DRAFT)Tj
ET
endstream
endobjIf a form XObject or image XObject has an OC key and the same XObject is also part of an optional content group or optional content membership dictionary configured inside of a content stream, the combination of the two states (treated as an AND) will be used to determine the visibility of the object. For example, if the OCG value of the OC key evaluates to ON but the content stream evaluates to OFF, then the state for the object will be OFF.
It is also possible to have individual content of a form XObject be part of an OCG or OCMD. In that instance, the visibility of the XObject will be evaluated, and if its state is ON, the specific graphics objects will be evaluated.
Optional Content for Annotations
Although the individual content elements of the appearance stream of an annotation can be marked up and associated with specific optional content groups or optional content membership dictionaries, it is more common to simply associate the entire annotation. This not only hides the annotation from view, but also ensures that a PDF viewer will not provide any user interaction with the element. This is quite useful for interactive forms, as a way to hide or show elements based on other criteria (see Chapter 7).
As with form or image XObjects, the value of the OC key in the annotation dictionary is an indirect reference to the optional content group or optional content membership dictionary to which it belongs. Example 10-10 demonstrates.