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 receiving `self`, returning `bool` — greys the control out when `False`
`name`	`str`	Keyword-only. Overrides the generated option key

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`	`0`	Minimum value
`max`	`int`	`999999`	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`	`0.0`	Minimum value
`max`	`float`	`1e9`	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.

Option Keys

Each option is persisted under a string key. When an Option is used as a class attribute, LinkCAD generates that key as PyPlugin.<Class>.<attribute>. The reserved PyPlugin root keeps plugin options out of the application’s own settings namespace, and the class segment keeps two plugins that both call an option flatten apart:

class AsciiWriter(FormatWriter):
    flatten = Option.boolean("Flatten hierarchy", default=False)
    # persisted as "PyPlugin.AsciiWriter.flatten"

The attribute name is used as written, so the key and the Python attribute that reads it are spelled the same. Every option is also settable from the command line under that key:

linkcad --PyPlugin.AsciiWriter.flatten=1 ...

Pass the keyword-only name argument to choose the key yourself:

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

Option values are loaded onto the instance before run(), read(), or write() is called, so inside those methods self.flatten is the current value. Setting the attribute directly also works, which is what makes a plugin drivable from the script editor without opening its dialog.