Skip to content

linkcad.plugin

The plugin module provides the framework for creating tools, format readers, and format writers.

Decorators

@tool()

Registers a class as a menu tool. See Tool Decorator.

@tool(name="My Tool", menu="Tools/Custom")
class MyTool(Tool):
    def run(self, drawing) -> None:
        ...

@format_reader()

Registers a class as a file import format. See Format Decorators.

@format_reader(name="My Format", extensions=["*.myf"])
class MyReader(FormatReader):
    def read(self, path: Path, drawing: DrawingContext) -> None:
        ...

@format_writer()

Registers a class as a file export format. See Format Decorators.

@format_writer(name="My Format", extensions=["*.myf"])
class MyWriter(FormatWriter):
    def write(self, path: Path, drawing: WriterContext) -> None:
        ...

Option Class

Option provides factory methods for defining typed, persistent options:

Factory Result Type UI Control
Option.integer(label, default, min, max) int Spin box
Option.real(label, default, min, max, decimals) float Double spin box
Option.boolean(label, default) bool Checkbox
Option.string(label, default) str Text field
Option.choice(label, choices, default) str Dropdown
Option.path(label, default, file_filter) str File picker
Option.color(label, default) str Color picker
Option.table(label, columns, default) list[dict] Editable grid
Option.cell_choice(label, default) str Cell dropdown

All factories accept optional tooltip and enabled_when parameters.

Context Classes

DrawingContext

Builder interface for format readers. Methods:

  • cell(name, main) — context manager for creating cells
  • iter_lines(path) — line iterator with progress
  • iter_binary(path, chunk_size) — binary iterator with progress
  • progress — get/set progress (0.0–1.0)

WriterContext

Reader interface for format writers. Methods:

  • shapes(cell, layer) — iterate shapes with progress
  • shapes_by_layer(cell) — shapes grouped by layer
  • shapes_by_cell(layer) — shapes grouped by cell
  • cells() — cell name iterator
  • layers() — layer name iterator
  • cell_count() / shape_count() — counts
  • main_cell_name() — top cell name
  • flatten — get/set hierarchy flattening

ShapeInfo

Data class yielded by WriterContext.shapes():

  • layer_name: str — layer name
  • cell_name: str — cell name
  • vertices: list[tuple] — (x, y) coordinates
  • is_polygon: bool — polygon vs. polyline
  • width: int — polyline width
  • is_closed: bool — whether the shape is closed

Exceptions

Exception Use
PluginError Base class for all plugin errors
ParseError File parsing errors (accepts line and path kwargs)
WriteError File writing errors
ValidationError Option validation errors

TableColumn

Data class for defining table option columns:

  • key: str — dict key
  • label: str — column header
  • col_type: str — string, integer, real, choice, cell_choice
  • default: Any — default value
  • choices: list[str] — for choice columns
  • decimals: int — for real columns
  • min_value / max_value — for numeric columns