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
Get Developing with PDF now with the O’Reilly learning platform.
O’Reilly members experience books, live events, courses curated by job role, and more from O’Reilly and nearly 200 top publishers.
