hexapdf 0.11.5 → 0.12.0

data/lib/hexapdf/type/acro_form/field.rb

@@ -4,7 +4,7 @@
 # This file is part of HexaPDF.
 #
 # HexaPDF - A Versatile PDF Creation and Manipulation Library For Ruby
-# Copyright (C) 2014-2019 Thomas Leitner
+# Copyright (C) 2014-2020 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
@@ -35,24 +35,75 @@
 #++
 
 require 'hexapdf/dictionary'
+require 'hexapdf/error'
+require 'hexapdf/utils/bit_field'
+require 'hexapdf/type/annotations'
 
 module HexaPDF
   module Type
     module AcroForm
 
-      # Field dictionaries are used to define the properties of form fields of AcroForm objects.
+      # AcroForm field dictionaries are used to define the properties of form fields of AcroForm
+      # objects.
       #
       # Fields can be organized in a hierarchy using the /Kids and /Parent keys, for namespacing
       # purposes and to set default values. Those fields that have other fields as children are
       # called non-terminal fields, otherwise they are called terminal fields.
       #
+      # While field objects can be created manually, it is best to use the various +create_+ methods
+      # of the main Form object to create them so that all necessary things are set up correctly.
+      #
+      # == Field Types
+      #
+      # Subclasses are used to implement the specific AcroForm field types:
+      #
+      # * ButtonField implements the button fields (pushbuttons, check boxes and radio buttons)
+      # * TextField implements single or multiline text fields.
+      # * ChoiceField implements scrollable list boxes or (editable) combo boxes.
+      # * SignatureField implements signature fields.
+      #
+      # == Field Flags
+      #
+      # Various characteristics of a field can be changed by setting a certain flag. Some flags are
+      # defined for all types of field, some are specific to a certain type.
+      #
+      # The following flags apply to all fields:
+      #
+      # :read_only:: The field is read only which means the user can't change the value or interact
+      #              with associated widget annotations.
+      #
+      # :required:: The field is required if the form is exported by a submit-form action.
+      #
+      # :no_export:: The field should *not* be exported by a submit-form action.
+      #
+      # == Field Type Implementation Notes
+      #
+      # If an AcroForm field type adds additional inheritable dictionary fields, it has to set the
+      # constant +INHERITABLE_FIELDS+ to all inheritable dictionary fields, including those from the
+      # superclass.
+      #
+      # Similarily, if additional flags are provided, the constant +FLAGS_BIT_MAPPING+ has to be set
+      # to combination of the superclass value of the constant and the mapping of flag names to bit
+      # indices.
+      #
       # See: PDF1.7 s12.7.3.1
       class Field < Dictionary
 
-        define_type :XXAcroFormField
+        # Provides a #value method for hash that returns self so that a Hash can be used
+        # interchangably with a HexaPDF::Dictionary.
+        module HashRefinement
+          refine Hash do
+            def value
+              self
+            end
+          end
+        end
+
+        using HashRefinement
 
-        # List of inheritable fields.
-        INHERITABLE_FIELDS = [:FT, :Ff, :V, :DV]
+        extend Utils::BitField
+
+        define_type :XXAcroFormField
 
         define_field :FT,     type: Symbol, allowed_values: [:Btn, :Tx, :Ch, :Sig]
         define_field :Parent, type: :XXAcroFormField
@@ -61,10 +112,49 @@ module HexaPDF
         define_field :TU,     type: String, version: '1.3'
         define_field :TM,     type: String, version: '1.3'
         define_field :Ff,     type: Integer, default: 0
-        define_field :V,      type: [Symbol, String, Stream, PDFArray, Dictionary]
-        define_field :DV,     type: [Symbol, String, Stream, PDFArray, Dictionary]
+        define_field :V,      type: [Dictionary, Symbol, String, Stream, PDFArray]
+        define_field :DV,     type: [Dictionary, Symbol, String, Stream, PDFArray]
         define_field :AA,     type: Dictionary, version: '1.2'
 
+        # The inheritable dictionary fields common to all AcroForm field types.
+        INHERITABLE_FIELDS = [:FT, :Ff, :V, :DV].freeze
+
+        ##
+        # :method: flags
+        #
+        # Returns an array of flag names representing the set bit flags.
+        #
+
+        ##
+        # :method: flagged?
+        # :call-seq:
+        #   flagged?(flag)
+        #
+        # Returns +true+ if the given flag is set. The argument can either be the flag name or the
+        # bit index.
+        #
+
+        ##
+        # :method: flag
+        # :call-seq:
+        #   flag(*flags, clear_existing: false)
+        #
+        # Sets the given flags, given as flag names or bit indices. If +clear_existing+ is +true+,
+        # all prior flags will be cleared.
+        #
+        bit_field(:flags, {read_only: 0, required: 1, no_export: 2},
+                  lister: "flags", getter: "flagged?", setter: "flag", unsetter: "unflag",
+                  value_getter: "self[:Ff]", value_setter: "self[:Ff]")
+
+        # Treats +name+ as an inheritable dictionary field and resolves its value for the AcroForm
+        # field +field+.
+        def self.inherited_value(field, name)
+          while field.value[name].nil? && (parent = field[:Parent])
+            field = parent
+          end
+          field.value[name].nil? ? nil : field[name]
+        end
+
         # Form fields must always be indirect objects.
         def must_be_indirect?
           true
@@ -72,15 +162,13 @@ module HexaPDF
 
         # Returns the value for the entry +name+.
         #
-        # If +name+ is an inheritable value and the value has not been set on this field object, its
+        # If +name+ is an inheritable field and the value has not been set on this field object, its
         # value is retrieved from the parent fields.
         #
         # See: Dictionary#[]
         def [](name)
-          if value[name].nil? && INHERITABLE_FIELDS.include?(name)
-            field = self
-            field = field[:Parent] while field.value[name].nil? && field[:Parent]
-            field == self || field.value[name].nil? ? super : field[name]
+          if value[name].nil? && self.class::INHERITABLE_FIELDS.include?(name)
+            self.class.inherited_value(self, name) || super
           else
             super
           end
@@ -88,30 +176,145 @@ module HexaPDF
 
         # Returns the type of the field, either :Btn (pushbuttons, check boxes, radio buttons), :Tx
         # (text fields), :Ch (scrollable list boxes, combo boxes) or :Sig (signature fields).
+        #
+        # Also see #concrete_field_type
         def field_type
           self[:FT]
         end
 
+        # Returns the concrete field type (:button_field, :text_field, :choice_field or
+        # :signature_field) or +nil+ is no field type is set.
+        #
+        # In constrast to #field_type this method also considers the field flags and not just the
+        # field type. This means that subclasses can return a more concrete name for the field type.
+        #
+        # Also see #field_type
+        def concrete_field_type
+          case self[:FT]
+          when :Btn then :button_field
+          when :Tx  then :text_field
+          when :Ch  then :choice_field
+          when :Sig then :signature_field
+          else nil
+          end
+        end
+
+        # Returns the name of the field or +nil+ if no name is set.
+        def field_name
+          self[:T]
+        end
+
         # Returns the full name of the field or +nil+ if no name is set.
         #
         # The full name of a field is constructed using the full name of the parent field, a period
-        # and the partial name of the field.
-        def full_name
+        # and the field name of the field.
+        def full_field_name
           if key?(:Parent)
-            [self[:Parent].full_name, self[:T]].compact.join('.')
+            [self[:Parent].full_field_name, field_name].compact.join('.')
           else
-            self[:T]
+            field_name
           end
         end
 
+        # Returns the alternate field name that should be used for display purposes (e.g. Acrobat
+        # shows this as tool tip).
+        def alternate_field_name
+          self[:TU]
+        end
+
+        # Sets the alternate field name.
+        #
+        # See #alternate_field_name
+        def alternate_field_name=(value)
+          self[:TU] = value
+        end
+
         # Returns +true+ if this is a terminal field.
         def terminal_field?
           kids = self[:Kids]
-          kids.nil? || kids.empty? || kids.any? {|kid| kid[:Subtype] == :Widget }
+          # PDF 2.0 s12.7.4.2 clarifies how to do check for fields since PDF 1.7 isn't clear
+          kids.nil? || kids.empty? || kids.none? {|kid| kid.key?(:T) }
+        end
+
+        # :call-seq:
+        #   field.each_widget {|widget| block}    -> field
+        #   field.each_widget                     -> Enumerator
+        #
+        # Yields each widget, i.e. visual representation, of this field.
+        #
+        # See: HexaPDF::Type::Annotations::Widget
+        def each_widget # :yields: widget
+          return to_enum(__method__) unless block_given?
+          if self[:Subtype]
+            yield(document.wrap(self))
+          elsif terminal_field?
+            self[:Kids]&.each {|kid| yield(document.wrap(kid)) }
+          end
+          self
+        end
+
+        # Creates a new widget annotation for this form field (must be a terminal field!) on the
+        # given +page+, adding the +values+ to the created widget annotation oject.
+        #
+        # If +allow_embedded+ is +false+, embedding the first widget in the field itself is not
+        # allowed.
+        #
+        # The +values+ argument should at least include :Rect for setting the visible area of the
+        # widget.
+        #
+        # If the field already has an embedded widget, i.e. field and widget are the same PDF
+        # object, its widget data is extracted to a new PDF object and stored in the /Kids field,
+        # together with the new widget annotation. Note that this means that a possible reference to
+        # the formerly embedded widget (=this field) is not valid anymore!
+        #
+        # See: HexaPDF::Type::Annotations::Widget
+        def create_widget(page, allow_embedded: true, **values)
+          unless terminal_field?
+            raise HexaPDF::Error, "Widgets can only be added to terminal fields"
+          end
+
+          widget_data = {Type: :Annot, Subtype: :Widget, Rect: [0, 0, 0, 0], **values}
+
+          if !allow_embedded || key?(:Subtype) || (key?(:Kids) && !self[:Kids].empty?)
+            kids = self[:Kids] ||= []
+            kids << extract_widget if key?(:Subtype)
+            widget = document.add(widget_data)
+            widget[:Parent] = self
+            self[:Kids] << widget
+          else
+            value.update(widget_data)
+            widget = document.wrap(self)
+          end
+
+          (page[:Annots] ||= []) << widget
+
+          widget
         end
 
         private
 
+        # An array of all widget annotation field names.
+        WIDGET_FIELDS = HexaPDF::Type::Annotations::Widget.each_field.map(&:first).uniq - [:Parent]
+
+        # Returns a new dictionary object with all the widget annotation data that is stored
+        # directly in the field and adjust the references accordingly. If the field doesn't have any
+        # widget data, +nil+ is returned.
+        def extract_widget
+          return unless key?(:Subtype)
+          data = WIDGET_FIELDS.each_with_object({}) do |key, hash|
+            hash[key] = delete(key) if key?(key)
+          end
+          widget = document.add(data, type: :Annot)
+          widget[:Parent] = self
+          document.pages.each do |page|
+            if page.key?(:Annots) && (index = page[:Annots].index {|annot| annot.data == self.data })
+              page[:Annots][index] = widget
+              break # Each annotation dictionary may only appear on one page, see PDF1.7 12.5.2
+            end
+          end
+          widget
+        end
+
         def perform_validation #:nodoc:
           super
           if terminal_field? && field_type.nil?

data/lib/hexapdf/type/acro_form/form.rb

@@ -4,7 +4,7 @@
 # This file is part of HexaPDF.
 #
 # HexaPDF - A Versatile PDF Creation and Manipulation Library For Ruby
-# Copyright (C) 2014-2019 Thomas Leitner
+# Copyright (C) 2014-2020 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
@@ -36,6 +36,7 @@
 
 require 'hexapdf/dictionary'
 require 'hexapdf/stream'
+require 'hexapdf/type/acro_form/field'
 require 'hexapdf/utils/bit_field'
 
 module HexaPDF
@@ -45,7 +46,29 @@ module HexaPDF
       # Represents the PDF's interactive form dictionary. It is linked from the catalog dictionary
       # via the /AcroForm entry.
       #
-      # See: PDF1.7 s12.7.2
+      # == Overview
+      #
+      # An interactive form consists of fields which can be structured hierarchically and shown on
+      # pages by using Annotations::Widget annotations. This means one field can have zero, one or
+      # more visual representations on one or more pages. The fields at the bottom of the hierarchy
+      # which have no parent are called "root fields" and are stored in /Fields.
+      #
+      # Each field in a form has a certain type which determines how it should be displayed and what
+      # a user can do with it. The most common type is "text field" which allows the user to enter
+      # one or more lines of text. There are also check boxes, radio buttons, list boxes and combo
+      # boxes.
+      #
+      # == Visual Appearance
+      #
+      # The visual appearance of a field is normally provided by the application creating the PDF.
+      # This is done by generating the so called appearances for all widgets of a field. However, it
+      # is also possible to instruct the PDF reader application to generate the appearances on the
+      # fly using the /NeedAppearances key, see #need_appearances!.
+      #
+      # HexaPDF uses the configuration option +acro_form.create_appearance_streams+ to determine
+      # whether appearances should automatically be generated.
+      #
+      # See: PDF1.7 s12.7.2, Field, HexaPDF::Type::Annotations::Widget
       class Form < Dictionary
 
         extend Utils::BitField
@@ -56,12 +79,18 @@ module HexaPDF
         define_field :NeedAppearances, type: Boolean, default: false
         define_field :SigFlags,        type: Integer, version: '1.3'
         define_field :CO,              type: PDFArray, version: '1.3'
-        define_field :DR,              type: :Ressources
+        define_field :DR,              type: :XXResources
         define_field :DA,              type: String
         define_field :XFA,             type: [Stream, PDFArray], version: '1.5'
 
         bit_field(:raw_signature_flags, {signatures_exist: 0, append_only: 1},
-                  lister: "signature_flags", getter: "signature_flag?", setter: "signature_flag")
+                  lister: "signature_flags", getter: "signature_flag?", setter: "signature_flag",
+                  unsetter: "signature_unflag")
+
+        # Returns the PDFArray containing the root fields.
+        def root_fields
+          self[:Fields] ||= document.wrap([])
+        end
 
         # Returns an array with all root fields that were found in the PDF document.
         def find_root_fields
@@ -69,7 +98,7 @@ module HexaPDF
           document.pages.each do |page|
             page[:Annots]&.each do |annot|
               if !annot.key?(:Parent) && annot.key?(:FT)
-                result << document.wrap(annot, type: :XXAcroFormField)
+                result << document.wrap(annot, type: :XXAcroFormField, subtype: annot[:FT])
               elsif annot.key?(:Parent)
                 field = annot[:Parent]
                 field = field[:Parent] while field[:Parent]
@@ -96,15 +125,99 @@ module HexaPDF
           return to_enum(__method__, terminal_only: terminal_only) unless block_given?
 
           process_field = lambda do |field|
-            field = document.wrap(field, type: :XXAcroFormField)
+            field = document.wrap(field, type: :XXAcroFormField,
+                                  subtype: Field.inherited_value(field, :FT))
             yield(field) if field.terminal_field? || !terminal_only
             field[:Kids].each(&process_field) unless field.terminal_field?
           end
 
-          self[:Fields]&.each(&process_field)
+          root_fields.each(&process_field)
           self
         end
 
+        # Returns the field with the given +name+ or +nil+ if no such field exists.
+        def field_by_name(name)
+          fields = root_fields
+          field = nil
+          name.split('.').each do |part|
+            field = fields&.find {|f| f[:T] == part }
+            break unless field
+            field = document.wrap(field, type: :XXAcroFormField,
+                                  subtype: Field.inherited_value(field, :FT))
+            fields = field[:Kids] unless field.terminal_field?
+          end
+          field
+        end
+
+        # Creates a new text field with the given name and adds it to the form.
+        #
+        # The +name+ may contain dots to signify a field hierarchy. If so, the referenced parent
+        # fields must already exist. If it doesn't contain dots, a top-level field is created.
+        def create_text_field(name)
+          create_field(name, :Tx)
+        end
+
+        # Creates a new check box with the given name and adds it to the form.
+        #
+        # The +name+ may contain dots to signify a field hierarchy. If so, the referenced parent
+        # fields must already exist. If it doesn't contain dots, a top-level field is created.
+        def create_check_box(name)
+          create_field(name, :Btn).tap(&:initialize_as_check_box)
+        end
+
+        # Creates a radio button with the given name and adds it to the form.
+        #
+        # The +name+ may contain dots to signify a field hierarchy. If so, the referenced parent
+        # fields must already exist. If it doesn't contain dots, a top-level field is created.
+        def create_radio_button(name)
+          create_field(name, :Btn).tap(&:initialize_as_radio_button)
+        end
+
+        # Creates a combo box with the given name and adds it to the form.
+        #
+        # The +name+ may contain dots to signify a field hierarchy. If so, the referenced parent
+        # fields must already exist. If it doesn't contain dots, a top-level field is created.
+        def create_combo_box(name)
+          create_field(name, :Ch).tap(&:initialize_as_combo_box)
+        end
+
+        # Creates a list box with the given name and adds it to the form.
+        #
+        # The +name+ may contain dots to signify a field hierarchy. If so, the referenced parent
+        # fields must already exist. If it doesn't contain dots, a top-level field is created.
+        def create_list_box(name)
+          create_field(name, :Ch).tap(&:initialize_as_list_box)
+        end
+
+        # Returns the dictionary containing the default resources for form field appearance streams.
+        def default_resources
+          self[:DR] ||= document.wrap({}, type: :XXResources)
+        end
+
+        # Sets the global default appearance string using the provided values.
+        #
+        # The default argument values are a sane default. If +font_size+ is set to 0, the font size
+        # is calculated using the height/width of the field.
+        def set_default_appearance_string(font: 'Helvetica', font_size: 0)
+          name = default_resources.add_font(document.fonts.add(font).pdf_object)
+          self[:DA] = "0 g /#{name} #{font_size} Tf"
+        end
+
+        # Sets the /NeedAppearances field to +true+.
+        #
+        # This will make PDF reader applications generate appropriate appearance streams based on
+        # the information stored in the fields and associated widgets.
+        def need_appearances!
+          self[:NeedAppearances] = true
+        end
+
+        # Creates the appearances for all widgets of all terminal fields if they don't exist.
+        def create_appearances
+          each_field do |field|
+            field.create_appearances if field.respond_to?(:create_appearances)
+          end
+        end
+
         private
 
         # Helper method for bit field getter access.
@@ -117,6 +230,43 @@ module HexaPDF
           self[:SigFlags] = value
         end
 
+        # Creates a new field with the full name +name+ and the field type +type+.
+        def create_field(name, type)
+          parent_name, _, name = name.rpartition('.')
+          parent_field = parent_name.empty? ? nil : field_by_name(parent_name)
+          if !parent_name.empty? && !parent_field
+            raise HexaPDF::Error, "Parent field '#{parent_name}' not found"
+          end
+
+          field = document.add({FT: type, T: name, Parent: parent_field},
+                               type: :XXAcroFormField, subtype: type)
+          if parent_field
+            (parent_field[:Kids] ||= []) << field
+          else
+            (self[:Fields] ||= []) << field
+          end
+          field
+        end
+
+        def perform_validation # :nodoc:
+          if (da = self[:DA])
+            unless self[:DR]
+              yield("When the field /DA is present, the field /DR must also be present")
+            end
+            font_name = nil
+            HexaPDF::Content::Parser.parse(da) do |obj, params|
+              font_name = params[0] if obj == :Tf
+            end
+            if font_name && !(self[:DR][:Font] && self[:DR][:Font][font_name])
+              yield("The font specified in /DA is not in the /DR resource dictionary")
+            end
+          else
+            set_default_appearance_string
+          end
+
+          create_appearances if document.config['acro_form.create_appearances']
+        end
+
       end
 
     end