hexapdf 0.11.9 → 0.12.0

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

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

@@ -0,0 +1,186 @@
+# -*- 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/error'
+require 'hexapdf/type/acro_form/variable_text_field'
+
+module HexaPDF
+  module Type
+    module AcroForm
+
+      # AcroForm text fields provide a box or space to fill-in data entered from keyboard. The text
+      # may be restricted to a single line or can span multiple lines.
+      #
+      # == Type Specific Field Flags
+      #
+      # :multiline:: If set, the text field may contain multiple lines.
+      #
+      # :password:: The field is a password field. This changes the behaviour of the PDF reader
+      #             application to not echo the input text and to not store it in the PDF file.
+      #
+      # :file_select:: The text field represents a file selection control where the input text is
+      #                the path to a file.
+      #
+      # :do_not_spell_check:: The text should not be spell-checked.
+      #
+      # :do_not_scroll:: The text field should not scroll (horizontally for single-line fields and
+      #                  vertically for multiline fields) to accomodate more text than fits into the
+      #                  annotation rectangle. This means that no more text can be entered once the
+      #                  field is full.
+      #
+      # :comb:: The field is divided into /MaxLen equally spaced positions (so /MaxLen needs to be
+      #         set). This is useful, for example, when entering things like social security
+      #         numbers which always have the same length.
+      #
+      # :rich_text:: The field is a rich text field.
+      #
+      # See: PDF1.7 s12.7.4.3
+      class TextField < VariableTextField
+
+        define_field :MaxLen, type: Integer
+
+        # All inheritable dictionary fields for text fields.
+        INHERITABLE_FIELDS = (superclass::INHERITABLE_FIELDS + [:MaxLen]).freeze
+
+        # Updated list of field flags.
+        FLAGS_BIT_MAPPING = superclass::FLAGS_BIT_MAPPING.merge(
+          {
+            multiline: 12,
+            password: 13,
+            file_select: 20,
+            do_not_spell_check: 22,
+            do_not_scroll: 23,
+            comb: 24,
+            rich_text: 25,
+          }
+        ).freeze
+
+        # Returns the field value, i.e. the text contents of the field, or +nil+ if no value is set.
+        #
+        # Note that modifying the returned value *might not* modify the text contents in case it is
+        # stored as stream! So always use #field_value= to set the field value.
+        def field_value
+          return unless value[:V]
+          self[:V].kind_of?(String) ? self[:V] : self[:V].stream
+        end
+
+        # Sets the field value, i.e. the text contents of the field, to the given string.
+        #
+        # Note that for single line text fields, all whitespace characters are changed to simple
+        # spaces.
+        def field_value=(str)
+          if flagged?(:password)
+            raise HexaPDF::Error, "Storing a field value for a password field is not allowed"
+          end
+          str = str.gsub(/[[:space:]]/, ' ') if concrete_field_type == :single_line_text_field
+          self[:V] = str
+          update_widgets
+        end
+
+        # Returns the default field value.
+        #
+        # See: #field_value
+        def default_field_value
+          self[:DV].kind_of?(String) ? self[:DV] : self[:DV].stream
+        end
+
+        # Sets the default field value.
+        #
+        # See: #field_value=
+        def default_field_value=(str)
+          self[:DV] = str
+        end
+
+        # Returns the concrete text field type, either :single_line_text_field,
+        # :multiline_text_field, :password_field, :file_select_field, :comb_text_field or
+        # :rich_text_field.
+        def concrete_field_type
+          if flagged?(:multiline)
+            :multiline_text_field
+          elsif flagged?(:password)
+            :password_field
+          elsif flagged?(:file_select)
+            :file_select_field
+          elsif flagged?(:comb)
+            :comb_text_field
+          elsif flagged?(:rich_text)
+            :rich_text_field
+          else
+            :single_line_text_field
+          end
+        end
+
+        # Creates appropriate appearances for all widgets.
+        #
+        # For information on how this is done see AppearanceGenerator.
+        #
+        # Note that an appearance for a text 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|
+            appearance_generator_class.new(widget).create_text_appearances
+          end
+        end
+
+        # Updates the widgets so that they reflect the current field value.
+        def update_widgets
+          create_appearances
+        end
+
+        private
+
+        def perform_validation #:nodoc:
+          if field_type != :Tx
+            yield("Field /FT of AcroForm text field has to be :Tx", true)
+            self[:FT] = :Tx
+          end
+
+          super
+
+          if self[:V] && !(self[:V].kind_of?(String) || self[:V].kind_of?(HexaPDF::Stream))
+            yield("Text field doesn't contain text but #{self[:V].class} object")
+          end
+          if (max_len = self[:MaxLen]) && field_value.length > max_len
+            yield("Text contents of field '#{full_field_name}' is too long")
+          end
+        end
+
+      end
+
+    end
+  end
+end

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

@@ -0,0 +1,122 @@
+# -*- 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/dictionary'
+require 'hexapdf/stream'
+require 'hexapdf/error'
+require 'hexapdf/content/parser'
+
+module HexaPDF
+  module Type
+    module AcroForm
+
+      # An AcroForm variable text field defines how text that it is not known at generation time
+      # should be rendered. For example, AcroForm text fields (normally) don't have an initial
+      # value; the value is entered by the user and needs to be rendered correctly by the PDF
+      # reader.
+      #
+      # See: PDF1.7 s12.7.3.3
+      class VariableTextField < Field
+
+        define_field :DA, type: String
+        define_field :Q, type: Integer, default: 0, allowed_values: [0, 1, 2]
+        define_field :DS, type: String, version: '1.5'
+        define_field :RV, type: [String, Stream], version: '1.5'
+
+        # All inheritable dictionary fields for text fields.
+        INHERITABLE_FIELDS = (superclass::INHERITABLE_FIELDS + [:DA, :Q]).freeze
+
+        UNSET_ARG = ::Object.new # :nodoc:
+
+        # :call-seq:
+        #   field.text_alignment                -> alignment
+        #   field.text_alignment(alignment)     -> field
+        #
+        # Sets or returns the text alignment that should be used when displaying text.
+        #
+        # With no argument, the current text alignment is returned. When a value is provided, the
+        # text alignment is set accordingly.
+        #
+        # The alignment value is one of :left, :center or :right.
+        def text_alignment(alignment = UNSET_ARG)
+          if alignment == UNSET_ARG
+            case self[:Q]
+            when 0 then :left
+            when 1 then :center
+            when 2 then :right
+            end
+          else
+            self[:Q] = case alignment
+                       when :left then 0
+                       when :center then 1
+                       when :right then 2
+                       else
+                         raise ArgumentError, "Invalid variable text field alignment #{alignment}"
+                       end
+          end
+        end
+
+        # Sets the 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 = document.acro_form(create: true).default_resources.
+            add_font(document.fonts.add(font).pdf_object)
+          self[:DA] = "0 g /#{name} #{font_size} Tf"
+        end
+
+        # Parses the default appearance string and returns an array containing [font_name,
+        # font_size].
+        #
+        # The default appearance string is taken from the field or, if not set, the default
+        # appearance string of the form.
+        def parse_default_appearance_string
+          da = self[:DA] || (document.acro_form && document.acro_form[:DA])
+          raise HexaPDF::Error, "No default appearance string set" unless da
+
+          font_params = nil
+          HexaPDF::Content::Parser.parse(da) do |obj, params|
+            font_params = params.dup if obj == :Tf
+          end
+          font_params
+        end
+
+      end
+
+    end
+  end
+end