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_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, #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.



227
228
229
 
# File 'lib/hexapdf/type/optional_content_group.rb', line 227

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.



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

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



242
243
244
245
246
247
248
249
250
 
# File 'lib/hexapdf/type/optional_content_group.rb', line 242

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.



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

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.



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

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:



202
203
204
 
# File 'lib/hexapdf/type/optional_content_group.rb', line 202

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

#intent_view? ⇒ Boolean

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

Returns:



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

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



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

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:



172
173
174
 
# File 'lib/hexapdf/type/optional_content_group.rb', line 172

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.



182
183
184
185
186
187
188
 
# File 'lib/hexapdf/type/optional_content_group.rb', line 182

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



220
221
222
 
# File 'lib/hexapdf/type/optional_content_group.rb', line 220

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



214
215
216
 
# File 'lib/hexapdf/type/optional_content_group.rb', line 214

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:



208
209
210
 
# File 'lib/hexapdf/type/optional_content_group.rb', line 208

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



375
376
377
378
379
380
381
 
# File 'lib/hexapdf/type/optional_content_group.rb', line 375

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



316
317
318
319
320
321
322
 
# File 'lib/hexapdf/type/optional_content_group.rb', line 316

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.



297
298
299
300
301
302
303
 
# File 'lib/hexapdf/type/optional_content_group.rb', line 297

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.



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

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