class HexaPDF:: Type:: OptionalContentGroup
Parent | HexaPDF::Dictionary |
---|
Represents an optional content group (OCG).
An optional content group represents graphics that can be made visible or invisible dynamically by the PDF processor. These graphics may reside in any content stream and don’t need to be consecutive with respect to the drawing order.
Most PDF viewers call this feature “layers” since it is often used to show/hide parts of drawings or maps.
Intent and Usage¶ ↑
An OCG may be assigned an intent (defaults to :View) and usage information. This allows one to specify in more detail how an OCG may be used (e.g. to only show the content when a certain zoom level is active).
See: PDF2.0 s8.11.2
Field Definitions
Name | Type/Allowed Values | Required | Default Value |
---|---|---|---|
Type | Symbol | true | :OCG |
Name | String | true | nil |
Intent | Symbol or HexaPDF::PDFArray or Array | false | :View |
Usage | HexaPDF::Type::OptionalContentGroup::OptionalContentUsage or Hash | false | nil |
Public Instance Methods
Adds the OCG to the PDF processor’s user interface in the default configuration (see OptionalContentProperties#default_configuration
), either at the top-level or under the given hierarchical path
but always as the last item.
Applies the given intent (:View, :Design or a custom intent) to the OCG.
Returns the creator info dictionary (see OptionalContentUsage::CreatorInfo
) or nil
if no argument is given. Otherwise sets the creator info using the given values.
The creator info dictionary is used to store application-specific data. The string creator
specifies the application that created the group and the symbol subtype
defines the type of content controlled by the OCG (for example :Artwork for graphic design applications or :Technical for technical designs such as plans).
Returns the export state if no argument is given. Otherwise sets the export state using the given value.
The export state indicates the recommended state of the content when the PDF document is saved to a format that does not support optional content (e.g. a raster image format). If state
is true
, the content controlled by the OCG will be visible.
Returns the user dictionary (see OptionalContentUsage::User
) or nil
if no argument is given. Otherwise sets the user information using the given values.
The information specifies one or more users for whom this OCG is primarily intended. The symbol type
can either be :Ind (individual), :Ttl (title or position) or :Org (organisation). The argument name
can either be a single name or an array of names.
Returns true
if this OCG has an intent of :Design.
Returns true
if this OCG has an intent of :View.
Returns the language dictionary (see OptionalContentUsage::Language
) or nil
if no argument is given. Otherwise sets the langauge using the given values.
The language dictionary describes the language of the content controlled by the OCG. The string lang
needs to be a language tag as defined in BCP 47 (e.g. ‘en’ or ‘de-AT’). If preferred
is true
, this dictionary is preferred if there is only a partial match
Returns true
since optional content group dictionaries objects must always be indirect.
Returns the name of the OCG if no argument is given. Otherwise sets the name to the given value.
Sets the state of the OCG to off in the default configuration (see OptionalContentProperties#default_configuration
).
Sets the state of the OCG to on in the default configuration (see OptionalContentProperties#default_configuration
).
Returns true
if the OCG is set to on in the default configuration (see OptionalContentProperties#default_configuration
).
Returns the page element type if no argument is given. Otherwise sets the page element type using the given value.
When set, the page element declares that the OCG contains a pagination artificat. The symbol argument subtype
can either be :HF (header/footer), :FG (foreground image or graphics), :BG (background image or graphics), or :L (logo).
Returns the print state (see OptionalContentUsage::Print
) or nil
if no argument is given. Otherwise sets the print state using the given values.
The print state indicates the state of the content when the PDF document is printed. If state
is true
, the content controlled by the OCG will be printed. The symbol subtype
may optionally specify the kind of content controlled by the OCG (e.g. :Trapping or :Watermark).
Returns the view state if no argument is given. Otherwise sets the view state using the given value.
The view state indicates the state of the content when the PDF document is first opened. If state
is true
, the content controlled by the OCG will be visible.
Returns the zoom dictionary (see OptionalContentUsage::Zoom
) or nil
if no argument is given. Otherwise sets the zoom range using the given values.
The zoom range specifies the magnifications at which the content in the OCG is visible. Either min
or max
or both can be specified as magnification factors (i.e. 1.0 means viewing at 100%):
-
If
min
is specified butmax
isn’t, the maximum possible magnification factor of the PDF processor is used formax
. -
If
max
is specified butmin
isn’t, the default value of 0 formin
is used.