5.3 Connecting graphical objects

The primary application domain of XPCE is handling graphical modelling languages. Drawing in such languages often entails connecting graphical objects using lines. Instead of adding an instance of line to the graphical device at the proper place, it is much better to declare two graphical objects to be connected. Class connection provides for this.

To prepare an object for making connections, the object should first define handles. Below is a simple example. The link is a reusable object and therefore defined as a global reference. See section 10.3. The screendump is shown in figure 13.

:- pce_global(@in_out_link, make_in_out_link).

make_in_out_link(L) :-
        new(L, link(in, out, line(arrows := second))).

linked_box_demo :-
        new(P, picture('Linked Box demo')),
        send(P, open),
        send(P, display, new(B1, box(50,50)), point(20,20)),
        send(P, display, new(B2, box(25,25)), point(100,100)),
        send(B1, handle, handle(w, h/2, in)),
        send(B2, handle, handle(w/2, 0, out)),
        send_list([B1, B2], recogniser, new(move_gesture)),
        send(B1, connect, B2, @in_out_link).

Figure 13 : A connection between two boxes

If there are multiple handles of the same `kind' on a graphical, a connection will automatically try to connect to the `best' handle.

The classes related to making connections are summarised in table 4.

connection Subclass of class line. A connection can connect two graphicals on the same window that have handles. The line is automatically updated if either of the graphicals is moved, resized, changed from device, (un)displayed, hidden/exposed or destroyed.
handle Defines the location, nature and name of a connection point for a connection. Handles can be attached to individual graphicals as well as to their class.
link Defines the generic properties of a connection: the nature (`kind') of the handle at either side and the line attributes (arrows, pen and colour).
connect_gesture Event-processing object (see section 5.5) used to connect two graphical objects.
Table 4 : Classes used to define connections

Note that, as class connection is a subclass of graphical, connections can be created between connections. Class graphical defines various methods to help reading the relations expressed with connections and/or refine the generic connect_gesture.