HomeExamplesDocsCodeNews
Home  »  Docs  »  API Reference  »  HexaPDF  »  Type  »  OptionalContentGroup

Classes and Modules

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

NameType/Allowed ValuesRequiredDefault Value
TypeSymboltrue:OCG
NameStringtruenil
IntentSymbol or HexaPDF::PDFArray or Arrayfalse:View
UsageHexaPDF::Type::OptionalContentGroup::OptionalContentUsage or Hashfalsenil

Public Instance Methods

add_to_ui(path: nil)

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.

apply_intent(intent)

Applies the given intent (:View, :Design or a custom intent) to the OCG.

creator_info → creator_info or nil
creator_info(creator, subtype) → creator_info

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).

export_state → true or false
export_state(state) → state

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.

intended_user → user_dict or nil
intended_user(type, name) → user_dict

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.

intent_design?()

Returns true if this OCG has an intent of :Design.

intent_view?()

Returns true if this OCG has an intent of :View.

language → language_info or nil
language(lang, preferred: false) → language_info

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

must_be_indirect?()

Returns true since optional content group dictionaries objects must always be indirect.

name → name
name(value) → value

Returns the name of the OCG if no argument is given. Otherwise sets the name to the given value.

off!()

Sets the state of the OCG to off in the default configuration (see OptionalContentProperties#default_configuration).

on!()

Sets the state of the OCG to on in the default configuration (see OptionalContentProperties#default_configuration).

on?()

Returns true if the OCG is set to on in the default configuration (see OptionalContentProperties#default_configuration).

page_element → element_type or nil
page_element(subtype) → element_type

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).

print_state → print_state or nil
print_state(state, subtype: nil) → print_state

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).

view_state → true or false
view_state(state) → state

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.

zoom → zoom_dict or nil
zoom(min: nil, max: nil) → zoom_dict

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 but max isn’t, the maximum possible magnification factor of the PDF processor is used for max.

  • If max is specified but min isn’t, the default value of 0 for min is used.