Skip to content

Form Controls ​

Insert form controls into worksheets. SheetKit writes worksheet control metadata and control-property parts with a VML (Vector Markup Language) fallback, and supports buttons, check boxes, option buttons, spin buttons, scroll bars, group boxes, and labels.

Supported Control Types ​

Type StringRust EnumDescription
buttonFormControlType::ButtonCommand button
checkboxFormControlType::CheckBoxCheck box
optionButtonFormControlType::OptionButtonOption (radio) button
spinButtonFormControlType::SpinButtonSpin button
scrollBarFormControlType::ScrollBarScroll bar
groupBoxFormControlType::GroupBoxGroup box
labelFormControlType::LabelLabel

Control type strings are case-insensitive. Aliases like "radio" for "optionButton", "spin" for "spinButton", "scroll" for "scrollBar", and "group" for "groupBox" are also accepted.

add_form_control / addFormControl ​

Add a form control to a sheet.

Rust:

rust
use sheetkit::{FormControlConfig, FormControlType};

// Button
let config = FormControlConfig::button("B2", "Click Me");
wb.add_form_control("Sheet1", config)?;

// Checkbox with cell link
let mut config = FormControlConfig::checkbox("B4", "Enable Feature");
config.cell_link = Some("$D$4".to_string());
config.checked = Some(true);
wb.add_form_control("Sheet1", config)?;

// Spin button
let config = FormControlConfig::spin_button("E2", 0, 100);
wb.add_form_control("Sheet1", config)?;

// Scroll bar
let config = FormControlConfig::scroll_bar("F2", 0, 200);
wb.add_form_control("Sheet1", config)?;

TypeScript:

typescript
// Button
wb.addFormControl("Sheet1", {
    controlType: "button",
    cell: "B2",
    text: "Click Me",
});

// Checkbox with cell link
wb.addFormControl("Sheet1", {
    controlType: "checkbox",
    cell: "B4",
    text: "Enable Feature",
    cellLink: "$D$4",
    checked: true,
});

// Spin button
wb.addFormControl("Sheet1", {
    controlType: "spinButton",
    cell: "E2",
    minValue: 0,
    maxValue: 100,
    increment: 5,
    currentValue: 50,
});

// Scroll bar
wb.addFormControl("Sheet1", {
    controlType: "scrollBar",
    cell: "F2",
    minValue: 0,
    maxValue: 200,
    pageIncrement: 10,
});

get_form_controls / getFormControls ​

Get all form controls on a sheet. Returns an array of FormControlInfo objects.

Rust:

rust
let controls = wb.get_form_controls("Sheet1")?;
for ctrl in &controls {
    println!("{:?}: {}", ctrl.control_type, ctrl.cell);
}

TypeScript:

typescript
const controls = wb.getFormControls("Sheet1");
for (const ctrl of controls) {
    console.log(`${ctrl.controlType}: ${ctrl.cell}`);
}

delete_form_control / deleteFormControl ​

Delete a form control by its 0-based index in the control list.

Rust:

rust
wb.delete_form_control("Sheet1", 0)?;

TypeScript:

typescript
wb.deleteFormControl("Sheet1", 0);

FormControlConfig ​

FieldRust TypeTS TypeRequiredDescription
control_type / controlTypeFormControlTypestringYesControl type (see table above)
cellStringstringYesAnchor cell (top-left corner, e.g., "B2")
widthOption<f64>number?NoWidth in points (auto-sized by default)
heightOption<f64>number?NoHeight in points (auto-sized by default)
textOption<String>string?NoDisplay text (Button, CheckBox, OptionButton, GroupBox, Label)
macro_name / macroNameOption<String>string?NoVBA macro name (Button only)
cell_link / cellLinkOption<String>string?NoLinked cell for value binding (CheckBox, OptionButton, SpinButton, ScrollBar)
checkedOption<bool>boolean?NoInitial checked state (CheckBox, OptionButton)
min_value / minValueOption<u32>number?NoMinimum value (SpinButton, ScrollBar)
max_value / maxValueOption<u32>number?NoMaximum value (SpinButton, ScrollBar)
incrementOption<u32>number?NoStep increment (SpinButton, ScrollBar)
page_increment / pageIncrementOption<u32>number?NoPage increment (ScrollBar only)
current_value / currentValueOption<u32>number?NoCurrent value (SpinButton, ScrollBar)
three_d / threeDOption<bool>boolean?NoEnable 3D shading (default: true)

FormControlInfo ​

FieldRust TypeTS TypeDescription
control_type / controlTypeFormControlTypestringControl type
cellStringstringAnchor cell reference
textOption<String>string?Display text
macro_name / macroNameOption<String>string?VBA macro name
cell_link / cellLinkOption<String>string?Linked cell reference
checkedOption<bool>boolean?Checked state
current_value / currentValueOption<u32>number?Current value
min_value / minValueOption<u32>number?Minimum value
max_value / maxValueOption<u32>number?Maximum value
incrementOption<u32>number?Step increment
page_increment / pageIncrementOption<u32>number?Page increment

Notes ​

  • Form controls use worksheet control metadata and xl/ctrlProps/ parts with a VML fallback (xl/drawings/vmlDrawingN.vml), not DrawingML.
  • Form controls can coexist with comments on the same sheet. When both are present, the VML content is merged into a single file.
  • Form controls can also coexist with charts, images, and shapes on the same sheet.
  • The cellLink field binds a control's value to a worksheet cell. For check boxes, the linked cell receives TRUE/FALSE. For spin buttons and scroll bars, it receives the numeric value.
  • Button controls support the macroName field to associate a VBA macro.
  • Default dimensions are automatically applied per control type if width/height are not specified.

Released under the MIT / Apache-2.0 License.