Tool Widgets#

Tools#

class ipyelk.tools.Tool(**kwargs)#

An interactive element to control a diagram.

Execution lifecycle#

trigger() requests execution: it cancels a still-running request, schedules run() as an asyncio.Task and returns it. A tool that does not implement run() (state-only tools such as Selection, or callback tools such as ToolButton) rejects the request with NotImplementedError before anything is scheduled.
run() performs the work.
on_start callbacks (registered with on_start()) fire with the tool as their argument when the work actually starts, i.e. when the task first runs – not when trigger() is called, and never for a rejected request.
reports are recorded on the attached pipe (record_reports()) once the work has started and finishes – successfully, with an error, or cancelled – so partial changes from failed or cancelled work still reach the next refresh. Recording merges; it never drops another writer’s reports.
on_done callbacks (registered with on_done()) fire with the tool as their argument only after run() completes successfully and its change reports are recorded. They never fire when execution fails, is cancelled, or is rejected before starting. Errors are logged.
A request that was superseded by a newer trigger() is stale: its completion records its reports and, when it succeeded, still fires on_done, but it never touches the tool’s task state, which the newer request owns.

Both hooks are registration methods – tool.on_start(callback), tool.on_done(callback) – so several listeners (the owning Diagram registers its refresh on on_done) can coexist. Assigning tool.on_start = callback or tool.on_done = callback (the 2.x single-slot form) is an error.

check_enabled()#

Raise RuntimeError if an invocation must be rejected right now.

Return type:: None

close()#: Close the tool and the default ui it built, not one passed in.

disable#: Removed in 3.0; raises DeprecatedAPIError throughout 3.x. Tool.disable was removed in ipyelk 3.0: nothing read it, so it never disabled anything. Use tool.disabled (the ipywidgets name), which rejects trigger() and clicks and disables the controls under tool.ui.

disabled#: an execution guard: trigger() and button clicks are rejected, and every control under ui that has a disabled trait is disabled

handler#: removed names raise DeprecatedAPIError through 3.x

missing_dependencies()#

The _dependencies that are still None; empty when the tool is bound.

Return type:: tuple[str, ...]

on_done(callback, remove=False)#

The callback is called with one argument, the tool, only after run() completed successfully and its change reports were recorded – never on failure, cancellation, or a request rejected by trigger().

Parameters#

remove: bool (optional): set to true to remove the callback from the list of callbacks.

on_run#: Removed in 3.0; raises DeprecatedAPIError throughout 3.x. Tool.on_run was removed in ipyelk 3.0. Despite its name, on_run callbacks ran AFTER a successful run, not when the run started, so the name was ambiguous. Register tool.on_start(callback) for the actual start of the work, or tool.on_done(callback) for success only (both are called as callback(tool); on_done never fires on failure, cancellation, or a rejected trigger). No forwarding: this error is raised throughout 3.x.

on_start(callback, remove=False)#

The callback is called with one argument, the tool. It does not fire for a request rejected by trigger().

Parameters#

remove: bool (optional): set to true to remove the callback from the list of callbacks.

record_reports()#

Mark this tool’s reports as pending on the attached pipe.

The inlet flow is the set of pending reports every writer (tools, the diagram, the pipeline itself) shares; a pending report is a request some writer already made and this tool cannot know whether it was satisfied. The reports are therefore merged into the flow – order preserved, duplicates dropped – never assigned over it. No-op without a tee.

Return type:: None

trigger(*_)#

Request execution: schedule run() and return its task.

Positional arguments are ignored so the method can be an ipywidgets callback (button.on_click(tool.trigger)). Raises before scheduling anything when the request is rejected (see the class docstring).

Return type:: Task

class ipyelk.tools.ToolButton(**kwargs)#

Generic Tool that provides a simple button UI.

Clicking the button calls on_click(tool) synchronously; a ToolButton has no run() and does not use the trigger() lifecycle.

Parameters:: on_click – Called as on_click(tool) when the button is pressed.

Tool View Widgets#

class ipyelk.tools.Toolbar(*args: t.Any, **kwargs: t.Any)#

Toolbar for an Elk App.

Shows the ui of every tool in tools that has one, grouped by priority; tools without a UI (Selection, Hover, Viewport, Painter) hold state only and are not rendered.

close()#

Close method.

Closes the underlying comm. When the comm is closed, all of the widget views are automatically removed from the front-end.

on_close#: called as on_close(toolbar) when the close button is pressed; the button is only shown while this is set

order()#

The tool UIs grouped by priority; tools whose ui is None are omitted.

Return type:: dict[int, list[DOMWidget]]

tool_order()#

The tool UIs in display order: ascending priority, then tools order.

Return type:: list[DOMWidget]

class ipyelk.tools.ControlOverlay(*args: t.Any, **kwargs: t.Any)#: Simple Container Widget for rendering element specific JupyterLab widgets