Class: HexaPDF::Type::OptionalContentProperties

Inherits:
Dictionary show all
Defined in:
lib/hexapdf/type/optional_content_properties.rb

Overview

Represents an optional content properties dictionary.

This dictionary is the value of the /OCProperties key in the document catalog and needs to exist for optional content to be usable by a PDF processor.

In HexaPDF it provides the main entry point for working with optional content.

See: PDF2.0 s8.11.4.2

Constant Summary collapse

OCMD_POLICY_MAPPING =

:nodoc:

{any_on: :AnyOn, AnyOn: :AnyOn, any_off: :AnyOff, # :nodoc:
AnyOff: :AnyOff, all_off: :AllOff, AllOff: :AllOff}

Constants included from DictionaryFields

DictionaryFields::Boolean, DictionaryFields::PDFByteString, DictionaryFields::PDFDate

Instance Attribute Summary

Attributes inherited from Object

#data, #document, #must_be_indirect

Instance Method Summary collapse

Methods inherited from Dictionary

#[], #[]=, define_field, define_type, #delete, #each, each_field, #empty?, field, #key?, #to_hash, type, #type

Methods inherited from Object

#<=>, #==, #cache, #cached?, #clear_cache, deep_copy, #deep_copy, #document?, #eql?, field, #gen, #gen=, #hash, #indirect?, #initialize, #inspect, make_direct, #must_be_indirect?, #null?, #oid, #oid=, #type, #validate, #value, #value=

Constructor Details

This class inherits a constructor from HexaPDF::Object

Instance Method Details

#add_ocg(name_or_dict) ⇒ Object

:call-seq:

optional_content.add_ocg(name)          -> ocg
optional_content.add_ocg(ocg)           -> ocg

Adds the given optional content group to the list of known OCGs and returns it. If a string is provided, an optional content group with that name is created before adding it.

See: #ocg, OptionalContentGroup



66
67
68
69
70
71
72
73
74
 
# File 'lib/hexapdf/type/optional_content_properties.rb', line 66

def add_ocg(name_or_dict)
  ocg = if name_or_dict.kind_of?(Dictionary)
          name_or_dict
        else
          document.add({Type: :OCG, Name: name_or_dict})
        end
  self[:OCGs] << ocg unless self[:OCGs].include?(ocg)
  ocg
end

#create_ocmd(ocgs, policy: :any_on) ⇒ Object

Creates an optional content membership dictionary containing the given optional content group(s).

The optional argument policy specifies the visibility policy:

:any_on/:AnyOn

Content is visible if any of the OCGs are on.

:any_off/:AnyOff

Content is visible if any of the OCGs are off.

:all_on/:AllOn

Content is only visible if all OCGs are on.

:all_off/:AllOff

Content is only visible if all OCGs are off.

See: OptionalContentMembership



109
110
111
112
113
114
 
# File 'lib/hexapdf/type/optional_content_properties.rb', line 109

def create_ocmd(ocgs, policy: :any_on)
  policy = OCMD_POLICY_MAPPING.fetch(policy) do
    raise ArgumentError, "Invalid OCMD policy #{policy} specified"
  end
  document.wrap({Type: :OCMD, OCGs: Array(ocgs), P: policy})
end

#default_configuration(hash = nil) ⇒ Object

:call-seq:

optional_content.default_configuration        -> config_dict
optional_content.default_configuration(hash)  -> config_dict

Returns the default optional content configuration dictionary if no argument is given. Otherwise sets the the default optional content configuration to the given hash value.

The default configuration defines the initial state of the optional content groups and how those states may be changed by a PDF processor.

Example:

optional_content.default_configuration(
  Name: 'My Configuration',
  OFF: [ocg1],
  Order: [ocg_all, [ocg1, ocg2, ocg3]]
)

See: OptionalContentConfiguration



135
136
137
138
139
140
141
142
 
# File 'lib/hexapdf/type/optional_content_properties.rb', line 135

def default_configuration(hash = nil)
  if hash
    self[:D] = hash
  else
    self[:D] ||= {Name: 'Default', Creator: 'HexaPDF'}
  end
  self[:D]
end

#ocg(name, create: true) ⇒ Object

:call-seq:

optional_content.ocg(name, create: true)          -> ocg or +nil+

Returns the first found optional content group with the given name.

If no optional content group with the given name exists but the optional argument create is true, a new OCG with the given name is created and returned. Otherwise nil is returned.

See: #add_ocg



86
87
88
 
# File 'lib/hexapdf/type/optional_content_properties.rb', line 86

def ocg(name, create: true)
  self[:OCGs].find {|ocg| ocg.name == name } || (create && add_ocg(name) || nil)
end

#ocgs ⇒ Object

Returns the list of known optional content group objects, with duplicates removed.



91
92
93
 
# File 'lib/hexapdf/type/optional_content_properties.rb', line 91

def ocgs
  self[:OCGs].uniq.compact
end