org.faceless.pdf2

## Class FormBarCode

- java.lang.Object
- - org.faceless.pdf2.FormElement
  - - org.faceless.pdf2.FormBarCode

- All Implemented Interfaces:
    Cloneable

      public final class FormBarCode
      extends FormElement

  A type of form element representing a BarCode. Barcode fields were added to Acrobat 7 as part of the XFA standard, and although they only became an official part of PDF as of PDF 2.0 (ISO-32000-2) they should be usable in Acrobat 7 or later (although they may not be usable in other PDF viewers).

  Barcode fields are typically used to represent the contents of other fields in the form, the idea being that if the form is printed rather than electronically submitted, the BarCode can be scanned to retrieve the form contents. The way to do this is by adding an `Event.OTHERCHANGE` action to the field to recalculate its value based on the other fields (although there should be other ways to do this, they're unlikely to work in Acrobat so this is the only recommended approach).

  Here's a very simple example:

       // create main form elements and add to form
       form.put("Name", namefield);
       form.put("Address", addressfield);

       String js = "var fields = [ 'Name', 'Address' ]; \
                    var val = ''; \
                    for (var f=0;f<fields.length;f++) { \
                      val = this.getField(fields[i]).value + '\t'; \
                    } \
                    event.value = val;";
       FormBarCode barcode = new FormBarCode();
       barcode.setSymbology("QRCode");
       barcode.setECC(1);
       barcode.setSymbolSize(0.5f);
       barcode.addAnnotation(page, 100, 100, 150, 150);
       barcode.setAction(Event.OTHERCHANGE, PDFAction.formJavaScript(js));
       barcode.setValue(namefield.getValue()+"\t"+addressfield.getValue());
       form.put("BarCode", barcode);

  Since:
    2.11.24

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static int` | `COMPRESSION_ADOBE` Barcode is Flate-compressed, with Adobe's "special sauce" - a two byte prefix of unknown purpose.
    `static int` | `COMPRESSION_FLATE` Barcode is Flate-compressed, without any prefix.
    `static int` | `COMPRESSION_NONE` Barcode is encoded with a value that is not compressed.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `FormBarCode()` Create a new BarCode field
    `FormBarCode(PDFPage page, float x1, float y1, float x2, float y2)` Create a new BarCode field and add an annotation for it to the page

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `WidgetAnnotation` | `addAnnotation(PDFPage page, float x1, float y1, float x2, float y2)` Create and add a new widget annotation for this field.
    `int` | `getCompression()` Returns the type of compression the field is stored with, as specified by `setCompression(int)`
    `int` | `getECC()` Return the error correction level, as set by `setECC(int)`
    `String` | `getSymbology()` Return the BarCode symbology as set by `setSymbology(java.lang.String)`
    `float` | `getSymbolSize()` Return the symbol size, as set by `setSymbolSize(float)`
    `static String` | `getTabDelimiteredJavaScript(Collection<String> names, boolean includenames)` Return the JavaScript used by Acrobat to set a BarCode to a tab-delimetered list of field names.
    `static String` | `getTabDelimiteredJavaScriptSetup()` If using the JavaScript returned by `getTabDelimiteredJavaScript(java.util.Collection<java.lang.String>, boolean)`, you must apply the JavaScript return by this method to the PDF, as in the following example:
         String js = FormBarCode.getTabDelimiteredJavaScript(Arrays.asList(new String[] { "Name", "Address" }), true);
         barcode.setAction(Event.OTHERCHANGE, PDFAction.formJavaScript(js));
         form.addElement("BarCode", barcode);
         pdf.setJavaScript(pdf.getJavaScript() + FormBarCode.getTabDelimiteredJavaScriptSetup());
    `String` | `getValue()` Returns the value of this field
    `void` | `rebuild()` Cause the annotation list to be rebuilt.
    `void` | `setCompression(int compression)` Set whether the BarCode value should be compressed by Flate compreesion first.
    `void` | `setECC(int ecc)` Sets the error correction coefficient (PDF417 and QRCode only).
    `void` | `setSymbology(String symbology)` Sets the type of BarCode symbology
    `void` | `setSymbolSize(float mm)` Set the symbol size in mm - this is the size of the smallest unit in the BarCode, and is typically in the region of 0.5 to 1.
    `void` | `setValue(String value)` Sets the value of this field
    `String` | `toString()`

    - ### Methods inherited from class org.faceless.pdf2.FormElement

      `addPropertyChangeListener, duplicate, flatten, getAction, getAnnotation, getAnnotations, getDescription, getForm, isReadOnly, isRequired, isSubmitted, removePropertyChangeListener, setAction, setDescription, setReadOnly, setRequired, setSubmitted`

    - ### Methods inherited from class java.lang.Object

      `equals, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- - ### Field Detail

    - #### COMPRESSION_NONE

          public static final int COMPRESSION_NONE

      Barcode is encoded with a value that is not compressed.
      See Also:
        Constant Field Values

    - #### COMPRESSION_ADOBE

          public static final int COMPRESSION_ADOBE

      Barcode is Flate-compressed, with Adobe's "special sauce" - a two byte prefix of unknown purpose. Use this for BarCodes that will be updated by Acrobat.
      See Also:
        Constant Field Values

    - #### COMPRESSION_FLATE

          public static final int COMPRESSION_FLATE

      Barcode is Flate-compressed, without any prefix. Not compatible with Acrobat, but useful for documents edited only with our PDF Viewer.
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### FormBarCode

          public FormBarCode()

      Create a new BarCode field

    - #### FormBarCode

          public FormBarCode(PDFPage page,
                             float x1,
                             float y1,
                             float x2,
                             float y2)

      Create a new BarCode field and add an annotation for it to the page
      Parameters:
        `page` - the page for the widget
        `x1` - the left-most X co-ordinate of the annotation
        `y1` - the bottom-most Y co-ordinate of the annotation
        `x2` - the right-most X co-ordinate of the annotation
        `y2` - the top-most Y co-ordinate of the annotation

  - ### Method Detail

    - #### addAnnotation

          public WidgetAnnotation addAnnotation(PDFPage page,
                                                float x1,
                                                float y1,
                                                float x2,
                                                float y2)

      Create and add a new widget annotation for this field.
      Parameters:
        `page` - the page for the widget
        `x1` - the left-most X co-ordinate of the annotation
        `y1` - the bottom-most Y co-ordinate of the annotation
        `x2` - the right-most X co-ordinate of the annotation
        `y2` - the top-most Y co-ordinate of the annotation

    - #### getValue

          public String getValue()

      Returns the value of this field
      Specified by:
        `getValue` in class `FormElement`

    - #### setValue

          public void setValue(String value)

      Sets the value of this field
      Parameters:
        `value` - the new value

    - #### setCompression

          public void setCompression(int compression)

      Set whether the BarCode value should be compressed by Flate compreesion first. This is slightly non-standard and unlikely to work with many BarCode readers.
      See Also:
        `COMPRESSION_NONE`, `COMPRESSION_FLATE`, `COMPRESSION_ADOBE`

    - #### setSymbology

          public void setSymbology(String symbology)

      Sets the type of BarCode symbology
      Parameters:
        `symbology` - one of `PDF417`, `QRCode`, or `DataMatrix`

    - #### setSymbolSize

          public void setSymbolSize(float mm)

      Set the symbol size in mm - this is the size of the smallest unit in the BarCode, and is typically in the region of 0.5 to 1. Note that we expect the value in mm, which is the units we use in the `BarCode` class, whereas Acrobat's UI asks for the units in points: for conversion, 2.8mm = 1pt.
      Parameters:
        `mm` - the size of the smallest unit in the BarCode, in mm
      See Also:
        `getSymbolSize()`

    - #### setECC

          public void setECC(int ecc)

      Sets the error correction coefficient (PDF417 and QRCode only). For PDF417 the value shall be from 0 to 8. For QRCode it shall be from 0 to 3 (0 for 'L', 1 for 'M', 2 for 'Q', and 3 for 'H').
      Parameters:
        `ecc` - the error correction coefficient

    - #### getSymbology

          public String getSymbology()

      Return the BarCode symbology as set by `setSymbology(java.lang.String)`

    - #### getECC

          public int getECC()

      Return the error correction level, as set by `setECC(int)`

    - #### getSymbolSize

          public float getSymbolSize()

      Return the symbol size, as set by `setSymbolSize(float)`
      See Also:
        `setSymbolSize(float)`

    - #### getCompression

          public int getCompression()

      Returns the type of compression the field is stored with, as specified by `setCompression(int)`

    - #### rebuild

          public void rebuild()

      Description copied from class: `FormElement`
      Cause the annotation list to be rebuilt. Unless you're rendering the annotation using the viewer, it's not necessary to call this method.
      Overrides:
        `rebuild` in class `FormElement`

    - #### getTabDelimiteredJavaScript

          public static String getTabDelimiteredJavaScript(Collection<String> names,
                                                           boolean includenames)

      Return the JavaScript used by Acrobat to set a BarCode to a tab-delimetered list of field names. For example, to include the fields "name" and "address" in the barcode, you could use the following:

           FormBarCode barcode = new FormBarCode();
           String js = FormBarCode.getTabDelimiteredJavaScript(Arrays.asList(new String[] {"Name, "Address"}), false);
           barcode.setAction(Event.OTHERCHANGE, PDFAction.formJavaScript(code));
           pdf.setJavaScript(pdf.getJavaScript() + FormBarCode.getTabDelimiteredJavaScriptSetup());

      Note that although this is the approach used by Acrobat, the generated JavaScript is a mess and you could probably do better yourself - there's no reason to rely on this JavaScript, and it's here for convenience only.
      Parameters:
        `names` - the list of field names to include in the barcode value, or null for all fields
        `includenames` - whether to include the list of field names in the value
      See Also:
        `getTabDelimiteredJavaScriptSetup()`

    - #### getTabDelimiteredJavaScriptSetup

          public static String getTabDelimiteredJavaScriptSetup()

      If using the JavaScript returned by `getTabDelimiteredJavaScript(java.util.Collection<java.lang.String>, boolean)`, you must apply the JavaScript return by this method to the PDF, as in the following example:

           String js = FormBarCode.getTabDelimiteredJavaScript(Arrays.asList(new String[] { "Name", "Address" }), true);
           barcode.setAction(Event.OTHERCHANGE, PDFAction.formJavaScript(js));
           form.addElement("BarCode", barcode);
           pdf.setJavaScript(pdf.getJavaScript() + FormBarCode.getTabDelimiteredJavaScriptSetup());

      See Also:
        `getTabDelimiteredJavaScript(java.util.Collection<java.lang.String>, boolean)`

    - #### toString

          public String toString()

Copyright © 2001-2015 Big Faceless Organization