# Form Controls DsExcel Java is a MESCIUS Documents product that offers a comprehensive library to create, manipulate, convert, and share Microsoft Excel-compatible spreadsheets. ## Content Form controls are objects which can be added to a worksheet to enable interaction with a cell or a data range available in the worksheet. You can seek input from the end-user or provide him with options to choose from by using these form controls. Hence, these controls are apt to create forms such as feedback forms or consent forms. ![](https://cdn.mescius.io/document-site-files/images/dd59ea42-cd61-4fa6-a018-6231c2a9c598/images/form-controls.png) DsExcel provides nine form controls through [com.grapecity.documents.excel.forms](/document-solutions/java-excel-api/api/online/com/grapecity/documents/excel/forms/package-summary.html) namespace which contains classes and interfaces for each supported form control. The table below lists the supported form controls and their images. | **Form Control** | **Snapshots** | | ------------ | --------- | | Button | ![](https://cdn.mescius.io/document-site-files/images/dd59ea42-cd61-4fa6-a018-6231c2a9c598/images/form_control_images/button.png) | | Dropdown | ![](https://cdn.mescius.io/document-site-files/images/dd59ea42-cd61-4fa6-a018-6231c2a9c598/images/form_control_images/dropdown.png) | | Checkbox | ![](https://cdn.mescius.io/document-site-files/images/dd59ea42-cd61-4fa6-a018-6231c2a9c598/images/form_control_images/checkbox.png) | | Spinner | ![](https://cdn.mescius.io/document-site-files/images/dd59ea42-cd61-4fa6-a018-6231c2a9c598/images/form_control_images/spinner.png) | | Listbox | ![](https://cdn.mescius.io/document-site-files/images/dd59ea42-cd61-4fa6-a018-6231c2a9c598/images/form_control_images/listbox.png) | | Option button | ![](https://cdn.mescius.io/document-site-files/images/dd59ea42-cd61-4fa6-a018-6231c2a9c598/images/form_control_images/option-button.png) | | Group box | ![](https://cdn.mescius.io/document-site-files/images/dd59ea42-cd61-4fa6-a018-6231c2a9c598/images/form_control_images/groupbox.png) | | Label | ![](https://cdn.mescius.io/document-site-files/images/dd59ea42-cd61-4fa6-a018-6231c2a9c598/images/form_control_images/label.png) | | Scrollbar | ![](https://cdn.mescius.io/document-site-files/images/dd59ea42-cd61-4fa6-a018-6231c2a9c598/images/form_control_images/scrollbar.png) | All the form controls possess some common features which are provided by [IControl](/document-solutions/java-excel-api/api/online/com/grapecity/documents/excel/forms/IControl.html) interface of the com.grapecity.documents.excel.forms namespace. You can disable these controls by setting the [setEnabled](/document-solutions/java-excel-api/api/online/com/grapecity/documents/excel/forms/IControl.html#setEnabled) method to **false**, so that user cannot bring focus to that control. There is an option to even lock the controls from accepting user input by setting the [setLocked](/document-solutions/java-excel-api/api/online/com/grapecity/documents/excel/forms/IControl.html#setLocked) method to true. To define how a control is attached to the underlying cells, you can use the [setPlacement](/document-solutions/java-excel-api/api/online/com/grapecity/documents/excel/forms/IControl.html#setPlacement) method. You can also change ZOrder of the controls, bring form controls to front or send them to back by using the [bringToFront](/document-solutions/java-excel-api/api/online/com/grapecity/documents/excel/forms/IControl.html#bringToFront) and [sendToBack](/document-solutions/java-excel-api/api/online/com/grapecity/documents/excel/forms/IControl.html#sendToBack) methods. ## Add and Remove Form Controls DsExcel allows you to add or remove the form controls to a worksheet by using [getControls](/document-solutions/java-excel-api/api/online/com/grapecity/documents/excel/IWorksheet.html#getControls) method of the [IWorksheet](/document-solutions/java-excel-api/api/online/com/grapecity/documents/excel/IWorksheet.html) interface. To add a form control to worksheet, you can use **add** method of the [IControlCollection](/document-solutions/java-excel-api/api/online/com/grapecity/documents/excel/forms/IControlCollection.html) interface. For instance, [addButton](/document-solutions/java-excel-api/api/online/com/grapecity/documents/excel/forms/IControlCollection.html#addButton) method adds the button form control and [addDropdown](/document-solutions/java-excel-api/api/online/com/grapecity/documents/excel/forms/IControlCollection.html#addDropDown) method adds the dropdown control to worksheet. So, there are nine such methods, one for each form control and all of them accept location coordinates, width, and height of the form control as parameters. DsExcel provides **delete** method of the **IControl** interface to remove a particular form control from worksheet. To remove all the controls from worksheet, you can use **clear** method of the **IControlCollection** interface. The code below demonstrates how to add or delete form controls to or from a worksheet: ```Java // Create a new workbook Workbook workbook = new Workbook(); IWorksheet ws = workbook.getWorksheets().get("Sheet1"); // Add two controls ILabel lblResolution = ws.getControls().addLabel(12.6, 20.4, 49.2, 18.6); lblResolution.setText("Resolution"); lblResolution.setPrintObject(true); IButton btnNative = ws.getControls().addButton(199.8, 21, 127.8, 17.4); btnNative.setText("Use native resolution"); btnNative.setPrintObject(true); // Remove the first one ws.getControls().get(0).delete(); // Remove all the controls // ws.getControls().clear(); ``` ## Link Form Controls to a Cell Range The selection-based form controls, that are **Checkbox**, **Option button**, **Listbox**, **Dropdown**, and **Scrollbar** provide **setLinkedCell** method of the **ICellLinkControl** interface that enables a two-way binding between value of the form control and the linked cell range. Linked cell range allows you to have a definite set of values in form control to avoid invalid data input from the end-user. You can update values of the form control by simply editing value in the linked cell range or vice-versa. The code below shows how to link cell values to the Checkbox form control: ```Java // Link a check box ICheckBox checkBox1 = ws.getControls().addCheckBox(54, 13.2, 64.2, 18); checkBox1.setLinkedCell(ws.getRange("$A$2")); ``` ## Find Form Controls DsExcel uses zero-based indexing while placing the form controls on a worksheet. You can find a form control in the worksheet using its name or its type. To find an excel form control by its name, you can use [getName](/document-solutions/java-excel-api/api/online/com/grapecity/documents/excel/forms/IControl.html#getName) method to look for the specified name. While to find a control using its type, you can use the [getFormControlType](/document-solutions/java-excel-api/api/online/com/grapecity/documents/excel/forms/IControl.html#getFormControlType) method. See the code below to find the control by its name: ```Java // Create a new workbook Workbook workbook = new Workbook(); IWorksheet ws = workbook.getWorksheets().get("Sheet1"); // Add the control ILabel lblResolution = ws.getControls().addLabel(12.6, 20.4, 49.2, 18.6); lblResolution.setText("Resolution"); lblResolution.setPrintObject(true); lblResolution.setName("lblResolution"); // Find the control by name System.out.println(ws.getControls().get("lblResolution").getName()); ``` See the code below to find the control by its type: ```Java for (IControl ctl : ws.getControls()) { switch (ctl.getFormControlType()) { case Button: ctl.setWidth(70); break; case CheckBox: ctl.setWidth(60); break; default: break; } } ``` ## Export Form Controls Worksheets with form controls can be exported to PDF, XLSX, XLSM, HTML, .sjs, or SSJSON formats using [save](/document-solutions/java-excel-api/api/online/com/grapecity/documents/excel/Workbook.html#save) method of the Workbook class and to PNG, SVG, JPG, or GIF formats using [toImage](/document-solutions/java-excel-api/api/online/com/grapecity/documents/excel/IWorksheet.html#toImage) method of the IWorksheet interface. DsExcel provides [setVisible](/document-solutions/java-excel-api/api/online/com/grapecity/documents/excel/forms/IControl.html#setVisible) method in [IControl](/document-solutions/java-excel-api/api/online/com/grapecity/documents/excel/forms/IControl.html) interface that enables you to include or exclude the form controls while exporting. If you set Visible property of a form control to false, then that form control is not exported to either PDF, XLSX, XLSM, .sjs, SSJSON, HTML, PNG, SVG, JPG, or GIF formats. Refer to the following example code to exclude a form control from exporting: ```Java // 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); // Set Visible to false. dropDown.setVisible(false); ``` >type=note > **Note**: DsExcel exports the form controls as static images in the PNG, SVG, JPG, GIF, HTML, or PDF format. For exporting form controls to interactive form fields in PDF, see [Export Form Controls to Form Fields](/document-solutions/java-excel-api/docs/online/ManageFileOperations/ExporttoaPDFFile/ExportFormControlstoFormFields). ## Form Control Shapes DsExcel Java form controls are also shapes. Hence, to recognize whether a particular shape is a form control, [ShapeType](/document-solutions/java-excel-api/api/online/com/grapecity/documents/excel/drawing/ShapeType.html) enumeration provides a **FormControl** member. To add onto this, if a shape is a form control, you can get the form control associated with the shape using the **getControl** method of the [IShape](/document-solutions/java-excel-api/api/online/com/grapecity/documents/excel/drawing/IShape.html) interface. Also, you can get shape associated with a form control using [getShapeRange](/document-solutions/java-excel-api/api/online/com/grapecity/documents/excel/forms/IControl.html#getShapeRange) method of the [IControl](/document-solutions/java-excel-api/api/online/com/grapecity/documents/excel/forms/IControl.html) interface. Refer to the following code to use form control as shape: ```Java Workbook workbook = new Workbook(); IWorksheet ws = workbook.getWorksheets().get("Sheet1"); // Add form control IButton button1 = ws.getControls().addButton(50, 100, 120, 40); IShape buttonShape1 = button1.getShapeRange().get(0); // Duplicate buttonShape1.duplicate(); // Size and move buttonShape1.setLeft(66.6); buttonShape1.setTop(22.8); buttonShape1.setWidth(155.4); buttonShape1.setHeight(49.2); // Delete buttonShape1.delete(); ``` ## Add Option Button Group In DsExcel, two or more option buttons can be grouped in a group box so that you can select one choice from several related but mutually exclusive choices. DsExcel groups the option buttons using the [getGroupBox](/document-solutions/java-excel-api/api/online/com/grapecity/documents/excel/forms/IOptionButton.html#getGroupBox) method (read only) of [IOptionButton](/document-solutions/java-excel-api/api/online/com/grapecity/documents/excel/forms/IOptionButton.html) interface which is identified by the boundaries of option buttons and group boxes. The getGroupBox method is the first matched group box if an option button lies entirely within a group box. If there are no matching group boxes, the option button is in the default group, which is the worksheet. When two or more option buttons are in the same group, they affect the selection state of other option buttons and allow you to select only one option button at a time in the same group. They also share the [setLinkedCell](/document-solutions/java-excel-api/api/online/com/grapecity/documents/excel/forms/ICellLinkControl.html#setLinkedCell) method, which means you can define setLinkedCell for one option button in the group, and other option buttons in the same group can use the setLinkedCell value. >type=note > **Note**: Explicitly recalculate option button groups by calling **Cut(Left,Top)** on each group box control when a group box or option button loses focus. Refer to the following example code to add two separate group boxes, each with respective linked option buttons: ```Java // // Initialize Workbook. Workbook workbook = new Workbook(); //Create a worksheet. IWorksheet ws = workbook.getWorksheets().get("Sheet1"); //Add option buttons and group boxes to the worksheet. String rngB2 = "Option buttons are grouped by group boxes."; ws.getRange("B2").setValue(rngB2); ws.getRange("B13:C13").setValue( new Object[][] { { "Value", 1d} }); ws.getRange("E13:F13").setValue(new Object[][] { { "Value", 2d} }); ws.getRange("A:A").setColumnWidthInPixel(37d); //Add first group box. IGroupBox group1 = ws.getControls().addGroupBox(29.75, 48.2, 136.5, 113.99); group1.setText("Group 1"); //Add option buttons. IOptionButton optionButton2 = ws.getControls().addOptionButton(39.45, 67.1, 98, 15.60); optionButton2.setLinkedCell(ws.getRange("C13")); optionButton2.setIsChecked(true); ws.getControls().addOptionButton(39.45, 97.5, 98, 17.40); ws.getControls().addOptionButton(39.45, 131.2, 98, 17.5); //Add second group box. IGroupBox group2 = ws.getControls().addGroupBox(191.95, 48.2, 136.5, 113.99); group2.setText("Group 2"); //Add option buttons. ws.getControls().addOptionButton(200.35, 65.7, 117.6, 18.5); IOptionButton optionButton7 = ws.getControls().addOptionButton(200.35, 95.99, 117.6, 21.28); //Set linked cell. optionButton7.setLinkedCell(ws.getRange("F13")); optionButton7.setIsChecked(true); ws.getControls().addOptionButton(200.35, 129.2, 117.6, 21.40); //Save the workbook. workbook.save("OptionButtonsBasicUsage.xlsx"); ``` ![](https://cdn.mescius.io/document-site-files/images/dd59ea42-cd61-4fa6-a018-6231c2a9c598/images/option-button-group.gif) >type=note > **Note**: Adding option buttons to overlapping group boxes may not be the same as in Microsoft Excel. **Limitations** * Rich text and styles in DsExcel Java form controls are not supported for PDF export and API. * Getting or setting macro names in form controls requires VBA project. * VBA project and COM interoperability is required for invoking macro when OnAction. * LinkedObject and ｀Copy to Clipboard¨ features require Window OLE automation interoperability. * Spell check in Excel form controls requires Windows language pack interoperability. * There is loss of some nodes during Excel I/O of alternate content in drawing Xml and Vml. * In the option button group, some option buttons will join a different group when the measuring result differs from Excel.