Handles and Ports

To connect one item to another, you need something to connect, and something to connect to. These roles are fulfilled by Handle and Port.

The Handle is an item you normally see on screen as a small square, either green or red. Although the actual shape depends on the Painter used.

Ports represent the receiving side. A port decides if it wants a connection with a handle. If it does, a constraint can be created and this constraint will be managed by a Connections instance. It is not uncommon to create special ports to suite your application’s behavior, whereas Handles are rarely subtyped.

Handle

class gaphas.connector.Handle(pos: tuple[float, float] = (0, 0), strength: int = 20, connectable: bool = False, movable: bool = True)

Handles are used to support modifications of Items.

If the handle is connected to an item, the connected_to property should refer to the item. A disconnect handler should be provided that handles all disconnect behaviour (e.g. clean up constraints and connected_to).

Note for those of you that use the Pickle module to persist a canvas: The property disconnect should contain a callable object (with __call__() method), so the pickle handler can also pickle that. Pickle is not capable of pickling instancemethod or function objects.

property pos

The Handle’s position

property connectable: bool

Can this handle actually connectect to a port?

property movable: bool

Can this handle be moved by a mouse pointer?

property visible: bool

Is this handle visible to the user?

property glued: bool

Is the handle being moved and about to be connected?

Port

The Port class. There are two default implementations: LinePort and PointPort.

class gaphas.connector.Port

Port connectable part of an item.

The Item’s handle connects to a port.

glue(pos: tuple[SupportsFloat, SupportsFloat]) → tuple[tuple[float, float], float]

Get glue point on the port and distance to the port.

constraint(item: Item, handle: Handle, glue_item: Item) → Constraint

Create connection constraint between item’s handle and glue item.

class gaphas.connector.LinePort(start: Position, end: Position)

Port defined as a line between two handles.

glue(pos: tuple[SupportsFloat, SupportsFloat]) → tuple[tuple[float, float], float]

Get glue point on the port and distance to the port.

>>> p1, p2 = (0.0, 0.0), (100.0, 100.0)
>>> port = LinePort(p1, p2)
>>> port.glue((50, 50))
((50.0, 50.0), 0.0)
>>> port.glue((0, 10))
((5.0, 5.0), 7.0710678118654755)

constraint(item: Item, handle: Handle, glue_item: Item) → Constraint

Create connection line constraint between item’s handle and the port.

class gaphas.connector.PointPort(point: Position)

Port defined as a point.

glue(pos: tuple[SupportsFloat, SupportsFloat]) → tuple[tuple[float, float], float]

Get glue point on the port and distance to the port.

>>> h = Handle((10, 10))
>>> port = PointPort(h.pos)
>>> port.glue((10, 0))
(<Position object on (10, 10)>, 10.0)

constraint(item: Item, handle: Handle, glue_item: Item) → MultiConstraint

Return connection position constraint between item’s handle and the port.