@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

Menu Path

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.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}")