Class: HexaPDF::Type::OptionalContentGroup

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

Overview

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

Defined Under Namespace

Classes: OptionalContentUsage

Constant Summary

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_h, 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, #null?, #oid, #oid=, #type, #validate, #value, #value=

Constructor Details

This class inherits a constructor from HexaPDF::Object

Instance Method Details

#add_to_ui(path: nil) ⇒ Object

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.



211
212
213
 
# File 'lib/hexapdf/type/optional_content_group.rb', line 211

def add_to_ui(path: nil)
  document.optional_content.default_configuration.add_ocg_to_ui(self, path: path)
end

#apply_intent(intent) ⇒ Object

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



175
176
177
178
 
# File 'lib/hexapdf/type/optional_content_group.rb', line 175

def apply_intent(intent)
  self[:Intent] = key?(:Intent) ? Array(self[:Intent]) : []
  self[:Intent] << intent
end

#creator_info(creator = nil, subtype = nil) ⇒ Object

:call-seq:

ocg.creator_info                     -> creator_info or nil
ocg.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).



226
227
228
229
230
231
232
233
234
 
# File 'lib/hexapdf/type/optional_content_group.rb', line 226

def creator_info(creator = nil, subtype = nil)
  if creator && subtype
    self[:Usage] ||= {}
    self[:Usage][:CreatorInfo] = {Creator: creator, Subtype: subtype}
  elsif creator || subtype
    raise ArgumentError, "Missing argument, both creator and subtype are needed"
  end
  self[:Usage]&.[](:CreatorInfo)
end

#export_state(state = nil) ⇒ Object

:call-seq:

ocg.export_state         -> true or false
ocg.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.



264
265
266
267
268
269
270
 
# File 'lib/hexapdf/type/optional_content_group.rb', line 264

def export_state(state = nil)
  if state
    self[:Usage] ||= {}
    self[:Usage][:Export] = {ExportState: (state ? :ON : :OFF)}
  end
  self[:Usage]&.[](:Export)&.[](:ExportState) == :ON
end

#intended_user(type = nil, name = nil) ⇒ Object

:call-seq:

ocg.intended_user              -> user_dict or nil
ocg.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.



341
342
343
344
345
346
347
 
# File 'lib/hexapdf/type/optional_content_group.rb', line 341

def intended_user(type = nil, name = nil)
  if type && name
    self[:Usage] ||= {}
    self[:Usage][:User] = {Type: type, Name: name}
  end
  self[:Usage]&.[](:User)
end

#intent_design? ⇒ Boolean

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

Returns:



186
187
188
 
# File 'lib/hexapdf/type/optional_content_group.rb', line 186

def intent_design?
  Array(self[:Intent]).include?(:Design)
end

#intent_view? ⇒ Boolean

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

Returns:



181
182
183
 
# File 'lib/hexapdf/type/optional_content_group.rb', line 181

def intent_view?
  Array(self[:Intent]).include?(:View)
end

#language(lang = nil, preferred: false) ⇒ Object

:call-seq:

ocg.language                          -> language_info or nil
ocg.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



246
247
248
249
250
251
252
 
# File 'lib/hexapdf/type/optional_content_group.rb', line 246

def language(lang = nil, preferred: false)
  if lang
    self[:Usage] ||= {}
    self[:Usage][:Language] = {Lang: lang, Preferred: (preferred ? :ON : :OFF)}
  end
  self[:Usage]&.[](:Language)
end

#must_be_indirect? ⇒ Boolean

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

Returns:



156
157
158
 
# File 'lib/hexapdf/type/optional_content_group.rb', line 156

def must_be_indirect?
  true
end

#name(value = nil) ⇒ Object

:call-seq:

ocg.name          -> name
ocg.name(value)   -> value

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



166
167
168
169
170
171
172
 
# File 'lib/hexapdf/type/optional_content_group.rb', line 166

def name(value = nil)
  if value
    self[:Name] = value
  else
    self[:Name]
  end
end

#off! ⇒ Object

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



204
205
206
 
# File 'lib/hexapdf/type/optional_content_group.rb', line 204

def off!
  document.optional_content.default_configuration.ocg_state(self, :off)
end

#on! ⇒ Object

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



198
199
200
 
# File 'lib/hexapdf/type/optional_content_group.rb', line 198

def on!
  document.optional_content.default_configuration.ocg_state(self, :on)
end

#on? ⇒ Boolean

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

Returns:



192
193
194
 
# File 'lib/hexapdf/type/optional_content_group.rb', line 192

def on?
  document.optional_content.default_configuration.ocg_on?(self)
end

#page_element(subtype = nil) ⇒ Object

:call-seq:

ocg.page_element           -> element_type or nil
ocg.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).



359
360
361
362
363
364
365
 
# File 'lib/hexapdf/type/optional_content_group.rb', line 359

def page_element(subtype = nil)
  if subtype
    self[:Usage] ||= {}
    self[:Usage][:PageElement] = {Subtype: subtype}
  end
  self[:Usage]&.[](:PageElement)&.[](:Subtype)
end

#print_state(state = nil, subtype: nil) ⇒ Object

:call-seq:

ocg.print_state                       -> print_state or nil
ocg.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).



300
301
302
303
304
305
306
 
# File 'lib/hexapdf/type/optional_content_group.rb', line 300

def print_state(state = nil, subtype: nil)
  if state
    self[:Usage] ||= {}
    self[:Usage][:Print] = {PrintState: (state ? :ON : :OFF), Subtype: subtype}
  end
  self[:Usage]&.[](:Print)
end

#view_state(state = nil) ⇒ Object

:call-seq:

ocg.view_state         -> true or false
ocg.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.



281
282
283
284
285
286
287
 
# File 'lib/hexapdf/type/optional_content_group.rb', line 281

def view_state(state = nil)
  if state
    self[:Usage] ||= {}
    self[:Usage][:View] = {ViewState: (state ? :ON : :OFF)}
  end
  self[:Usage]&.[](:View)&.[](:ViewState) == :ON
end

#zoom(min: nil, max: nil) ⇒ Object

:call-seq:

ocg.zoom                      -> zoom_dict or nil
ocg.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.



323
324
325
326
327
328
329
 
# File 'lib/hexapdf/type/optional_content_group.rb', line 323

def zoom(min: nil, max: nil)
  if min || max
    self[:Usage] ||= {}
    self[:Usage][:Zoom] = {min: min, max: max}
  end
  self[:Usage]&.[](:Zoom)
end