Package com.pdftools.sign

Class Appearance

java.lang.Object
com.pdftools.internal.NativeBase
com.pdftools.internal.NativeObject
com.pdftools.sign.Appearance
public class Appearance extends NativeObject

The visual appearance of signatures

A signature may have a visual appearance on a page of the document. The visual appearance is optional and has no effect on the validity of the signature. Because of this and because a visual appearance may cover important content of the page, it is recommended to create invisible signatures by default.

Typically, a visual appearance is created for forms with a dedicated area reserved for the appearance. Other transaction documents, e.g. invoices, correspondence, or bank statements, are usually signed without a visual appearance.

The appearance can be positioned on a page using getPageNumber(), getTop(), getRight(), getBottom(), and getLeft(). It is recommended to set either getTop() or getBottom() and getRight() or getLeft(). If all are null, the default is to position the appearance in the lower right corner with 12 pt (1/6 inch or 4.2 mm) distance to the bottom and right edge of the page, i.e. Bottom = 12 and Right = 12.

  • Method Details

    • createFromJson

      public static Appearance createFromJson(Stream stream) throws NotFoundException, GenericException, CorruptException, ProcessingException

      Create an appearance with the content loaded from a JSON file

      The format of the JSON file is described in the user manual.
      Parameters:
      stream - The JSON file defining the content
      Returns:
      Throws:
      CorruptException - The file is not a valid JSON file.
      NotFoundException - An image or font referenced in the JSON was not found.
      GenericException - The JSON file is not a valid appearance content specification.
      ProcessingException - Could not process content of the JSON.
      IllegalArgumentException - if stream is null

    • createFromXml

      public static Appearance createFromXml(Stream stream) throws NotFoundException, GenericException, CorruptException, ProcessingException

      Create an appearance with the content loaded from an XML file

      The format of the XML file is described in the user manual.
      Parameters:
      stream - The XML file defining the content
      Returns:
      Throws:
      CorruptException - The file is not a valid XML file.
      NotFoundException - An image or font referenced in the XML was not found.
      GenericException - The XML file is not a valid appearance content specification.
      ProcessingException - Could not process content of the XML.
      IllegalArgumentException - if stream is null

    • createFieldBoundingBox

      public static Appearance createFieldBoundingBox(Size size)

      Create the bounding box for an unsigned signature field

      Unsigned signature fields can define a rectangle on a page. When the field is signed, the signer creates a visual appearance within that rectangle.
      Parameters:
      size - The size of the rectangle
      Returns:
      Throws:
      IllegalArgumentException - if size is null

    • getPageNumber

      public Integer getPageNumber()

      The number of the page where the appearance is positioned (Getter)

      Page number must be in the range from 1 to pdftools.pdf.Document.getPageCount.

      If null, the appearance is positioned on the last page.

      Default: null

    • setPageNumber

      public void setPageNumber(Integer value)

      The number of the page where the appearance is positioned (Setter)

      Page number must be in the range from 1 to pdftools.pdf.Document.getPageCount.

      If null, the appearance is positioned on the last page.

      Default: null

    • getTop

      public Length getTop()

      Distance to top of page (Getter)

      This property specifies the distance between appearance's top edge and the top of the page.

      If null, the distance to the top is unspecified.

      Default: null

    • setTop

      public void setTop(Length value)

      Distance to top of page (Setter)

      This property specifies the distance between appearance's top edge and the top of the page.

      If null, the distance to the top is unspecified.

      Default: null

      Throws:
      IllegalArgumentException - If the given value is negative

    • getRight

      public Length getRight()

      Distance to right of page (Getter)

      This property specifies the distance between appearance's right edge and the right of the page.

      If null, the distance to the right is unspecified.

      Default: null

    • setRight

      public void setRight(Length value)

      Distance to right of page (Setter)

      This property specifies the distance between appearance's right edge and the right of the page.

      If null, the distance to the right is unspecified.

      Default: null

      Throws:
      IllegalArgumentException - If the given value is negative

    • getBottom

      public Length getBottom()

      Distance to bottom of page (Getter)

      This property specifies the distance between appearance's bottom edge and the bottom of the page.

      If null, the distance to the bottom is unspecified.

      Default: null

    • setBottom

      public void setBottom(Length value)

      Distance to bottom of page (Setter)

      This property specifies the distance between appearance's bottom edge and the bottom of the page.

      If null, the distance to the bottom is unspecified.

      Default: null

      Throws:
      IllegalArgumentException - If the given value is negative

    • getLeft

      public Length getLeft()

      Distance to left of page (Getter)

      This property specifies the distance between appearance's left edge and the left of the page.

      If null, the distance to the left is unspecified.

      Default: null

    • setLeft

      public void setLeft(Length value)

      Distance to left of page (Setter)

      This property specifies the distance between appearance's left edge and the left of the page.

      If null, the distance to the left is unspecified.

      Default: null

      Throws:
      IllegalArgumentException - If the given value is negative

    • getCustomTextVariables

      public CustomTextVariableMap getCustomTextVariables()
      Maps the name of a custom text variable to its value. These variables can parametrize the content of the text element in the appearance configuration XML and Json files. They are used by setting "[custom:‹key›]".