Signature Fields

Before a document can be signed, it needs places for the signatures. In a WPF application, signature fields are those places: frames in the text that record the expected signer, show a signature image and are signed with a certificate when the document is saved as PDF. Users add them with the ribbon, and your code inserts, finds and removes them through SignatureFields.

The examples use a window with a TextControl named textControl1, as in Create Your First WPF Application. Signature fields were introduced in version 31.0. How the fields are signed is the subject of Digital Signatures.

Signature Fields in a Document

A SignatureField is a frame that holds a signature image, added while the document is designed or when it is signed. Like an image or a text frame, it is placed as a character in the text, anchored to a paragraph or fixed on a page. In a document, empty signature fields appear as gray boxes with a signature line:

Besides its position and size, a signature field has a name, needed to assign a certificate to it in a PDF, signer data about the expected signer and the reason for signing, and an optional image. Signature fields are saved in the TX Text Control format, PDF, DOCX and RTF; other formats keep only the image. PDF readers such as Adobe Acrobat Reader can sign an unsigned signature field of an exported PDF.

The API consists of the field, its collection, SignerData, SignatureImage and the events of the TextControl:

Let Users Insert Signature Fields

The Insert tab of the WPF ribbon, WPF.RibbonInsertTab, has a Signature Field button. When a signature field is selected, the frame layout tab, WPF.RibbonFrameLayoutTab, shows a signer info group for the signer's name, title, address, contact information and reason, next to the name and ID of the field. Connect both tabs with the TextControl in MainWindow.xaml:

<DockPanel>
    <Ribbon DockPanel.Dock="Top">
        <WPF:RibbonInsertTab x:Name="ribbonInsertTab" />
        <WPF:RibbonFrameLayoutTab x:Name="ribbonFrameLayoutTab" />
    </Ribbon>
    <StackPanel DockPanel.Dock="Top" Orientation="Horizontal">
        <Button Content="Insert Signature Field" Click="InsertSignatureField_Click" />
        <Button Content="Draw Signature Field" Click="DrawSignatureField_Click" />
        <Button Content="Set Image" Click="SetImage_Click" />
        <Button Content="Remove" Click="RemoveSignatureField_Click" />
    </StackPanel>
    <WPF:TextControl x:Name="textControl1"
                    RibbonInsertTab="ribbonInsertTab"
                    RibbonFrameLayoutTab="ribbonFrameLayoutTab"
                    SignatureFieldSelected="textControl1_SignatureFieldSelected" />
</DockPanel>

RibbonInsertTab and RibbonFrameLayoutTab take the names of the tabs. The ribbon sample of TX Text Control Words puts the frame layout tab into a contextual tab group, so that it appears when a frame is selected; Connecting Ribbon Tabs in XAML shows how tabs are connected. WPF.TextControl.SignatureFieldLayoutDialog opens the dialog box with the layout, size and text distances of the selected field.

Insert a Signature Field in Code

WPF.TextControl.SignatureFields returns the SignatureFieldCollection of the main text. MainWindow.xaml.cs needs using System.Windows; and using TXTextControl;:

private void InsertSignatureField_Click(object sender, RoutedEventArgs e)
{
    // 2.5 x 1 inch in twips (1 inch = 1440 twips); "txsign" is the name
    SignatureField signatureField = new SignatureField(new System.Drawing.Size(3600, 1440), "txsign", 0)
    {
        SignerData = new SignerData(
            "Tim Typer", "Sales Manager", "", "tim@example.com", "Contract approval")
    };

    // Anchor the field to the paragraph at the input position (-1)
    bool added = textControl1.SignatureFields.Add(
        signatureField,
        TXTextControl.HorizontalAlignment.Left,
        -1,
        FrameInsertionMode.DisplaceText);

    if (!added)
    {
        MessageBox.Show(this, "The signature field couldn't be added at this position.");
    }
}

The code works as follows:

• The SignatureField constructor takes the size in twips, a name and an ID, where 0 means none. The size is a System.Drawing.Size, not a WPF Size, so the code names its namespace.
• SignerData holds the name, title, address and contact information of the expected signer and the reason for signing. SignatureField.SignerData stores it with the field.
• SignatureFieldCollection.Add with an alignment, a text position and a FrameInsertionMode anchors the field to the paragraph; -1 is the input position. TXTextControl.HorizontalAlignment is written in full, because WPF has a System.Windows.HorizontalAlignment as well.

To let the user draw the field, pass only the insertion mode:

private void DrawSignatureField_Click(object sender, RoutedEventArgs e)
{
    // The user draws the field with the mouse; ESC cancels
    SignatureField signatureField = new SignatureField(new System.Drawing.Size(0, 0), "txsign_2", 0);
    textControl1.SignatureFields.Add(signatureField, FrameInsertionMode.DisplaceText);
    textControl1.Focus();
}

A cross cursor shows where the field can go, and the user determines its size. ESC or a change of the document cancels it. Further overloads insert the field as a character or at a fixed position on a page; Images describes these kinds of placement.

Set an Image and Remove a Field

private void SetImage_Click(object sender, RoutedEventArgs e)
{
    SignatureField signatureField = textControl1.SignatureFields.GetItem("txsign");

    if (signatureField != null)
    {
        // Filter index 8 is SVG, 4 is PNG
        signatureField.Image = new SignatureImage("signature.svg", 8);
    }
}

private void RemoveSignatureField_Click(object sender, RoutedEventArgs e)
{
    // The signature field the user has selected, or null
    SignatureField signatureField = textControl1.SignatureFields.GetItem();

    if (signatureField != null)
    {
        textControl1.SignatureFields.Remove(signatureField);
    }
}

• GetItem returns the field with a name or an ID, or without a parameter the selected field.
• SignatureField.Image takes a SignatureImage created from a file and the index of its format, or from a MemoryStream; null removes the image. Add a Signature Image lists the format indexes and the constructors and decides how the image is saved.
• Remove deletes the field from the document.

Handle Signature Field Events

The WPF TextControl raises SignatureFieldCreated, SignatureFieldDeleted, SignatureFieldSelected, SignatureFieldDeselected and SignatureFieldClicked, each with a SignatureFieldEventArgs. The handler connected in the XAML above shows the expected signer of the selected field:

private void textControl1_SignatureFieldSelected(object sender, SignatureFieldEventArgs e)
{
    SignerData signer = e.SignatureField.SignerData;
    Title = e.SignatureField.Name + (signer != null ? ", expected signer: " + signer.Name : "");
}

Sign the Fields

The signing happens when the document is saved as PDF. SaveSettings.SignatureFields takes an array of DigitalSignature objects, each with a certificate and the name of the field it signs, so that several signers each sign their own field. Digitally Sign a PDF walks through it, and Signature Fields and Signature Appearance covers the details.

The blog article Sneak Peek 31.0: Signature Fields introduces the feature, and Preparing Documents for E-Signing for Multiple Signers in .NET C# prepares a document for several signers.

Next Steps

• Digitally Sign a PDF: apply a certificate to a signature field.
• Signing PDF Documents: sign documents and fields.
• Form Fields and Conditional Instructions: the other fields of a form.