Widgets#

Diagram Widget#

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

An Elk diagramming widget to help coordinate the Viewer and Pipe

Attributes#

source: MarkElementWidget

input source to the diagram’s processing pipe

pipe: Pipe

processing pipe (that may contain sub-pipes). Pipes perform various tasks like adding x/y and width/height layouts or calculating text label sizes. The diagram owns its pipe and every pipe nested in it. A new pipe, or a stage added to a pipeline’s pipes, is refused if any pipe in it is closed, owned by another open diagram, or part of the current pipe. A stage removed from pipes is released, not closed. Replacing the pipe or closing the diagram closes the pipe, its sub-pipes and the widgets they created (such as status views), but never source or an inlet/outlet passed in.

view: Viewer

output view that will render the pipe outlet; closed with the diagram

tools: tuple Tool

list of tools that a user of the diagram might use to manipulate the state of the diagram; closed with the diagram.

symbols: SymbolSpec

additional shape definitions that can be used in rendering the diagram. For example unique arrow head shapes or custom node shapes.

close()#

Close the diagram with its pipe, view, tools and toolbar.

source and any inlet or outlet passed to a pipe stay open.

get_tool(tool_type)#

Get the tool that matches the given Tool type.

Parameters:

tool_type (Type[Tool]) – get specific tool instance based on matched type.

Return type:

Tool

refresh(sender=None)#

Create asynchronous refresh task which will update the view given any changes.

sender is ignored; it lets refresh serve as a tool’s on_done callback (which receives the tool). Returns None when no event loop is running (see Pipe.schedule_run).

Return type:

Task | None

register_tool(tool)#

Add a new tool to the diagram.

Parameters:

tool (Tool) – new tool instance to add to the diagram.

Return type:

Diagram

Returns:

current Diagram instance

source#

Syncs Elk JSON Elements

Viewer Widget#

class ipyelk.diagram.Viewer(*args: t.Any, **kwargs: t.Any)#

Generic Viewer of ELK JSON diagrams. Currently only mainly used by SprottyViewer

Attributes#

parameter source:

MarkElementWidget input source for rendering.

parameter selection:

Selection maintains selected ids and methods to resolve the python elements.

parameter hover:

Hover maintains the hovered id.

parameter viewport:

Viewport the camera (origin, zoom, canvas size, viewed ids) of the most recently reporting view, written by the browser. Move a view with set_viewport().

parameter painter:

Painter temporary, view-only CSS classes per element id, applied in every view without touching the model.

parameter control_overlay:

ControlOverlay or None additional JupyterLab widgets that can be rendered on top of the diagram based on the current selected states. Opt-in: None (the default) and an overlay without children render nothing.

center(model_ids=None, animate=None, retain_zoom=None)#

Center the view on model_ids (the whole diagram if None).

A str is one id, never a sequence of characters. The generic viewer has no viewport of its own, so this does nothing; subclasses that render (SprottyViewer) implement it with the same signature.

Return type:

None

close()#

Close the viewer and its tools, not source or control_overlay.

fit(model_ids=None, animate=None, max_zoom=None, padding=None)#

Pan/zoom the view to focus on model_ids (the whole diagram if None).

A str is one id, never a sequence of characters. The generic viewer has no viewport of its own, so this does nothing; subclasses that render (SprottyViewer) implement it with the same signature.

Return type:

None

pan#

Removed in 3.0; raises DeprecatedAPIError throughout 3.x. Viewer.pan was removed in ipyelk 3.0: the Pan tool was a placeholder that nothing ever wrote. Read viewer.viewport.origin and viewer.viewport.canvas_size (the browser’s latest report, None until one arrives) and move a view with viewer.set_viewport(origin=(x, y)). No alias: this error is raised throughout 3.x.

viewed#

Removed in 3.0; raises DeprecatedAPIError throughout 3.x. Viewer.viewed was removed in ipyelk 3.0: nothing ever wrote it. Read viewer.viewport.viewed_ids (the ids whose bounds touch the reporting view’s visible rectangle; None until the browser reports). No alias: this error is raised throughout 3.x.

zoom#

removed names raise DeprecatedAPIError through 3.x

class ipyelk.diagram.SprottyViewer(*args: t.Any, **kwargs: t.Any)#

JupyterLab widget for displaying and interacting with views generated from ELK JSON.

Setting the instance’s value traitlet to valid Eclipse Layout Kernel JSON will call the elkjs layout method and display the returned mark_layout using sprotty.

center(model_ids=None, animate=None, retain_zoom=None)#

Center Diagram View on specified model ids

Parameters:

  • model_ids (str | Sequence[str] | None) – one elk model id, or a sequence of them; None (default) centers the whole diagram

  • animate (bool | None) – specify is the view animates to the given marks

  • retain_zoom (bool | None) – specify if the current zoom level is maintained

Return type:

None

fit(model_ids=None, animate=None, max_zoom=None, padding=None)#

Pan/Zoom the Diagram View to focus on particular model ids

Parameters:

  • model_ids (str | Sequence[str] | None) – one elk model id, or a sequence of them; None (default) fits the whole diagram

  • animate (bool | None) – specify is the view animates to the given marks

  • max_zoom (float | None) – specify if the max zoom level

  • padding (float | None) – specify if the viewport padding around the marks

Return type:

None

set_viewport(*, origin=None, zoom=None, animate=True, view_id=None)#

Move the camera of the connected view(s).

A command, not state: the browser applies it and then reports the resulting camera through viewport.

Parameters:

  • origin (tuple[float, float] | None) – diagram coordinates for the canvas top-left corner; None keeps the view’s current origin

  • zoom (float | None) – CSS pixels per diagram unit; None keeps the current zoom

  • animate (bool) – animate the move (default) or jump

  • view_id (str | None) – only the view with this id (see ipyelk.tools.Viewport.view_id); None moves every connected view

Return type:

None