hexapdf 0.11.9 → 0.12.0

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

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
 

data/lib/hexapdf/type/annotations.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/annotations/link.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,7 +53,7 @@ module HexaPDF
                                   version: '1.2'
         define_field :PA,         type: Dictionary, version: '1.3'
         define_field :QuadPoints, type: PDFArray, version: '1.6'
-        define_field :BS,         type: Dictionary, version: '1.6'
+        define_field :BS,         type: :Border, version: '1.6'
 
       end
 

data/lib/hexapdf/type/annotations/markup_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

data/lib/hexapdf/type/annotations/text.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/annotations/widget.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,6 +35,8 @@
 #++
 
 require 'hexapdf/type/annotation'
+require 'hexapdf/content'
+require 'hexapdf/serializer'
 
 module HexaPDF
   module Type
@@ -80,9 +82,244 @@ module HexaPDF
         define_field :MK,      type: :XXAppearanceCharacteristics
         define_field :A,       type: Dictionary, version: '1.1'
         define_field :AA,      type: Dictionary, version: '1.2'
-        define_field :BS,      type: Dictionary, version: '1.2'
+        define_field :BS,      type: :Border, version: '1.2'
         define_field :Parent,  type: Dictionary
 
+        # Returs the AcroForm field object to which this widget annotation belongs.
+        #
+        # Since a widget and a field can share the same dictionary object, the returned object is
+        # often just the widget re-wrapped in the correct field class.
+        def form_field
+          field = if key?(:Parent) &&
+                      (tmp = document.wrap(self[:Parent], type: :XXAcroFormField)).terminal_field?
+                    tmp
+                  else
+                    document.wrap(self, type: :XXAcroFormField)
+                  end
+          document.wrap(field, type: :XXAcroFormField, subtype: field[:FT])
+        end
+
+        # :call-seq:
+        #   widget.background_color                => background_color or nil
+        #   widget.background_color(*color)        => widget
+        #
+        # Returns the current background color as device color object, or +nil+ if no background
+        # color is set, when no argument is given. Otherwise sets the background color using the
+        # +color+ argument and returns self.
+        #
+        # See HexaPDF::Content::ColorSpace.device_color_from_specification for information on the
+        # allowed arguments.
+        def background_color(*color)
+          if color.empty?
+            components = self[:MK]&.[](:BG)
+            components.nil? ? nil : Content::ColorSpace.prenormalized_device_color(components)
+          else
+            color = Content::ColorSpace.device_color_from_specification(color)
+            (self[:MK] ||= {})[:BG] = color.components
+            self
+          end
+        end
+
+        # Describes the border of an annotation.
+        #
+        # The +color+ property is either +nil+ if the border is transparent or else a device color
+        # object - see HexaPDF::Content::ColorSpace.
+        #
+        # The +style+ property can be one of the following:
+        #
+        # :solid::      Solid line.
+        # :beveled::    Embossed rectangle seemingly raised above the surface of the page.
+        # :inset::      Engraved rectangle receeding into the page.
+        # :underlined:: Underlined, i.e. only the bottom border is draw.
+        # Array:        Dash array describing how to dash the line.
+        BorderStyle = Struct.new(:width, :color, :style, :horizontal_corner_radius,
+                                 :vertical_corner_radius)
+
+        # :call-seq:
+        #   widget.border_style                                      => border_style
+        #   widget.border_style(color: 0, width: 1, style: :solid)   => widget
+        #
+        # Returns a BorderStyle instance representing the border style of the widget when no
+        # argument is given. Otherwise sets the border style of the widget and returns self.
+        #
+        # When setting a border style, arguments that are not provided will use the default: a
+        # border with a solid, black, 1pt wide line. This also means that multiple invocations will
+        # reset *all* prior values.
+        #
+        # +color+:: The color of the border. See
+        #           HexaPDF::Content::ColorSpace.device_color_from_specification for information on
+        #           the allowed arguments.
+        #
+        #           If the special value +:transparent+ is used when setting the color, a
+        #           transparent is used. A transparent border will return a +nil+ value when getting
+        #           the border color.
+        #
+        # +width+:: The width of the border. If set to 0, no border is shown.
+        #
+        # +style+:: Defines how the border is drawn. can be one of the following:
+        #
+        #           +:solid+::      Draws a solid border.
+        #           +:beveled+::    Draws a beveled border.
+        #           +:inset+::      Draws an inset border.
+        #           +:underlined+:: Draws only the bottom border.
+        #           Array::         An array specifying a line dash pattern (see
+        #                           HexaPDF::Content::LineDashPattern)
+        def border_style(color: nil, width: nil, style: nil)
+          if color || width || style
+            color = if color == :transparent
+                      []
+                    else
+                      Content::ColorSpace.device_color_from_specification(color || 0).components
+                    end
+            width ||= 1
+            style ||= :solid
+
+            (self[:MK] ||= {})[:BC] = color
+            bs = self[:BS] = {W: width}
+            case style
+            when :solid then bs[:S] = :S
+            when :beveled then bs[:S] = :B
+            when :inset then bs[:S] = :I
+            when :underlined then bs[:S] = :U
+            when Array
+              bs[:S] = :D
+              bs[:D] = style
+            else
+              raise ArgumentError, "Unknown value #{style} for style argument"
+            end
+            self
+          else
+            result = BorderStyle.new(1, nil, :solid, 0, 0)
+            if (ac = self[:MK]) && (bc = ac[:BC]) && !bc.empty?
+              result.color = Content::ColorSpace.prenormalized_device_color(bc.value)
+            end
+
+            if (bs = self[:BS])
+              result.width = bs[:W] if bs.key?(:W)
+              result.style = case bs[:S]
+                             when :S then :solid
+                             when :B then :beveled
+                             when :I then :inset
+                             when :U then :underlined
+                             when :D then bs[:D].value
+                             else :solid
+                             end
+            elsif key?(:Border)
+              border = self[:Border]
+              result.horizontal_corner_radius = border[0]
+              result.vertical_corner_radius = border[1]
+              result.width = border[2]
+              result.style = border[3] if border[3]
+            end
+
+            result
+          end
+        end
+
+        # Describes the marker style of a check box or radio button widget.
+        class MarkerStyle
+
+          # The kind of marker that is shown inside the widget. Can either be one of the symbols
+          # +:check+, +:circle+, +:cross+, +:diamond+, +:square+ or +:star+, or a one character
+          # string. The latter is interpreted using the ZapfDingbats font.
+          attr_reader :style
+
+          # The size of the marker in PDF points that is shown inside the widget. The special value
+          # 0 means that the marker should be auto-sized based on the widget's rectangle.
+          attr_reader :size
+
+          # A device color object representing the color of the marker - see
+          # HexaPDF::Content::ColorSpace.
+          attr_reader :color
+
+          # Creates a new instance with the given values.
+          def initialize(style, size, color)
+            @style = style
+            @size = size
+            @color = color
+          end
+
+        end
+
+        # :call-seq:
+        #   widget.marker_style                                     => marker_style
+        #   widget.marker_style(style: nil, size: nil, color: nil)   => widget
+        #
+        # Returns a MarkerStyle instance representing the marker style of the widget when no
+        # argument is given. Otherwise sets the button marker style of the widget and returns self.
+        #
+        # This method returns valid information only for check boxes and radio buttons!
+        #
+        # When setting a marker style, arguments that are not provided will use the default: a black
+        # auto-sized checkmark (i.e. :check for for check boxes) or circle (:circle for radio
+        # buttons). This also means that multiple invocations will reset *all* prior values.
+        #
+        # Note: The marker is called "normal caption" in the PDF 1.7 spec and the /CA entry of the
+        # associated appearance characteristics dictionary. The marker size and color are set using
+        # the /DA key on the widget (although /DA is not defined for widget, this is how Acrobat
+        # does it).
+        #
+        # See: PDF1.7 s12.5.6.19 and s17.7.3.3
+        def marker_style(style: nil, size: nil, color: nil)
+          field = form_field
+          if style || size || color
+            style ||= (field.check_box? ? :check : :cicrle)
+            size ||= 0
+            color = Content::ColorSpace.device_color_from_specification(color || 0)
+
+            self[:MK] ||= {}
+            self[:MK][:CA] = case style
+                             when :check   then '4'
+                             when :circle  then 'l'
+                             when :cross   then '8'
+                             when :diamond then 'u'
+                             when :square  then 'n'
+                             when :star    then 'H'
+                             when String   then style
+                             else
+                               raise ArgumentError, "Unknown value #{style} for argument 'style'"
+                             end
+            operator = case color.color_space.family
+                       when :DeviceRGB then :rg
+                       when :DeviceGray then :g
+                       when :DeviceCMYK then :k
+                       end
+            serialized_color = Content::Operator::DEFAULT_OPERATORS[operator].
+              serialize(HexaPDF::Serializer.new, *color.components)
+            self[:DA] = "/ZaDb #{size} Tf #{serialized_color}".strip
+          else
+            style = case self[:MK]&.[](:CA)
+                    when '4' then :check
+                    when 'l' then :circle
+                    when '8' then :cross
+                    when 'u' then :diamond
+                    when 'n' then :square
+                    when 'H' then :star
+                    when String then self[:MK][:CA]
+                    else
+                      if field.check_box?
+                        :check
+                      else
+                        :circle
+                      end
+                    end
+            size = 0
+            color = [0]
+            if (da = self[:DA] || field[:DA])
+              HexaPDF::Content::Parser.parse(da) do |obj, params|
+                if obj == :rg || obj == :g || obj == :k
+                  color = params.dup
+                elsif obj == :Tf
+                  size = params[1]
+                end
+              end
+            end
+            color = HexaPDF::Content::ColorSpace.prenormalized_device_color(color)
+
+            MarkerStyle.new(style, size, color)
+          end
+        end
+
       end
 
     end