Skip to content
Back to top
View this page

# 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.