Document Solutions for PDF
Features / Forms
In This Topic
    Forms
    In This Topic

    The PDF-based fillable form, also known as AcroForm, is an interactive form with a collection of fields, such as TextBox, Button, CheckBox, etc. These fields can be filled with data programmatically or manually in order to take information as input from the user. For more information on AcroForm, see PDF specification 2.0 (Section 12.7).

    DsPdf allows you to create AcroForms using AcroForm class and define common properties of AcroForm using Fields property of AcroForm class. The library lets you add, get, modify, and delete different form fields. You can use the following fields in AcroForms.

    FormFields

    Add AcroForm Fields

    To add AcroForm fields in a PDF document using DsPdf:

    1. Create an instance of class corresponding to field you want to add to the form, for example,
      TextField class.
    2. Set the basic properties of the field.
      Observe that the field is also being filled in the code through Value property.
    3. Add the field to the form using the Add method.
      C#
      Copy Code
      public void CreatePDF(Stream stream)
      {
          var doc = new GcPdfDocument();
          var page = doc.NewPage();
          var g = page.Graphics;
          TextFormat tf = new TextFormat();
          tf.Font = StandardFonts.Times;
          tf.FontSize = 14;
          PointF ip = new PointF(72, 72);
          float fldOffset = 72 * 2;
          float fldHeight = tf.FontSize * 1.2f;
          float dY = 32;
      
          // Add TextField
          g.DrawString("Text field:", tf, ip);
          var fldText = new TextField();
          fldText.Value = "Initial TextField value";
          fldText.Widget.Page = page;
          fldText.Widget.Rect = new RectangleF(ip.X + fldOffset, ip.Y, 72 * 3, fldHeight);
          fldText.Widget.TextFormat.Font = tf.Font;
          fldText.Widget.TextFormat.FontSize = tf.FontSize;
          doc.AcroForm.Fields.Add(fldText);
          ip.Y += dY;
      
          // Add Checkbox:
          g.DrawString("Checkbox:", tf, ip);
          var fldCheckbox = new CheckBoxField();
          fldCheckbox.Value = true;
          fldCheckbox.Widget.Page = page;
          fldCheckbox.Widget.Rect = new RectangleF(ip.X + fldOffset, ip.Y, fldHeight, fldHeight);
          doc.AcroForm.Fields.Add(fldCheckbox);
          ip.Y += dY;
      
          // Save Document
          doc.Save(stream);
      }
      
    Back to Top

    Set Field Format

    You can set the format of TextField, CombTextField, and ComboBoxField to percent, number, date, time, and special format using the following methods in TextFieldCombTextField, and ComboBoxField classes:

    Methods Description

    SetPercentFormat

    Initializes the field's Format and KeyPress events with ActionJavaScript objects corresponding to the specified format. This method does not affect the field value or appearance streams of the field annotations.
    SetNumberFormat Initializes the field's Format and KeyPress events with ActionJavaScript objects corresponding to the specified format. This method does not affect the field value or appearance streams of the field annotations.
    SetDateFormat Initializes the field's Format and KeyPress events with ActionJavaScript objects corresponding to the specified format. This method does not affect the field value or appearance streams of the field annotations.
    SetTimeFormat Initializes the field's Format and KeyPress events with ActionJavaScript objects corresponding to the specified format. This method does not affect the field value or appearance streams of the field annotations.
    SetSpecialFormat Initializes the field's Format and KeyPress events with ActionJavaScript objects corresponding to the specified format. This method does not affect the field value or appearance streams of the field annotations.
    SetPercentValue Initializes the field's Format and KeyPress events, sets the field value, and generates the appearance stream for field annotations. The passed value will be converted to a string using the corresponding format.
    SetNumberValue Initializes the field's Format and KeyPress events, sets the field value, and generates the appearance stream for field annotations. The passed value will be converted to a string using the corresponding format.
    SetDateValue Initializes the field's Format and KeyPress events, sets the field value, and generates the appearance stream for field annotations. The passed value will be converted to a string using the corresponding format.
    SetTimeValue Initializes the field's Format and KeyPress events, sets the field value, and generates the appearance stream for field annotations. The passed value will be converted to a string using the corresponding format.
    SetSpecialFormatValue Initializes the field's Format and KeyPress events, sets the field value, and generates the appearance stream for field annotations. The passed value will be converted to a string using the corresponding format.

    Refer to the following example code to set formats for text fields, comb text fields, and combo box fields:

    C#
    Copy Code
    // Set percent format for TextField.
    private static TextField AddPercentFormat(Page p,
        _Rect rect,
        int decimalPlaces,
        TextField.NumberSeparatorStyle separatorStyle)
    {
        TextField result = new TextField();
        p.Doc.AcroForm.Fields.Add(result);
    
        result.Widget.Page = p;
        result.Widget.Rect = rect;
        result.Widget.Border.Width = 1;
        result.SetPercentFormat(decimalPlaces, separatorStyle);
    
        return result;
    }
    
    // Set number format for CombTextField.
    private static CombTextField AddNumberFormat(Page p,
        _Rect rect,
        int decimalPlaces,
        CombTextField.NumberSeparatorStyle separatorStyle,
        CombTextField.NumberNegativeStyle negativeStyle,
        string currencySymbol,
        CombTextField.CurrencySymbolStyle currencySymbolStyle)
    {
        CombTextField result = new CombTextField();
        p.Doc.AcroForm.Fields.Add(result);
    
        result.Widget.Page = p;
        result.Widget.Rect = rect;
        result.Widget.Border.Width = 1;
        result.SetNumberFormat(decimalPlaces, separatorStyle, negativeStyle, currencySymbol, currencySymbolStyle);
    
        return result;
    }
    
    // Set date format for TextField.
    private static TextField AddDateFormat(Page p,
        _Rect rect,
        DateTime v,
        string format)
    {
        TextField result = new TextField();
        p.Doc.AcroForm.Fields.Add(result);
    
        result.Widget.Page = p;
        result.Widget.Rect = rect;
        result.Widget.Border.Width = 1;
        result.SetDateValue(v, format);
    
        return result;
    }
    
    // Set time format for ComboBoxField.
    private static ComboBoxField AddTimeFormat(Page p,
        _Rect rect,
        DateTime v,
        string format)
    {
        ComboBoxField result = new ComboBoxField();
        p.Doc.AcroForm.Fields.Add(result);
    
        result.Widget.Page = p;
        result.Widget.Rect = rect;
        result.Widget.Border.Width = 1;
        result.SetTimeValue(v, format);
    
        return result;
    }
    
    // Set special format for TextField.
    private static TextField AddSpecialFormat(Page p,
        _Rect rect,
        string v,
        TextField.SpecialFormat format)
    {
        TextField result = new TextField();
        p.Doc.AcroForm.Fields.Add(result);
    
        result.Widget.Page = p;
        result.Widget.Rect = rect;
        result.Widget.Border.Width = 1;
        result.SetSpecialFormatValue(v, format);            
    
        return result;
    }
    
    static void Main(string[] args)
    {
        // Initialize GcPdfDocument. 
        GcPdfDocument doc = new GcPdfDocument();
    
        // Set compression level.
        doc.CompressionLevel = System.IO.Compression.CompressionLevel.NoCompression;
    
        // Add a blank page to the document.
        var p = doc.NewPage();
    
        // Initialize GcPdfGraphics.
        var g = p.Graphics;
    
        // Draw SetPercentFormat string.
        g.DrawString("SetPercentFormat", StandardFonts.Helvetica, 14, Color.Black, new _Point(10, 10));
    
        // Set percent format for the text fields.
        AddPercentFormat(p, new _Rect(10, 40, 60, 20), 2, TextField.NumberSeparatorStyle.Comma);
        AddPercentFormat(p, new _Rect(80, 40, 60, 20), 0, TextField.NumberSeparatorStyle.CommaDot);
        AddPercentFormat(p, new _Rect(150, 40, 60, 20), 3, TextField.NumberSeparatorStyle.DotComma);
        AddPercentFormat(p, new _Rect(220, 40, 60, 20), 2, TextField.NumberSeparatorStyle.Dot);
        AddPercentFormat(p, new _Rect(290, 40, 60, 20), 2, TextField.NumberSeparatorStyle.ApostropheDot);
    
        // Draw SetNumberFormat string.
        g.DrawString("SetNumberFormat", StandardFonts.Helvetica, 14, Color.Black, new _Point(10, 70));
    
        // Set number format for the comb text fields.
        AddNumberFormat(p, new _Rect(10, 100, 60, 20), 2, CombTextField.NumberSeparatorStyle.Comma,
            CombTextField.NumberNegativeStyle.None, null, CombTextField.CurrencySymbolStyle.BeforeWithSpace);
        AddNumberFormat(p, new _Rect(80, 100, 60, 20), 0, CombTextField.NumberSeparatorStyle.CommaDot,
            CombTextField.NumberNegativeStyle.UseRedText, "R", CombTextField.CurrencySymbolStyle.BeforeWithSpace);
        AddNumberFormat(p, new _Rect(150, 100, 60, 20), 3, CombTextField.NumberSeparatorStyle.DotComma,
            CombTextField.NumberNegativeStyle.ShowParentheses, "\u20ac", CombTextField.CurrencySymbolStyle.AfterWithSpace);
        AddNumberFormat(p, new _Rect(220, 100, 60, 20), 2, CombTextField.NumberSeparatorStyle.Dot,
            CombTextField.NumberNegativeStyle.ShowParentheses, "TL", CombTextField.CurrencySymbolStyle.AfterNoSpace);
        AddNumberFormat(p, new _Rect(290, 100, 60, 20), 2, CombTextField.NumberSeparatorStyle.ApostropheDot,
            CombTextField.NumberNegativeStyle.ShowParentheses | CombTextField.NumberNegativeStyle.UseRedText, "TL", CombTextField.CurrencySymbolStyle.AfterWithSpace);
    
        // Draw SetDateFormat string.
        g.DrawString("SetDateFormat", StandardFonts.Helvetica, 14, Color.Black, new _Point(10, 130));
    
        // Set date format for the text fields.
        AddDateFormat(p, new _Rect(10, 160, 60, 20), DateTime.Now, "dd-mm-yyyy");
        AddDateFormat(p, new _Rect(80, 160, 60, 20), DateTime.Now, "d-m-yy");
        AddDateFormat(p, new _Rect(150, 160, 60, 20), DateTime.Now, "yyyy/mmmm/dd");
    
        // Draw SetTimeFormat string.
        g.DrawString("SetTimeFormat", StandardFonts.Helvetica, 14, Color.Black, new _Point(10, 200));
    
        // Set time format for the combobox fields.
        DateTime dt = new DateTime(2000, 1, 1, 1, 2, 3);
        AddTimeFormat(p, new _Rect(10, 230, 60, 20), dt, "HH:MM");
        AddTimeFormat(p, new _Rect(80, 230, 60, 20), dt, "h:MM tt");
        AddTimeFormat(p, new _Rect(150, 230, 60, 20), dt, "HH:MM:ss");
    
        // Draw Special Format string.
        g.DrawString("Special Format", StandardFonts.Helvetica, 14, Color.Black, new _Point(10, 270));
    
        // Set special format for the text fields.
        AddSpecialFormat(p, new _Rect(10, 300, 60, 20), "35004", TextField.SpecialFormat.ZipCode);
        AddSpecialFormat(p, new _Rect(80, 300, 60, 20), "84606-6580", TextField.SpecialFormat.ZipCode4);
        AddSpecialFormat(p, new _Rect(150, 300, 60, 20), "", TextField.SpecialFormat.Phone);
        AddSpecialFormat(p, new _Rect(220, 300, 60, 20), "", TextField.SpecialFormat.SSN);
    
        // Save the document.
        doc.Save("FieldFormat.pdf");
    }
    

     

    Note: If any field property that affects appearance is changed, then appearance streams generated by SetXXXMethods are lost, so these methods should be called "at the end".

    Back to Top

    Set Field Formats using Format Functions

    You can also set the format of TextField, CombTextField, and ComboBoxField to percent, number, date, time, and special format using the following format functions:

    Format Description Example
    AFPercent_Format Displays a numeric value as a percentage. The numeric value "1" in the field changes to "100%" after applying the format function.
    AFNumber_Format Displays a numeric value according to specified parameters. The numeric value "0.123" in the field changes to "0.123 €" after applying the format function.
    AFTime_FormatEx Displays a time value according to the specified style. The time value "23:21" in the field changes to "11:21 PM" after applying the format function.
    AFDate_FormatEx Displays a date value according to the specified style. The date value "2024/May/27" in the field changes to "May 21, 2024" after applying the format function.
    AFSpecial_Format Displays a value according to the specified fixed format style. The value "1234567890" in the field changes to "(123) 456-7890" after applying the format function.

    Refer to the following example code to set different formats for text fields:

    C#
    Copy Code
    // Initialize GcPdfDocument.
    var doc = new GcPdfDocument();
                
    // Add new page to the document.
    var page = doc.NewPage();
    
    // Initialize GcPdfGraphics.
    var g = page.Graphics;
    
    // Set text format.
    TextFormat tf = new TextFormat();
    tf.Font = StandardFonts.Times;
    tf.FontSize = 14;
    PointF ip = new PointF(72, 72);
    float fldOffset = 72 * 2;
    float fldHeight = tf.FontSize * 1.2f;
    float dY = 32;
    
    // Add TextField for Percent Format.
    g.DrawString("Percent Format", tf, ip);
    var fldText1 = new TextField();
                
    // Add value to the field.
    fldText1.Value = "-0.100";
    fldText1.Widget.Page = page;
    fldText1.Widget.Rect = new RectangleF(ip.X + fldOffset, ip.Y, 72 * 3, fldHeight);
    
    // Format the value to percent format.
    fldText1.Events.FormatValue = new ActionJavaScript("AFPercent_Format(3, 2)");
    doc.AcroForm.Fields.Add(fldText1);
    ip.Y += dY;
    
    // Add TextField for Number Format.
    g.DrawString("Number Format", tf, ip);
    var fldText2 = new TextField();
    
    // Add value to the field.
    fldText2.Value = "-0.123";
    fldText2.Widget.Page = page;
    fldText2.Widget.Rect = new RectangleF(ip.X + fldOffset, ip.Y, 72 * 3, fldHeight);
    
    // Format the value to number format.
    fldText2.Events.FormatValue = new ActionJavaScript("AFNumber_Format(3, 2, 1, 0, ' €', false)");
    doc.AcroForm.Fields.Add(fldText2);
    ip.Y += dY;
    
    // Add TextField for Time Format.
    g.DrawString("Time Format", tf, ip);
    var fldText3 = new TextField();
    
    // Add value to the field.
    fldText3.Value = "23:21";
    fldText3.Widget.Page = page;
    fldText3.Widget.Rect = new RectangleF(ip.X + fldOffset, ip.Y, 72 * 3, fldHeight);
    
    // Format the value to time format.
    fldText3.Events.FormatValue = new ActionJavaScript("AFTime_FormatEx('H:MM tt')");
    doc.AcroForm.Fields.Add(fldText3);
    ip.Y += dY;
    
    // Add TextField for Date Format.
    g.DrawString("Date Format", tf, ip);
    var fldText4 = new TextField();
    
    // Add value to the field.
    fldText4.Value = "27-05-2025";
    fldText4.Widget.Page = page;
    fldText4.Widget.Rect = new RectangleF(ip.X + fldOffset, ip.Y, 72 * 3, fldHeight);
    
    // Format the value to date format.
    fldText4.Events.FormatValue = new ActionJavaScript("AFDate_FormatEx('dd-m-yy')");
    doc.AcroForm.Fields.Add(fldText4);
    ip.Y += dY;
    
    // Add TextField for Special Format.
    g.DrawString("Special Format", tf, ip);
    var fldText5 = new TextField();
    
    // Add value to the field.
    fldText5.Value = "1234567890";
    fldText5.Widget.Page = page;
    fldText5.Widget.Rect = new RectangleF(ip.X + fldOffset, ip.Y, 72 * 3, fldHeight);
    
    // Format the value to special format.
    fldText5.Events.FormatValue = new ActionJavaScript("AFSpecial_Format(2)");
    doc.AcroForm.Fields.Add(fldText5);
    ip.Y += dY;
    
    // Save Document
    doc.Save("FieldFormatFunctions.pdf");
    

     

    Note: Since DsPdf does not parse ActionJavaScript function, the field formatting will not take effect initially, but it will take effect when you modify the field. To overcome this, DsPdf provides various methods in TextFieldCombTextField, and ComboBoxField classes to set the field format. For more information, see Set Field Format.

    Back to Top

    Modify AcroForm Fields

    To modify form fields in PDF document, get the particular form field by specifying its index and set a new value for the field using Value property. This property fills the field with the specified string value.

    C#
    Copy Code
    doc.AcroForm.Fields[0].Value = "Sample Text";
    
    Back to Top

    Delete AcroForm Fields

    To delete a particular form field in PDF document, use RemoveAt method to remove any field by specifying its index value. Apart from this, Clear method can be used to remove all the AcroForm fields from the document.

    C#
    Copy Code
    // Delete a particular field
    doc.AcroForm.Fields.RemoveAt(0);
            
    // Delete all the fields
    doc.AcroForm.Fields.Clear();
    
    Back to Top

    Define Tab Order of Form Fields

    You can navigate the form fields in a PDF document by using the 'Tab' key on the keyboard. The order of navigation of form fields can be set by using the AnnotationTabsOrder property which can be set to any of the below mentioned AnnotationTabsOrder enumeration values:

    To know more about tab orders, see PDF specification 2.0 (refer section 12.5.1)

    C#
    Copy Code
    // Set tab order of form fields to row
    page.AnnotationsTabsOrder = AnnotationsTabsOrder.RowOrder;
    
    Note: The tab order, set in the PDF document, can be viewed as well as edited in DsPdfViewer. Refer Form Editor for more details.

    Back to Top

    For more information about implementation of AcroForms using DsPdf, see DsPdf sample browser.