[]
        
(Showing Draft Content)

Export Form Controls to Form Fields

Sometimes you need the Excel form containing form controls as an interactive PDF form (or AcroForms). Form controls are objects that can be added to a worksheet to enable interaction with a cell or a data range available in the worksheet. With setFormFields method of PdfSaveOptions class, DsExcel allows you to export the form controls as form fields to the PDF document, which will be interactive for the user.

Refer to the following example code to export Excel form controls as PDF form fields:

// Initialize Workbook.
Workbook workbook = new Workbook();
        
// Create worksheet.
IWorksheet ws = workbook.getWorksheets().get("Sheet1");
        
// Add three checkboxes.
ICheckBox checkBox1 = ws.getControls().addCheckBox(62.4, 16.8, 69, 19.2);
checkBox1.setValue(false);

ICheckBox checkBox2 = ws.getControls().addCheckBox(62.4, 36.6, 69, 19.2);
checkBox2.setValue(true);

ICheckBox checkBox3 = ws.getControls().addCheckBox(62.4, 57, 69, 19.2);
checkBox3.setValue(false);

// Add dropdown.
IDropDown dropDown = ws.getControls().addDropDown(28.8, 81.8, 103.8, 31.4);
dropDown.setPrintObject(true);
dropDown.getItems().add(new DropDownItem("Item 1"));
dropDown.getItems().add(new DropDownItem("Item 2"));
dropDown.getItems().add(new DropDownItem("Item 3"));
dropDown.setSelectedIndex(0);

// Add listbox.
IListBox lstBox1 = ws.getControls().addListBox(51.6, 134.2, 135, 99.6);
for (int i = 0; i < 6; i++) {
    lstBox1.getItems().add(new ListBoxItem("Item " + (i + 1)));
}
lstBox1.setSelectedIndex(2);

// Add option button groups.
ws.getControls().addGroupBox(234.2, 8.4, 222.6, 138.6);
ws.getControls().addOptionButton(261.2, 29.4, 71.4, 16.8);
ws.getControls().addOptionButton(267.8, 70.8, 71.4, 16.8);
ws.getControls().addOptionButton(275.6, 111.6, 71.4, 16.8);

ws.getControls().addGroupBox(244.4, 187.6, 176.4, 143.4);
ws.getControls().addOptionButton(274.4, 216.6, 71.4, 16.8);
ws.getControls().addOptionButton(279.8, 255, 71.4, 16.8);
ws.getControls().addOptionButton(286.4, 295.2, 71.4, 16.8);

// Set FormFields to true to export Excel form controls as PDF form fields.
PdfSaveOptions options = new PdfSaveOptions();
options.setFormFields(true);
        
// Save the PDF document.
workbook.save("PdfFormFieldExample.pdf", options);


Note: The ZIndex of mapped PDF form fields is always higher than other shapes.

If form controls are not present in the exported PDF document, then check and enable setPrintObject setting of the specific form control. By default, the value of this property is true for all form controls except the Button form control.

Refer to the following example code to print a Button form control while saving it as a PDF:

// Create a new workbook
Workbook workbook = new Workbook();

IWorksheet worksheet = workbook.getWorksheets().get(0);
        
// Add a button control to worksheet and set its PrintObject property
IButton btn = worksheet.getControls().addButton(360, 91.8, 103.94, 19.79);
btn.setText("Test settings");
btn.setPrintObject(true);

// Save to a pdf file
workbook.save("FormControlPdf.pdf");

Mapping of Excel Controls to PDF Form Fields

When exporting an Excel file to PDF, DsExcel maps the supported Excel form controls to PDF form fields. The properties that DsExcel supports for mapping are listed in the table below.

Control Type

Interface

Mapped Members and Description

Check Box

GrapeCity.Documents.Excel.Forms.ICheckBox

When exporting to PDF, the following members of the check box are mapped:

Combo Box

GrapeCity.Documents.Excel.Forms.IDropDown

When exporting to PDF, the following members of the combo box are mapped:

List Box

GrapeCity.Documents.Excel.Forms.IListBox

When exporting to PDF, the following members of the list box are mapped:

Option Button

GrapeCity.Documents.Excel.Forms.IOptionButton

When exporting to PDF, the following members of the option button are mapped:

Limitations

  • Since PDF does not support running Excel VBA code, buttons (IButton) are displayed as static content when exported as PDF forms and are not interactive.

  • Group boxes (IGroupBox), labels (ILabel), scroll bars (IScrollBar), and spinners (ISpinner) are not available as PDF form fields. When exported as PDF forms, these controls are displayed as static content and are not interactive.

  • Linked cells for controls cannot be set in PDF forms. When exported as PDF forms, the cell link will be invalid.

  • The colors and lines of check boxes (ICheckBox) and option buttons (IOptionButton) cannot be set in PDF forms. When exported as PDF forms, the default appearance will be used.

  • When form controls are grouped and exported as PDF forms, controls within the group will not be displayed.

  • The selection states of option buttons are not exported.

  • The option buttons have rectangle border instead of round border.

For more information on exporting form controls to PDF document, see Simulate UI with PDF form fields.