Skip to content

@tool() Decorator

Registers a class as a LinkCAD tool that appears in the application menu with an auto-generated options dialog.

Signature

@tool(
    name: str,
    menu: str = "Tools/Python",
    tooltip: str = "",
    shortcut: str = "",
    icon: str = "",
    requires_drawing: bool = True,
)
class MyTool(Tool):
    ...

Parameters

Parameter	Type	Default	Description
`name`	`str`	required	Display name in the menu
`menu`	`str`	`"Tools/Python"`	Menu path (use `/` for submenus)
`tooltip`	`str`	`""`	Tooltip shown on hover
`shortcut`	`str`	`""`	Keyboard shortcut (e.g. `"Ctrl+Shift+M"`)
`icon`	`str`	`""`	Path to icon file (PNG, 24×24)
`requires_drawing`	`bool`	`True`	Whether the tool requires an open drawing

Tool Base Class

All tool plugins must extend Tool and implement run():

class Tool:
    def run(self, drawing) -> None:
        """Override to implement the tool logic."""
        ...

The drawing argument provides access to the current drawing. If requires_drawing=False, this may be None.

ToolInfo

The decorator creates a ToolInfo named tuple attached to the class:

Field	Description
`name`	Tool display name
`menu`	Menu path
`tooltip`	Tooltip text
`shortcut`	Keyboard shortcut
`icon`	Icon path
`requires_drawing`	Whether a drawing is required

The menu parameter defines where the tool appears in LinkCAD’s menu:

"Tools/Python"         → Tools → Python → <tool name>
"Tools/Analysis"       → Tools → Analysis → <tool name>
"Tools/Drawing/Custom" → Tools → Drawing → Custom → <tool name>

Complete Example

from linkcad.v1.plugin import tool, Tool, Option

@tool(
    name="Shape Counter",
    menu="Tools/Analysis",
    tooltip="Count shapes per layer",
    shortcut="Ctrl+Shift+C",
    requires_drawing=True,
)
class ShapeCounter(Tool):
    include_refs = Option.boolean("Include cell references", default=False)

    def run(self, drawing) -> None:
        total = 0
        for layer_name, shapes in drawing.shapes_by_layer():
            count = sum(1 for _ in shapes)
            total += count
            print(f"{layer_name}: {count}")
        print(f"Total: {total}")