Package io.keikai.axyra.sheets.content

Class FormControl

java.lang.Object
io.keikai.axyra.sheets.content.FormControl
public final class FormControl extends Object
A worksheet form control (immutable): check box, option button, button, combo box, list box, scroll bar, spin button, edit box, label or group box — the classic Form Controls group on Excel's Developer tab. Add with Sheet.addFormControl(...); read back with Sheet.formControls(); replace with Sheet.updateFormControl(index, control). Crosses the boundary as flat JSON.

The anchor is a two-cell rectangle in 0-based row/column coordinates, optionally refined by EMU offsets inside the corner cells. Per-type state: checked (check box / option button), listFillRange + selectedIndex + dropLines (combo / list box), value/min/max/increment/page (scroll bar / spin button), text (caption shown by captioned controls), linkedCell (cell reflecting the control's state) and threeD (the 3-D shading flag of the Format Control dialog).

Values are checked only when the control is added or updated: a wrong type or a number outside its range makes the sheet call throw AxyraException. 


 sheet.addFormControl(FormControl.checkBox("Approved")
         .anchor(1, 1, 2, 3)          // B2 to the top-left of D3
         .linkedCell("A2")
         .text("Approved")
         .build());

Reference: ECMA-376 Part 1 §18.3.1.13 (controls) plus the <formControlPr> control-properties part.

  • Method Details

    • checkBox

      public static FormControl.Builder checkBox(String name)
      A check box; set state with .checked(true).

    • optionButton

      public static FormControl.Builder optionButton(String name)
      An option (radio) button; set state with .checked(true).

    • button

      public static FormControl.Builder button(String name)
      A push button; the caption comes from .text(...) or the name.

    • comboBox

      public static FormControl.Builder comboBox(String name)
      A drop-down combo box; feed it with .listFillRange("F1:F5").

    • listBox

      public static FormControl.Builder listBox(String name)
      A list box; feed it with .listFillRange("F1:F5").

    • scrollBar

      public static FormControl.Builder scrollBar(String name)
      A scroll bar; configure .range(min, max) / .value(v).

    • spinButton

      public static FormControl.Builder spinButton(String name)
      A spin button; configure .range(min, max) / .value(v).

    • editBox

      public static FormControl.Builder editBox(String name)
      An edit box (legacy dialog-sheet control).

    • label

      public static FormControl.Builder label(String name)
      A static text label.

    • groupBox

      public static FormControl.Builder groupBox(String name)
      A group box frame (visually groups option buttons).

    • of

      public static FormControl.Builder of(FormControlType type, String name)
      A control of any FormControlType. FormControlType.UNKNOWN cannot be written: Sheet.addFormControl and Sheet.updateFormControl throw AxyraException for it.
      Throws:
      NullPointerException - if type is null

    • toBuilder

      public FormControl.Builder toBuilder()
      A builder pre-loaded with this control, for read–modify–write round trips. A control read back as FormControlType.UNKNOWN cannot be written back.

    • toJson

      public String toJson()
      The control as the JSON object sent to the engine. Used by the SDK.

    • fromJson

      public static FormControl fromJson(String json)
      Builds a control from the engine's JSON, the form behind Sheet.formControls(). Used by the SDK.

    • type

      public FormControlType type()
      The control kind; FormControlType.UNKNOWN for a token the SDK does not know.

    • name

      public String name()
      The shape name, e.g. "Check Box 1".

    • fromRow

      public int fromRow()
      The 0-based row of the anchor's top-left cell.

    • fromColumn

      public int fromColumn()
      The 0-based column of the anchor's top-left cell.

    • toRow

      public int toRow()
      The 0-based row of the cell that holds the anchor's bottom-right corner; at zero row offset that cell is not covered.

    • toColumn

      public int toColumn()
      The 0-based column of the cell that holds the anchor's bottom-right corner; at zero column offset that cell is not covered.

    • linkedCell

      public String linkedCell()
      Linked cell in A1 form (e.g. "A1", "Sheet2!B3"), or null.

    • listFillRange

      public String listFillRange()
      Items source range in A1 form for combo / list boxes, or null.

    • checked

      public boolean checked()
      Check box / option button state.

    • selectedIndex

      public int selectedIndex()
      The 1-based selected item of a combo box or list box; 0 means no selection, and also when the control does not store the value.

    • dropLines

      public int dropLines()
      Visible drop-down rows of a combo box; 0 when the control does not store it, in which case Excel shows 8.

    • value

      public int value()
      Current value of a scroll bar or spin button; 0 when the control does not store it.

    • min

      public int min()
      Minimum value of a scroll bar or spin button; 0 when the control does not store it.

    • max

      public int max()
      Maximum value of a scroll bar or spin button; 0 when the control does not store it.

    • increment

      public int increment()
      The step of one arrow click on a scroll bar or spin button; 0 when the control does not store it.

    • page

      public int page()
      The step of one click on a scroll bar's track; 0 when the control does not store it.

    • text

      public String text()
      Caption text painted by captioned controls, or null (name is used).

    • threeD

      public boolean threeD()
      The 3-D shading flag of the Format Control dialog.