hexapdf 0.11.9 → 0.13.0

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

@@ -0,0 +1,187 @@
+# -*- 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")
+            return
+          end
+          if (max_len = self[:MaxLen]) && field_value && 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

data/lib/hexapdf/type/action.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

data/lib/hexapdf/type/actions.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

data/lib/hexapdf/type/actions/go_to.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

data/lib/hexapdf/type/actions/go_to_r.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

data/lib/hexapdf/type/actions/launch.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

data/lib/hexapdf/type/actions/uri.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
@@ -53,9 +53,10 @@ module HexaPDF
 
         def perform_validation #:nodoc:
           super
-          unless self[:URI].ascii_only?
+          uri = self[:URI]
+          if uri && !uri.ascii_only?
             yield("URIs have to contain ASCII characters only", true)
-            uri = self[:URI].dup.force_encoding(Encoding::BINARY)
+            uri = uri.dup.force_encoding(Encoding::BINARY)
             uri.encode!(Encoding::US_ASCII, fallback: lambda {|c| "%#{c.ord.to_s(16).upcase}" })
             self[:URI] = uri
           end

data/lib/hexapdf/type/annotation.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
@@ -46,6 +46,54 @@ module HexaPDF
     # See: PDF1.7 s12.5
     class Annotation < Dictionary
 
+      # The appearance dictionary references appearance streams for various use cases.
+      #
+      # Each appearance can either be an XObject or a dictionary mapping names to XObjects. The
+      # latter is used when the appearance depends on the state of the annotation, e.g. a check box
+      # widget that can be checked or unchecked.
+      #
+      # See: PDF1.7 s12.5.5
+      class AppearanceDictionary < Dictionary
+
+        define_type :XXAppearanceDictionary
+
+        define_field :N, type: [Dictionary, Stream], required: true
+        define_field :R, type: [Dictionary, Stream]
+        define_field :D, type: [Dictionary, Stream]
+
+        # The annotation's normal appearance.
+        def normal_appearance
+          self[:N]
+        end
+
+        # The rollover appearance which should be used when the cursor is moved into the active area
+        # of the annotation without pressing a button.
+        def rollover_appearance
+          self[:R] || self[:N]
+        end
+
+        # The down appearance which should be used when the mouse button is pressed or held down
+        # inside the active area of the annotation.
+        def down_appearance
+          self[:D] || self[:N]
+        end
+
+      end
+
+      # Border style dictionary used by various annotation types.
+      #
+      # See: PDF1.7 s12.5.4
+      class Border < Dictionary
+
+        define_type :Border
+
+        define_field :Type, type: Symbol, default: type
+        define_field :W,    type: [Integer, Float], default: 1
+        define_field :S,    type: Symbol, default: :S, allowed_values: [:S, :D, :B, :I, :U]
+        define_field :D,    type: PDFArray, default: [3]
+
+      end
+
       extend Utils::BitField
 
       define_type :Annot
@@ -58,7 +106,7 @@ module HexaPDF
       define_field :NM,           type: String, version: '1.4'
       define_field :M,            type: PDFDate, version: '1.1'
       define_field :F,            type: Integer, default: 0, version: '1.1'
-      define_field :AP,           type: Dictionary, version: '1.2'
+      define_field :AP,           type: :XXAppearanceDictionary, version: '1.2'
       define_field :AS,           type: Symbol, version: '1.2'
       define_field :Border,       type: PDFArray, default: [0, 0, 1]
       define_field :C,            type: PDFArray, version: '1.1'
@@ -68,7 +116,29 @@ module HexaPDF
       bit_field(:raw_flags, {invisible: 0, hidden: 1, print: 2, no_zoom: 3, no_rotate: 4,
                              no_view: 5, read_only: 6, locked: 7, toggle_no_view: 8,
                              locked_contents: 9},
-                lister: "flags", getter: "flagged?", setter: "flag")
+                lister: "flags", getter: "flagged?", setter: "flag", unsetter: "unflag")
+
+      # Returns +true+ because annotation objects must always be indirect objects.
+      def must_be_indirect?
+        true
+      end
+
+      # Returns the AppearanceDictionary instance associated with the annotation or +nil+ if none is
+      # set.
+      def appearance
+        self[:AP]
+      end
+
+      # Returns +true+ if the widget's normal appearance exists.
+      #
+      # Note that this checks only if the appearance exists but not if the structure of the
+      # appearance dictionary conforms to the expectations of the annotation.
+      def appearance?
+        return false unless (normal_appearance = appearance&.normal_appearance)
+        normal_appearance.kind_of?(HexaPDF::Stream) ||
+          (!normal_appearance.empty? &&
+           normal_appearance.each.all? {|_k, v| v.kind_of?(HexaPDF::Stream) })
+      end
 
       private