Skip to content
Back to top
View this page

# Connections

The `Connections` class can be used to manage any type of constraint within, and between items.

class gaphas.connections.Connections(solver: Solver | None = None)

  Manage connections and constraints.

  add_handler(handler)

    Add a callback handler.

    Handlers are triggered when a constraint has been solved.

  remove_handler(handler)

    Remove a previously assigned handler.

  property solver: Solver

    The solver used by this connections instance.

  solve() → None

    Solve all constraints.

  add_constraint(item: Item, constraint: Constraint) → Constraint

    Add a “simple” constraint for an item.

  remove_constraint(item: Item, constraint: Constraint) → None

    Remove an item specific constraint.

  connect_item(item: Item, handle: Handle, connected: Item, port: Port | None, constraint: Constraint | None = None, callback: Callable[[Item, Handle, Item, Port], None] | None = None) → None

    Create a connection between two items. The connection is registered and the constraint is added to the constraint solver.

    The pair `(item, handle)` should be unique and not yet connected.

    The callback is invoked when the connection is broken.

    Parameters:

      - item (Item) – Connecting item (i.e. a line).

      - handle (Handle) – Handle of connecting item.

      - connected (Item) – Connected item (i.e. a box).

      - port (Port) – Port of connected item.

      - constraint (Constraint) – Constraint to keep the connection in place.

      - callback (() -> None) – Function to be called on disconnection.

    `ConnectionError` is raised in case handle is already registered on a connection.

  disconnect_item(item: Item, handle: Handle | None = None) → None

    Disconnect the connections of an item.

    If handle is not None, only the connection for that handle is disconnected.

  remove_connections_to_item(item: Item) → None

    Remove all connections (handles connected to and constraints) for a specific item (to and from the item).

    This is some brute force cleanup (e.g. if constraints are referenced by items, those references are not cleaned up).

  reconnect_item(item: Item, handle: Handle, port: Port | None = None, constraint: Constraint | None = None) → None

    Update an existing connection.

    This is used to provide a new constraint to the connection. `item` and `handle` are the keys to the to-be-updated connection.

  get_connection(handle: Handle) → Connection | None

    Get connection information for specified handle.

        >>> c = Connections()
        >>> from gaphas.item import Line
        >>> line = Line()
        >>> from gaphas import item
        >>> i = item.Line()
        >>> ii = item.Line()
        >>> c.connect_item(i, i.handles()[0], ii, ii.ports()[0])
        >>> c.get_connection(i.handles()[0])
        Connection(item=<gaphas.item.Line object at 0x...)
        >>> c.get_connection(i.handles()[1])
        >>> c.get_connection(ii.handles()[0])

  get_connections(item: Item | None = None, handle: Handle | None = None, connected: Item | None = None, port: Port | None = None) → Iterator[Connection]

    Return an iterator of connection information.

    The list contains (item, handle). As a result an item may be in the list more than once (depending on the number of handles that are connected). If `item` is connected to itself it will also appear in the list.

        >>> c = Connections()
        >>> from gaphas import item
        >>> i = item.Line()
        >>> ii = item.Line()
        >>> iii = item.Line()
        >>> c.connect_item(i, i.handles()[0], ii, ii.ports()[0], None)

        >>> list(c.get_connections(item=i))
        [Connection(item=<gaphas.item.Line object at 0x...]
        >>> list(c.get_connections(connected=i))
        []
        >>> list(c.get_connections(connected=ii))
        [Connection(item=<gaphas.item.Line object at 0x...]

        >>> c.connect_item(ii, ii.handles()[0], iii, iii.ports()[0], None)
        >>> list(c.get_connections(item=ii))
        [Connection(item=<gaphas.item.Line object at 0x...]
        >>> list(c.get_connections(connected=iii))
        [Connection(item=<gaphas.item.Line object at 0x...]