Skip to main content
All docs
V24.1

Form Controls in Spreadsheet Documents

  • 4 minutes to read

Form controls controls are interactive elements (buttons, checkboxes, and drop-down lists) that can be added to a worksheet to create user-friendly interfaces. These controls allow users to input or manage data.

form controls main

The Spreadsheet Document API allows you to manage form controls in code. You can add, edit and remove form controls. Documents with form controls are processed without content loss.

Form controls are available in the following formats:

  • XLSX
  • XLSM
  • XLTX
  • XLTM

Create Form Controls

The table below lists available form controls and API used to create each type.

Form Control Class Method
Button ButtonFormControl FormControlCollection.AddButton
Check Box CheckBoxFormControl FormControlCollection.AddCheckBox
Combo box ComboBoxFormControl FormControlCollection.AddComboBox
Group box GroupBoxFormControl FormControlCollection.AddGroupBox
List box ListBoxFormControl FormControlCollection.AddListBox
Radio Button RadioButtonFormControl FormControlCollection.AddRadioButton
Scrollbar ScrollbarFormControl FormControlCollection.AddScrollbar
Spin Button SpinnerFormControl FormControlCollection.AddSpinner

Note

The FormControlCollection.Add... method call adds a new item to both FormControlCollection and ShapeCollection.

The code sample below creates a button, a list box, and a checkbox. The result is opened in WinForms Spreadsheet Control:

form controls create

using DevExpress.Spreadsheet;

Workbook workbook = new Workbook();

var formControls = workbook.Worksheets[0].FormControls;

// Create a button form control:
var buttonCellRange = workbook.Worksheets[0].Range["B2:C2"];
var buttonFormControl = formControls.AddButton(buttonCellRange);
buttonFormControl.PlainText = "Click Here";

// Create a list box form control:
var comboCellRange = workbook.Worksheets[0].Range["B4:C4"];
var comboBoxControl = formControls.AddComboBox(comboCellRange);
comboBoxControl.DropDownLines = 3;
comboBoxControl.SourceRange = workbook.Worksheets[0].Range["E2:E6"];
comboBoxControl.SelectedIndex = 1;

// Create a check box form control:
var checkRange = workbook.Worksheets[0].Range["D5:E5"];
var checkBoxControl = formControls.AddCheckBox(checkRange);
checkBoxControl.CheckState = FormControlCheckState.Checked;
checkBoxControl.PlainText = "Reviewed";

Access and Modify Form Controls

The Worksheet.FormControls property obtains all form controls in a worksheet. You can use one of the following ways to obtain a specific form control:

The FormControl.Id and FormControl.Name properties return the form control’s identifier and name.

The code sample below retrieves all button form controls from a worksheet and disables printing for all buttons:

using DevExpress.Spreadsheet;
using System.Linq;

Workbook workbook = new Workbook();
workbook.LoadDocument("Document.xlsx");

var formControls = workbook.Worksheets[0].FormControls;

var buttons = formControls.Where(formControl => formControl.FormControlType == FormControlType.Button).Cast<ButtonFormControl>();
foreach (ButtonFormControl button in buttons) {
    button.PrintObject = false;
}

You can print and export to PDF workbooks with form controls. Each form control has the PrintObject property that specifies whether to print the form control.

This option also affects the following operations:

  • Form control export to PDF format
  • Export of a cell range that contains a form control to an image
  • Export of a worksheet with form controls to an image

Remove Form Controls

Call the FormControlCollection.Remove or FormControlCollection.RemoveAt method to remove a form control. The FormControlCollection.Clear() method removes all form controls from a worksheet.

The code sample below removes all check boxes from a workbook:

Workbook workbook = new Workbook();
workbook.LoadDocument("Document.xlsx");

var formControls = workbook.Worksheets[0].FormControls;

for (int i = formControls.Count - 1; i >= 0; i--) {
    if (formControls[i].FormControlType == FormControlType.CheckBox)
        formControls.RemoveAt(i);
}

Limitations

The Form Control API subset ships with the following limitations: