Visual representation

The visual representation of a PDF signature is a text or image, inside the document, with information about the signature. Depending on the PDF viewer, this representation may link to the data and properties of the signature and of the signer.

Each visual representation always refers to a single signature in the PDF, and each signature can have at most one visual representation.

The @Lacuna.Pki.Pades.PadesVisualRepresentation2 class controls the visual representation information included in the signature. The sections below go through the options, parameters and customizations for defining the visual representation of PDF signatures.

Visual representation elements

The @Lacuna.Pki.Pades.PadesVisualRepresentation2 visual representation class has 3 elements you can set: @Lacuna.Pki.Pades.PadesVisualRepresentation2.Position, @Lacuna.Pki.Pades.PadesVisualRepresentation2.Text and @Lacuna.Pki.Pades.PadesVisualRepresentation2.Image. The list below introduces them. For more information, see the API reference of each class.

• Position

  The position of the signature's visual representation rectangle is customizable through the @Lacuna.Pki.Pades.PadesVisualAutoPositioning and @Lacuna.Pki.Pades.PadesVisualManualPositioning classes.

  • Automatic positioning

    Automatic positioning suits cases where you can define a region (container) on a PDF page to receive the signature representations. In this mode the signatures are arranged one after the other inside the given region. The figure below shows how automatic positioning works. The red rectangle is the container in which the visual representations are placed automatically, one after the other.

    

  • Manual positioning

    Manual positioning suits cases where each signature representation goes in an arbitrary position, for instance a position and page given by the user.

    

• Text

  The text included in the signature's visual representation is customizable through the @Lacuna.Pki.Pades.PadesVisualText class.

• Image

  You can include a background image in the signature's visual representation, and also customize its opacity and its alignment inside the visual representation rectangle. These options are set through the @Lacuna.Pki.Pades.PadesVisualImage class.

Manual positioning

With manual positioning, you set the page on which the signature representation goes, and the position and size of the signature rectangle relative to the page.

The page is set by the @Lacuna.Pki.Pades.PadesVisualPositioning.PageNumber property. Negative numbers count from the end of the document (-1 means the last page, -2 the one before it, and so on). The special value 0 (zero) means the signature representation goes on a new blank page added at the end of the document.

The position of the signature rectangle relative to the page is set by the @Lacuna.Pki.Pades.PadesVisualManualPositioning.SignatureRectangle property. A rectangle can have the parameters Top, Bottom, Left, Right, Width and Height, as in the figure below.

For instance, to place the visual representation on the last page of the document, 7cm wide and 3cm high, 2.5cm from the left and bottom margins, as in the image below, you would write the following code:

var signer = new PadesSigner();
...
var signatureVisualRep = new PadesVisualRepresentation2() {
    Position = new PadesVisualManualPositioning() {
        PageNumber = -1,                                    // Places it on the last page of the document
        SignatureRectangle = new PadesVisualRectangle() {
            Width = 7,                                      // Width = 7cm
            Height = 3,                                     // Height = 3cm
            Left = 2.50,                                    // Distance from the left margin = 2.50cm
            Bottom = 2.50                                   // Distance from the bottom margin = 2.50cm
        }
    },
    Text = ...,
    Image = ...
};
signer.SetVisualRepresentation(signatureVisualRep);

For more information on setting the position of the signature representation, see Defining a container.

Automatic positioning

With automatic positioning, as with manual positioning, you set the page on which the visual representation goes. Instead of positioning the visual representation relative to the page, though, you define a container that receives the representations of the successive signatures on the document, and the size of each signature rectangle inside the container.

The signature container is set by the @Lacuna.Pki.Pades.PadesVisualAutoPositioning.Container property. Like the signature rectangle in manual positioning, the container can have the parameters Top, Bottom, Left, Right, Width and Height. The size of each signature rectangle (height and width) is set by the @Lacuna.Pki.Pades.PadesVisualAutoPositioning.SignatureRectangleSize property.

The @Lacuna.Pki.Pades.PadesVisualAutoPositioning.RowSpacing property sets the spacing between the "rows" of visual representations. The signature rectangles are placed from left to right and, when there is no more room, on a new row, with the given RowSpacing.

For instance, to place the visual representations one after the other on the last page of the document, inside a container 3cm from the left and right edges, 2cm from the bottom edge and 8cm from the top edge, with each signature rectangle 7cm wide by 3cm high, as in the image below, you would write the following code:

var signer = new PadesSigner();
...
var signatureVisualRep = new PadesVisualRepresentation2() {
    Position = new PadesVisualAutoPositioning() {
        PageNumber = -1,                             // Places it on the last page of the document
        Container = new PadesVisualRectangle() {
            Left = 3.00,                             // Distance from the left margin = 3.00cm
            Right = 3.00,                            // Distance from the right margin = 3.00cm
            Bottom = 2.00,                           // Distance from the bottom margin = 2.00cm
            Top = 8.00                               // Distance from the top margin = 8.00cm
        },
        SignatureRectangleSize = new PadesSize(7, 3), // Size of each signature rectangle (width x height)
        RowSpacing = 1                               // 1.00cm spacing between rows
    },
    Text = ...,
    Image = ...
};
signer.SetVisualRepresentation(signatureVisualRep);

note

The container defined above has variable height and width. This is one of many ways to define the signature container. For more information, see Defining a container.

Signatures made with the code above should look like the image below:

Text and image positioning

• Text

  Inside the signature's visual representation rectangle, the SDK lets you customize the alignment, position and content of the text. The position of the text is controlled by defining a @Lacuna.Pki.Pades.PadesVisualText.Container. If no container is defined, the text fills the whole signature rectangle.

  As an example, we position the text relative to the signature rectangle as in the figure below.

  

  var text = new PadesVisualText() {                          // Text of the visual representation
      SignerName = signingCert.Certificate.SubjectDisplayName, // Includes the signer's name
      IncludeSigningTime = true,                              // Includes the signing date
      Container = new PadesVisualRectangle() {                // Defines the text container
          Left = 0,
          Top = 0,
          Right = 1.5,
          Bottom = 0.5
      }
  };

  For the text customizations available, see the properties in the @Lacuna.Pki.Pades.PadesVisualText API reference.

• Image

  You can also set a background image for the signature rectangle and customize its opacity and alignment. For the image customizations available, see the properties in the @Lacuna.Pki.Pades.PadesVisualImage API reference.

See also

• @Lacuna.Pki.Pades.PadesVisualRepresentation2
• @Lacuna.Pki.Pades.PadesVisualText
• @Lacuna.Pki.Pades.PadesVisualImage
• @Lacuna.Pki.Pades.PadesVisualAutoPositioning
• @Lacuna.Pki.Pades.PadesVisualManualPositioning