Option Types

The Option class provides factory methods for defining typed, persistent options that generate UI controls in tool and format plugin dialogs.

Common Parameters

All option factories accept these parameters:

Parameter	Type	Description
`label`	`str`	Display label (first positional argument)
`default`	varies	Default value
`tooltip`	`str`	Tooltip text
`enabled_when`	`callable`	Callback returning `bool` — controls visibility

Option.integer()

Spin box for integer values.

count = Option.integer("Count", default=1, min=0, max=1000)

Parameter	Type	Default	Description
`default`	`int`	`0`	Default value
`min`	`int`	`None`	Minimum value
`max`	`int`	`None`	Maximum value

Option.real()

Double spin box for floating-point values.

scale = Option.real("Scale Factor", default=1.0, min=0.001, max=1e6, decimals=4)

Parameter	Type	Default	Description
`default`	`float`	`0.0`	Default value
`min`	`float`	`None`	Minimum value
`max`	`float`	`None`	Maximum value
`decimals`	`int`	`2`	Decimal places displayed

Option.boolean()

Checkbox for true/false values.

flatten = Option.boolean("Flatten hierarchy", default=False)

Parameter	Type	Default	Description
`default`	`bool`	`False`	Default value

Option.string()

Single-line text field.

name = Option.string("Output name", default="output")

Parameter	Type	Default	Description
`default`	`str`	`""`	Default value

Option.choice()

Dropdown selector.

mode = Option.choice("Mode", choices=["Fast", "Precise", "Custom"], default="Fast")

Parameter	Type	Default	Description
`choices`	`list[str]`	required	Available options
`default`	`str`	first choice	Default selection

Option.path()

File path picker with browse button.

output = Option.path("Output file", file_filter="CSV Files (*.csv)")

Parameter	Type	Default	Description
`default`	`str`	`""`	Default path
`file_filter`	`str`	`""`	File type filter string

Option.color()

Color picker button.

fill = Option.color("Fill color", default="#FF0000")

Parameter	Type	Default	Description
`default`	`str`	`"#000000"`	Default color (hex)

Option.cell_choice()

Dropdown populated with all cell names from the current drawing.

target = Option.cell_choice("Target cell")

Parameter	Type	Default	Description
`default`	`str`	`""`	Default cell name

Option.table()

Editable grid with typed columns. See also Panel Assembly Tutorial.

entries = Option.table(
    "My Table",
    columns=[
        TableColumn(key="name", label="Name", col_type="string"),
        TableColumn(key="value", label="Value", col_type="real", decimals=3),
    ],
)

Parameter	Type	Default	Description
`columns`	`list[TableColumn]`	required	Column definitions
`default`	`list[dict]`	`[]`	Default rows

The value is a list[dict] where each dict maps column keys to values.

TableColumn

Property	Type	Description
`key`	`str`	Dict key for this column
`label`	`str`	Column header
`col_type`	`str`	`string`, `integer`, `real`, `choice`, `cell_choice`
`default`	`Any`	Default value for new rows
`choices`	`list[str]`	Options for `choice` columns
`decimals`	`int`	Decimal places for `real` columns
`min_value`	`int\|float`	Minimum for numeric columns
`max_value`	`int\|float`	Maximum for numeric columns

Conditional Visibility

Use enabled_when to dynamically enable/disable options:

class MyTool(Tool):
    mode = Option.choice("Mode", choices=["Simple", "Advanced"])
    threshold = Option.real(
        "Threshold",
        default=0.5,
        enabled_when=lambda self: self.mode == "Advanced",
    )
    iterations = Option.integer(
        "Iterations",
        default=10,
        enabled_when=lambda self: self.mode == "Advanced",
    )

When mode is “Simple”, the threshold and iterations fields are grayed out.