hexapdf 0.33.0 → 0.34.0

data/lib/hexapdf/type/actions/set_ocg_state.rb

@@ -0,0 +1,86 @@
+# -*- encoding: utf-8; frozen_string_literal: true -*-
+#
+#--
+# This file is part of HexaPDF.
+#
+# HexaPDF - A Versatile PDF Creation and Manipulation Library For Ruby
+# Copyright (C) 2014-2023 Thomas Leitner
+#
+# HexaPDF is free software: you can redistribute it and/or modify it
+# under the terms of the GNU Affero General Public License version 3 as
+# published by the Free Software Foundation with the addition of the
+# following permission added to Section 15 as permitted in Section 7(a):
+# FOR ANY PART OF THE COVERED WORK IN WHICH THE COPYRIGHT IS OWNED BY
+# THOMAS LEITNER, THOMAS LEITNER DISCLAIMS THE WARRANTY OF NON
+# INFRINGEMENT OF THIRD PARTY RIGHTS.
+#
+# HexaPDF is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public
+# License for more details.
+#
+# You should have received a copy of the GNU Affero General Public License
+# along with HexaPDF. If not, see <http://www.gnu.org/licenses/>.
+#
+# The interactive user interfaces in modified source and object code
+# versions of HexaPDF must display Appropriate Legal Notices, as required
+# under Section 5 of the GNU Affero General Public License version 3.
+#
+# In accordance with Section 7(b) of the GNU Affero General Public
+# License, a covered work must retain the producer line in every PDF that
+# is created or manipulated using HexaPDF.
+#
+# If the GNU Affero General Public License doesn't fit your need,
+# commercial licenses are available at <https://gettalong.at/hexapdf/>.
+#++
+
+require 'hexapdf/type/action'
+
+module HexaPDF
+  module Type
+    module Actions
+
+      # A Set-OCG-state action changes the state of one or more optional content groups.
+      #
+      # See: PDF2.0 s12.6.4.13, HexaPDF::Type::OptionalContentGroup
+      class SetOCGState < Action
+
+        define_field :S, type: Symbol, required: true, default: :SetOCGState
+        define_field :State, type: PDFArray, required: true, default: []
+        define_field :PreserveRB, type: Boolean, default: true
+
+        STATE_TYPE_MAPPING = {on: :ON, ON: :ON, off: :OFF, OFF: :OFF, # :nodoc:
+                              toggle: :Toggle, Toggle: :Toggle}
+
+        # Adds a state changing sequence to the /State array.
+        #
+        # The +type+ argument specifies how the state of the given optional content groups should be
+        # changed.
+        #
+        # +type+:: The type of sequence to add, either :on/:ON (for turning the OCGs on) , :off/:OFF
+        #          (for turning the OCGs off), or :toggle/:Toggle (for toggling the state of the
+        #          OCGs).
+        #
+        # +ocgs+:: A single optional content group or an array of optional content groups to which
+        #          the state change defined with +type+ should be applied. The OCGs can be specified
+        #          via their dictionary or by name which uses the first found OCG with that name.
+        def add_state_change(type, ocgs)
+          type = STATE_TYPE_MAPPING.fetch(type) do
+            raise ArgumentError, "Invalid type #{type} specified, should be one of :on, :off or :toggle"
+          end
+          state = self[:State]
+          state << type
+          Array(ocgs).each do |ocg|
+            if (ocg_name = ocg).kind_of?(String)
+              ocg = document.optional_content.ocg(ocg_name, create: false)
+              raise HexaPDF::Error, "Invalid OCG named '#{ocg_name}' specified" unless ocg
+            end
+            state << ocg
+          end
+        end
+
+      end
+
+    end
+  end
+end

data/lib/hexapdf/type/actions.rb

@@ -48,6 +48,7 @@ module HexaPDF
       autoload(:GoToR, 'hexapdf/type/actions/go_to_r')
       autoload(:Launch, 'hexapdf/type/actions/launch')
       autoload(:URI, 'hexapdf/type/actions/uri')
+      autoload(:SetOCGState, 'hexapdf/type/actions/set_ocg_state')
 
     end
 

data/lib/hexapdf/type/annotations/text.rb

@@ -55,8 +55,7 @@ module HexaPDF
 
         private
 
-        # :nodoc:
-        STATE_TO_STATE_MODEL = {
+        STATE_TO_STATE_MODEL = { # :nodoc:
           "Marked" => "Marked", "Unmarked" => "Marked",
           "Accepted" => "Review", "Rejected" => "Review", "Cancelled" => "Review",
           "Completed" => "Review", "None" => "Review"

data/lib/hexapdf/type/catalog.rb

@@ -78,7 +78,7 @@ module HexaPDF
       define_field :SpiderInfo,        type: Dictionary, version: '1.3'
       define_field :OutputIntents,     type: PDFArray,   version: '1.4'
       define_field :PieceInfo,         type: Dictionary, version: '1.4'
-      define_field :OCProperties,      type: Dictionary, version: '1.5'
+      define_field :OCProperties,      type: :XXOCProperties, version: '1.5'
       define_field :Perms,             type: Dictionary, version: '1.5'
       define_field :Legal,             type: Dictionary, version: '1.5'
       define_field :Requirements,      type: PDFArray,   version: '1.7'
@@ -112,6 +112,15 @@ module HexaPDF
         self[:Outlines] ||= document.add({}, type: :Outlines)
       end
 
+      # Returns the optional content properties dictionary, creating it if needed.
+      #
+      # This is the main entry point for working with optional content, a.k.a. layers.
+      #
+      # See: OptionalContentProperties
+      def optional_content
+        self[:OCProperties] ||= document.add({OCGs: [], D: {Creator: 'HexaPDF'}}, type: :XXOCProperties)
+      end
+
       # Returns the main AcroForm object.
       #
       # * If an AcroForm object exists, the +create+ argument is not used.

data/lib/hexapdf/type/cid_font.rb

@@ -45,10 +45,24 @@ module HexaPDF
     # See: PDF2.0 s9.7.4
     class CIDFont < Font
 
+      # Describes the CIDSystemInfo dictionary specifying the character collection assumed by the
+      # CIDFont.
+      #
+      # See: PDF2.0 s9.7.3
+      class CIDSystemInfo < Dictionary
+
+        define_type :XXCIDSystemInfo
+
+        define_field :Registry, type: String, required: true
+        define_field :Ordering, type: String, required: true
+        define_field :Supplement, type: Integer, required: true
+
+      end
+
       DEFAULT_WIDTH = 1000 # :nodoc:
 
       define_field :BaseFont,        type: Symbol, required: true
-      define_field :CIDSystemInfo,   type: Dictionary, required: true
+      define_field :CIDSystemInfo,   type: :XXCIDSystemInfo, required: true
       define_field :FontDescriptor,  type: :FontDescriptor, indirect: true, required: true
       define_field :DW,              type: Integer, default: DEFAULT_WIDTH
       define_field :W,               type: PDFArray

data/lib/hexapdf/type/form.rb

@@ -34,6 +34,7 @@
 # commercial licenses are available at <https://gettalong.at/hexapdf/>.
 #++
 
+require 'stringio'
 require 'hexapdf/stream'
 require 'hexapdf/content'
 
@@ -45,6 +46,32 @@ module HexaPDF
     # See: PDF2.0 s8.10
     class Form < Stream
 
+      # Represents a group attribute dictionary.
+      #
+      # See: PDF2.0 s8.10.3
+      class Group < Dictionary
+
+        define_type :Group
+
+        define_field :Type, type: Symbol, default: type
+        define_field :S,    type: Symbol, required: true
+
+      end
+
+      # Represents a reference dictionary which allows an XObject to refer to content in an embedded
+      # or linked PDF document.
+      #
+      # See: PDF2.0 s8.10.4
+      class Reference < Dictionary
+
+        define_type :XXReference
+
+        define_field :F,    type: :Filespec, required: true
+        define_field :Page, type: [Integer, String], required: true
+        define_field :ID,   type: PDFArray
+
+      end
+
       define_type :XObject
 
       define_field :Type,          type: Symbol,     default: type
@@ -53,8 +80,8 @@ module HexaPDF
       define_field :BBox,          type: Rectangle,  required: true
       define_field :Matrix,        type: PDFArray,   default: [1, 0, 0, 1, 0, 0]
       define_field :Resources,     type: :XXResources, version: '1.2'
-      define_field :Group,         type: Dictionary, version: '1.4'
-      define_field :Ref,           type: Dictionary, version: '1.4'
+      define_field :Group,         type: :Group,     version: '1.4'
+      define_field :Ref,           type: :XXReference, version: '1.4'
       define_field :Metadata,      type: Stream,     version: '1.4'
       define_field :PieceInfo,     type: Dictionary, version: '1.3'
       define_field :LastModified,  type: PDFDate,    version: '1.3'
@@ -115,14 +142,15 @@ module HexaPDF
       #
       # See: HexaPDF::Content::Processor
       def process_contents(processor, original_resources: nil)
-        processor.resources = if self[:Resources]
-                                self[:Resources]
+        form = referenced_content || self
+        processor.resources = if form[:Resources]
+                                form[:Resources]
                               elsif original_resources
                                 original_resources
                               else
                                 document.wrap({}, type: :XXResources)
                               end
-        Content::Parser.parse(contents, processor)
+        Content::Parser.parse(form.contents, processor)
       end
 
       # Returns the canvas for the form XObject.
@@ -152,6 +180,48 @@ module HexaPDF
         end
       end
 
+      # Returns +true+ if the Form XObject is a reference XObject.
+      def reference_xobject?
+        !self[:Ref].nil?
+      end
+
+      # Returns the referenced page as Form XObject, if this Form XObject is a Reference XObject and
+      # the referenced page is found. Otherwise returns +nil+.
+      def referenced_content
+        return unless (ref = self[:Ref])
+
+        doc = if ref[:F].embedded_file?
+                HexaPDF::Document.new(io: StringIO.new(ref[:F].embedded_file_stream.stream))
+              elsif File.exist?(ref[:F].path)
+                HexaPDF::Document.open(ref[:F].path)
+              end
+        return unless doc
+
+        page = ref[:Page]
+        if page.kind_of?(Integer)
+          page = doc.pages[page]
+        else
+          labels = []
+          doc.pages.each_labelling_range do |first_index, count, label|
+            count.times {|i| labels << label.construct_label(i) }
+          end
+          index = labels.index(page)
+          page = index && doc.pages[index]
+        end
+        return unless page
+
+        # See PDF2.0 s8.10.4.3
+        print_annots = page.each_annotation.select {|annot| annot.flagged?(:print) }
+        page.flatten_annotations(print_annots) unless print_annots.empty?
+
+        obj = page.to_form_xobject
+        obj[:BBox] = self[:BBox].dup
+        obj[:Matrix] = self[:Matrix].dup
+        obj
+      rescue
+        nil
+      end
+
     end
 
   end

data/lib/hexapdf/type/optional_content_configuration.rb

@@ -0,0 +1,170 @@
+# -*- encoding: utf-8; frozen_string_literal: true -*-
+#
+#--
+# This file is part of HexaPDF.
+#
+# HexaPDF - A Versatile PDF Creation and Manipulation Library For Ruby
+# Copyright (C) 2014-2023 Thomas Leitner
+#
+# HexaPDF is free software: you can redistribute it and/or modify it
+# under the terms of the GNU Affero General Public License version 3 as
+# published by the Free Software Foundation with the addition of the
+# following permission added to Section 15 as permitted in Section 7(a):
+# FOR ANY PART OF THE COVERED WORK IN WHICH THE COPYRIGHT IS OWNED BY
+# THOMAS LEITNER, THOMAS LEITNER DISCLAIMS THE WARRANTY OF NON
+# INFRINGEMENT OF THIRD PARTY RIGHTS.
+#
+# HexaPDF is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public
+# License for more details.
+#
+# You should have received a copy of the GNU Affero General Public License
+# along with HexaPDF. If not, see <http://www.gnu.org/licenses/>.
+#
+# The interactive user interfaces in modified source and object code
+# versions of HexaPDF must display Appropriate Legal Notices, as required
+# under Section 5 of the GNU Affero General Public License version 3.
+#
+# In accordance with Section 7(b) of the GNU Affero General Public
+# License, a covered work must retain the producer line in every PDF that
+# is created or manipulated using HexaPDF.
+#
+# If the GNU Affero General Public License doesn't fit your need,
+# commercial licenses are available at <https://gettalong.at/hexapdf/>.
+#++
+
+require 'hexapdf/dictionary'
+
+module HexaPDF
+  module Type
+
+    # Represents an optional content configuration dictionary.
+    #
+    # This dictionary is used for the /D and /Configs entries in the optional content properties
+    # dictionary. It configures the states of the OCGs as well as defines how those states may be
+    # changed by a PDF processor.
+    #
+    # See: PDF2.0 s8.11.4.3
+    class OptionalContentConfiguration < Dictionary
+
+      # Represents an optional content usage application dictionary.
+      #
+      # This dictionary is used for the elements in the /AS array of an optional content
+      # configuration dictionary. It specifies how a PDF processor should use the usage entries of
+      # OCGs to automatically change their state based on external factors (like magnifacation
+      # factor or language).
+      #
+      # See: PDF2.0 s8.11.4.4
+      class UsageApplication < Dictionary
+        define_type :XXOCUsageApplication
+        define_field :Event, type: Symbol, required: true, allowed_values: [:View, :Print, :Export]
+        define_field :OCGs, type: PDFArray, default: []
+        define_field :Category, type: PDFArray, required: true
+      end
+
+      define_type :XXOCConfiguration
+
+      define_field :Name,      type: String
+      define_field :Creator,   type: String
+      define_field :BaseState, type: Symbol, default: :ON, allowed_values: [:ON, :OFF, :Unchanged]
+      define_field :ON,        type: PDFArray
+      define_field :OFF,       type: PDFArray
+      define_field :Intent,    type: [Symbol, PDFArray], default: :View
+      define_field :AS,        type: PDFArray
+      define_field :Order,     type: PDFArray
+      define_field :ListMode,  type: Symbol, default: :AllPages,
+        allowed_values: [:AllPages, :VisiblePages]
+      define_field :RBGroups,  type: PDFArray
+      define_field :Locked,    type: PDFArray, default: []
+
+      # :call-seq:
+      #   configuration.ocg_state(ocg)          -> state
+      #   configuration.ocg_state(ocg, state)   -> state
+      #
+      # Returns the state (+:on+, +:off+ or +nil+) of the optional content group if the +state+
+      # argument is not given. Otherwise sets the state of the OCG to the given state value
+      # (+:on+/+:ON+ or +:off+/+:OFF+).
+      #
+      # The value +nil+ is only returned if the state is not defined by the configuration dictionary
+      # (which may only be the case if the configuration dictionary is not the default configuration
+      # dictionary).
+      def ocg_state(ocg, state = nil)
+        if state.nil?
+          case self[:BaseState]
+          when :ON then self[:OFF]&.include?(ocg) ? :off : :on
+          when :OFF then self[:ON]&.include?(ocg) ? :on : :off
+          else self[:OFF]&.include?(ocg) ? :off : (self[:ON]&.include?(ocg) ? :on : nil)
+          end
+        elsif state&.downcase == :on
+          (self[:ON] ||= []) << ocg unless self[:ON]&.include?(ocg)
+          self[:OFF].delete(ocg) if key?(:OFF)
+        elsif state&.downcase == :off
+          (self[:OFF] ||= []) << ocg unless self[:OFF]&.include?(ocg)
+          self[:ON].delete(ocg) if key?(:ON)
+        else
+          raise ArgumentError, "Invalid value #{state.inspect} for state argument"
+        end
+      end
+
+      # Returns +true+ if the given optional content group is on.
+      def ocg_on?(ocg)
+        ocg_state(ocg) == :on
+      end
+
+      # Makes the given optional content group visible in an interactive PDF processor's user
+      # interface.
+      #
+      # The OCG is always added to the end of the specified +path+ or, if +path+ is not specified,
+      # the top level.
+      #
+      # The optional argument +path+ specifies the strings or OCGs under which the given OCG should
+      # hierarchically be nested. A string is used as a non-selectable label, an OCG reflects an
+      # actual nesting of the involved OCGs.
+      #
+      # Examples:
+      #
+      #  configuration.add_ocg_to_ui(ocg)                   # Add the OCG as top-level item
+      #  configuration.add_ocg_to_ui(ocg, path: 'Debug')    # Add the OCG under the label 'Debug'
+      #  # Add the OCG under the label 'Page1' which is under the label 'Debug'
+      #  configuration.add_ocg_to_ui(ocg, path: ['Debug', 'Page1'])
+      #  configuration.add_ocg_to_ui(ocg, path: other_ocg)  # Add the OCG under the other OCG
+      def add_ocg_to_ui(ocg, path: nil)
+        array = self[:Order] ||= []
+        path = Array(path)
+        until path.empty?
+          item = path.shift
+          index = array.index do |entry|
+            if (entry.kind_of?(Array) || entry.kind_of?(PDFArray)) && item.kind_of?(String)
+              entry.first == item
+            else
+              entry == item
+            end
+          end
+
+          if item.kind_of?(String)
+            unless index
+              array << [item]
+              index = -1
+            end
+            array = array[index]
+          else
+            unless index
+              array << item << []
+              index = -2
+            end
+            if array[index + 1].kind_of?(Array) || array[index + 1].kind_of?(PDFArray)
+              array = array[index + 1]
+            else
+              array.insert(index + 1, [])
+              array = array[index + 1]
+            end
+          end
+        end
+        array << ocg
+      end
+
+    end
+
+  end
+end