hexapdf 0.11.9 → 0.12.0

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

@@ -0,0 +1,220 @@
+# -*- 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-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
+# 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/acro_form/variable_text_field'
+require 'hexapdf/type/acro_form/appearance_generator'
+
+module HexaPDF
+  module Type
+    module AcroForm
+
+      # AcroForm choice fields contain multiple text items of which one (or, if so flagged, more)
+      # may be selected.
+      #
+      # They are divided into scrollable list boxes and combo boxes. To create a list or combo box,
+      # use the appropriate convenience methods on the main Form instance
+      # (HexaPDF::Document#acro_form). By using those methods, everything needed is automatically
+      # set up.
+      #
+      # == Type Specific Field Flags
+      #
+      # :combo:: If set, the field represents a comb box.
+      #
+      # :edit:: If set, the combo box includes an editable text box for entering arbitrary values.
+      #         Therefore the 'combo' flag also needs to be set.
+      #
+      # :sort:: The option items have to be sorted alphabetically. This flag is intended for PDF
+      #         writers, not readers which should display the items in the order they appear.
+      #
+      # :multi_select:: If set, more than one item may be selected.
+      #
+      # :do_not_spell_check:: The text should not be spell-checked.
+      #
+      # :commit_on_sel_change:: If set, a new value should be commited as soon as a selection is
+      #                         made.
+      #
+      # See: PDF1.7 s12.7.4.4
+      class ChoiceField < VariableTextField
+
+        define_field :Opt, type: PDFArray
+        define_field :TI, type: Integer, default: 0
+        define_field :I, type: PDFArray, version: '1.4'
+
+        # Updated list of field flags.
+        FLAGS_BIT_MAPPING = superclass::FLAGS_BIT_MAPPING.merge(
+          {
+            combo: 17,
+            edit: 18,
+            sort: 19,
+            multi_select: 21,
+            do_not_spell_check: 22,
+            commit_on_sel_change: 26,
+          }
+        ).freeze
+
+        # Initializes the choice field to be a list box.
+        #
+        # This method should only be called directly after creating a new choice field because it
+        # doesn't completely reset the object.
+        def initialize_as_list_box
+          self[:V] = nil
+          unflag(:combo)
+        end
+
+        # Initializes the button field to be a combo box.
+        #
+        # This method should only be called directly after creating a new choice field because it
+        # doesn't completely reset the object.
+        def initialize_as_combo_box
+          self[:V] = nil
+          flag(:combo)
+        end
+
+        # Returns +true+ if this choice field represents a list box.
+        def list_box?
+          !combo_box?
+        end
+
+        # Returns +true+ if this choice field represents a combo box.
+        def combo_box?
+          flagged?(:combo)
+        end
+
+        # Returns the field value which represents the currently selected item(s).
+        #
+        # If no item is selected, +nil+ is returned. If multiple values are selected, the return
+        # value is an array of strings, otherwise it is just a string.
+        def field_value
+          process_value(self[:V])
+        end
+
+        # Sets the field value to the given string or array of strings.
+        def field_value=(value)
+          items = option_items
+          all_included = [value].flatten.all? {|v| items.include?(v) }
+          self[:V] = if (combo_box? && value.kind_of?(String) &&
+                          (flagged?(:edit) || all_included)) ||
+                         (list_box? && all_included &&
+                          (value.kind_of?(String) || flagged?(:multi_select)))
+                       value
+                     else
+                       @document.config['acro_form.on_invalid_value'].call(self, value)
+                     end
+        end
+
+        # Returns the default field value.
+        #
+        # See: #field_value
+        def default_field_value
+          process_value(self[:DV])
+        end
+
+        # Sets the default field value.
+        #
+        # See: #field_value=
+        def default_field_value=(value)
+          items = option_items
+          self[:DV] = if [value].flatten.all? {|v| items.include?(v) }
+                       value
+                     else
+                       @document.config['acro_form.on_invalid_value'].call(self, value)
+                     end
+        end
+
+        # Returns the array with the available option items.
+        def option_items
+          key?(:Opt) ? process_value(self[:Opt]) : self[:Opt] ||= []
+        end
+
+        # Sets the array with the available option items to the given value.
+        def option_items=(value)
+          self[:Opt] = value
+        end
+
+        # Returns the concrete choice field type, either :list_box, :combo_box or
+        # :editable_combo_box.
+        def concrete_field_type
+          if combo_box?
+            flagged?(:edit) ? :editable_combo_box : :combo_box
+          else
+            :list_box
+          end
+        end
+
+        # Creates appropriate appearances for all widgets if they don't already exist.
+        #
+        # For information on how this is done see AppearanceGenerator.
+        #
+        # Note that an appearance for a choice field widget is *always* created even if there is an
+        # existing one to make sure the current field value is properly represented.
+        def create_appearances
+          appearance_generator_class = document.config.constantize('acro_form.appearance_generator')
+          each_widget do |widget|
+            if combo_box?
+              appearance_generator_class.new(widget).create_combo_box_appearances
+            else
+              raise HexaPDF::Error, "List boxes not yet supported"
+            end
+          end
+        end
+
+        private
+
+        # Uses the HexaPDF::DictionaryFields::StringConverter to process the value (a string or an
+        # array of strings) so that it contains only normalized strings.
+        def process_value(value)
+          value = value.value if value.kind_of?(PDFArray)
+          if value.kind_of?(Array)
+            value.map! {|item| DictionaryFields::StringConverter.convert(item, nil, nil) || item }
+          else
+            DictionaryFields::StringConverter.convert(value, nil, nil) || value
+          end
+        end
+
+        def perform_validation #:nodoc:
+          if field_type != :Ch
+            yield("Field /FT of AcroForm choie field has to be :Ch", true)
+            self[:FT] = :Ch
+          end
+
+          super
+        end
+
+      end
+
+    end
+  end
+end

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?