prawn-forms 0.1

data/README.markdown

@@ -0,0 +1,67 @@
+# prawn-forms
+
+## Overview
+
+This is the beginnings of a prawn extension for adding interactive forms to
+PDFs.
+
+## Installation
+
+    gem install prawn-forms
+
+## Usage
+
+Prawn-Forms depends on the core prawn library, and simply adds a few additional
+methods to the standard Prawn::Document object that allow you to add form elements
+to your output.
+
+Start by requiring the prawn library, then the prawn-forms library. Build your PDF as usual,
+and use methods like text_field() to add a free text input box.
+
+    require 'prawn'
+    require 'prawn/forms'
+
+    Prawn::Document.generate "form.pdf" do |pdf|
+      pdf.text_field("fname", 100, 560, 200, 16)
+    end
+
+For further examples and documentation, check out the examples/ directory of this project
+and the code docs for the Prawn::Forms module.
+
+## Technical Discussion
+
+Interactive forms are primarily defined by section 8.6 the PDF spec. The visual
+appearance of fields is controlled using widget annotations, defined in section
+8.4.5.
+
+A PDF can contain *one* form.
+
+The form is defined by a dict linked via the AcroForm entry in the root
+catalog. Amongst other entries, the form dict has a Fields entry that holds an
+array of all the form fields. The array should be indirect references to a
+dicts, generally one per field.
+
+Each field dict can link to one or more widget annotations that define the visual
+appearance in various states. It seems most fields have a single widget
+annotation, in which case it is permitted to merge the field and annotation
+dicts into a single dict. Annotation and field dicts have no common keys, so
+there is no conflict.
+
+For the fields to appear on the page, the widget annotation (or merged
+field/widget dict) must appear in the page Annots entry.
+
+## Disclaimer
+
+This code is still very much experimental and is not recommended for use in
+production systems.
+
+## Licensing
+
+This library is distributed under the terms of the MIT License. See the included file for
+more detail.
+
+## Further Reading
+
+- The source: [http://github.com/yob/prawn-js/tree/master](http://github.com/yob/prawn-forms/tree/master)
+- Prawn source: [http://github.com/sandal/prawn/tree/master](http://github.com/sandal/prawn/tree/master)
+- Rubyforge: [http://rubyforge.org/projects/prawn](http://rubyforge.org/projects/prawn)

data/lib/prawn/forms.rb

@@ -0,0 +1,100 @@
+# encoding: utf-8
+#
+# forms.rb : Interactive form support for prawn
+#
+# Copyright August 2009, James Healy. All Rights Reserved.
+#
+# This is free software. Please see the LICENSE file for details.
+
+module Prawn
+  module Forms
+
+    def button(text)
+      add_interactive_field(:Btn, :T => Prawn::Core::LiteralString.new(text),
+                                  :DA => Prawn::Core::LiteralString.new("/Helv 0 Tf 0 g"),
+                                  :F => 4,
+                                  :Ff => 65536,
+                                  :MK => {:CA => Prawn::Core::LiteralString.new(text), :BG => [0.75294, 0.75294, 0.75294], :BC => [0.75294, 0.75294, 0.75294]},
+                                  :Rect => [304.5, 537.39, 429, 552.39])
+
+    end
+
+    def text_field(name, x, y, w, h, opts = {})
+      x, y = map_to_absolute(x, y)
+
+      field_dict = {:T => Prawn::Core::LiteralString.new(name),
+                    :DA => Prawn::Core::LiteralString.new("/Helv 0 Tf 0 g"),
+                    :F => 4,
+                    :Ff => flags_from_options(opts),
+                    :BS => {:Type => :Border, :W => 1, :S => :S},
+                    :MK => {:BC => [0, 0, 0]},
+                    :Rect => [x, y, x + w, y - h]}
+
+      if opts[:default]
+        field_dict[:V] = Prawn::Core::LiteralString.new(opts[:default])
+      end
+
+      add_interactive_field(:Tx, field_dict)
+    end
+
+    private
+
+    def add_interactive_field(type, opts = {})
+      defaults = {:FT => type, :Type => :Annot, :Subtype => :Widget}
+      annotation = ref!(opts.merge(defaults))
+      acroform.data[:Fields] << annotation
+      state.page.dictionary.data[:Annots] ||= []
+      state.page.dictionary.data[:Annots] << annotation
+    end
+
+    # The AcroForm dictionary (PDF spec 8.6) for this document. It is
+    # lazily initialized, so that documents that do not use interactive
+    # forms do not incur the additional overhead.
+    def acroform
+      state.store.root.data[:AcroForm] ||= 
+        ref!({:DR => acroform_resources, 
+              :DA => Prawn::Core::LiteralString.new("/Helv 0 Tf 0 g"),
+              :Fields => []})
+    end
+
+    # a resource dictionary for interactive forms. At a minimum,
+    # must contain the font we want to use
+    def acroform_resources
+      helv = ref!(:Type     => :Font,
+                  :Subtype  => :Type1,
+                  :BaseFont => :Helvetica,
+                  :Encoding => :WinAnsiEncoding)
+      ref!(:Font => {:Helv => helv})
+    end
+
+    # Returns the integer value for the /Ff (flags) entry in the field
+    # dictionary, based on the options provided.
+    #
+    def flags_from_options(opts)
+      flags = 0
+
+      flags |= 1<<12 if opts[:multiline]
+      flags |= 1<<13 if opts[:password]
+
+      if opts[:file_select]
+        min_version 1.4
+        flags |= 1<<20
+      end
+
+      if opts[:do_not_spell_check]
+        min_version 1.4
+        flags |= 1<<22
+      end
+
+      if opts[:do_not_scroll]
+        min_version 1.4
+        flags |= 1<<23
+      end
+
+      flags
+    end
+  end
+end
+
+require 'prawn/document'
+Prawn::Document.send(:include, Prawn::Forms)

metadata

@@ -0,0 +1,50 @@
+--- !ruby/object:Gem::Specification
+name: prawn-forms
+version: !ruby/object:Gem::Version
+  version: '0.1'
+  prerelease: 
+platform: ruby
+authors:
+- Brad Ediger
+- James Healy
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-06-16 00:00:00.000000000 Z
+dependencies: []
+description: This is the beginnings of a prawn extension for adding interactive forms
+  to PDFs.
+email: ''
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/prawn/forms.rb
+- README.markdown
+homepage: https://github.com/yob/prawn-forms
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.29
+signing_key: 
+specification_version: 3
+summary: This is the beginnings of a prawn extension for adding interactive forms
+  to PDFs.
+test_files: []
+has_rdoc: