A connect_gesture is used to create a connection
object between two
graphical objects
by dragging from the first to the second graphical
object. The gesture is connected to a graphical that can serve as an
origin (starting) point for a connection. Note that the graphical should
have handle objects
that can connect to the link
object associated with the gesture. Thus, if the link is created from
the term link(in, out), the graphical from which the
connection is started should have at least one handle of handle<-kind
in and the graphical at the other end should have at least
one handle of handle<-kind out.
This class provides a high-level user-interface for creating connections. The following program illustrates the use of PCE's graphical connection facilities:
connect_demo :-
send(new(P, picture('Connect Demo')), open),
send(P, recogniser,
click_gesture(left, '', single,
message(@prolog,
display_box, P,
@event?position))).
:- pce_global(@east, new(handle(0, h/2, any, east))).
:- pce_global(@north, new(handle(w/2, 0, any, north))).
:- pce_global(@west, new(handle(w, h/2, any, west))).
:- pce_global(@south, new(handle(w/2, h, any, south))).
:- pce_global(@connect_recogniser,
new(handler_group(connect_gesture(left, '',
link(any)),
new(move_gesture)))).
display_box(P, Pos) :-
send(P, display, new(B, box(30,30)), Pos),
send_list(B, handle,
[ @east, @north, @west, @south
]),
send(B, recogniser, @connect_recogniser).
Unfortunately possible links often rely on semantics too complicated to deal with by the handle and link naming mechanism. For this reason this class defines a large number of methods that may be redefined. The most commonly redefined are:
connect_gesture ->verifyAdditional tests, assign connect_gesture <-deviceconnect_gesture <-pointedDetermine graphical to link too connect_gesture ->indicateFind possible connection-points connect_gesture ->connectCreates the actual connection
The default methods allow for connecting objects displayed on the
same device. In principle, connect-gestures may be used to connect any
two objects displayed on the same window
object, arbitrary nested in device
objects. To use this feature, the
connect_gesture->verify
method should be redefined and should set connect_gesture->device
to the common device displaying both the origin and target objects (this
can be the window). The connect_gesture<-pointed
method should be redefined to find graphicals under the pointer that can
be used to connect to. The methods device<-find
and‘device
connect_gesture<-pointed’are
often useful to implement the connect_gesture<-pointed.
See also class handle,
class connection,
class link,‘graphical
connect_gesture->connect’.
The PceDraw demo illustrates the use of connections.
On a down event (of the appropriate button with the appropriate modifiers), the gesture will indicate the possible connection-points of the graphical with the from-side of the link using small markers. If the down occurs close to one specific handle, the gesture assumes this is the only handle the user wants to connect to. On termination, the from-side of the connection will be fixed to this handle. Otherwise all handles of the appropriate kind are indicated. In this case the connection will not be fixed and moving or resizing one of the objects may reconnect the connection to a visually more attractive handle.
On each subsequent drag event, the gesture will indicate valid
to-handles if they exist.
When the gesture is terminated after an up event, the appropriate connection is created.
-mark
<-from_indicators
and connect_gesture<-to_indicators
are displayed on this device. Also, the recognisers looks for possible
graphicals to connect too on this device. May be changed in a redefined connect_gesture->initiate
to any device in the same window that displays the receiving graphical.from side that has to be used for
the connection. @default
if there are more valid candidate handles, the name of the only
candidate otherwise. Set by connect_gesture->initiate.
<-mark
slot of the gesture.
<->link
of the gesture.->verify
method should be redefined to set the appropriate link value.
<-from_indicators
and connect_gesture<-to_indicators
chains. See also connect_gesture->indicated
->drag
and passed to
connect_gesture->connect
by connect_gesture->terminate.<-mark
slot of the gesture.
->terminate.
It's responsibility is to create the actual connection
object. The default implementation is to invoke graphical->connect
with the corresponding arguments. This method may be redefined.<-end of the connect_gesture<-line.
Next searches for graphicals on
connect_gesture<-device
that overlap with the pointer and have suitable handles. When found,
invokes connect_gesture->indicate
to provide visual feedback to the user on the matching handles.->indicate_handle.and
fill the given variable (connect_gesture<-to_handle
or connect_gesture<-from_handle)
with the name of the closest handle.
Else if there are any pointer handle objects anywhere on the graphical under the pointer, indicate them. Fill the given variable with @default.
free is determined by the graphical<-name
of the indicator: unused or used. Used by connect_gesture->indicate.<-line
used for feedback.
<-line
using: a) line->copy
using the line of the connect_gesture<-link.
b) graphical->texture
c)‘line connect_gesture->points with
the connect_gesture<-x and connect_gesture<-y
of the event
<-device
->indicate
the handle objects on
the receiving graphicals. @see connect_gesture-from_handle
->drag.
Next removes the connect_gesture<-line
and the indicator bitmaps from the connect_gesture<-device
and finally invokes connect_gesture->connect
using the following arguments:
constant <-receiverThe fromgraphicalconnect_gesture <-toThe tographicalconnect_gesture <-linkThe connect_gesture <-linkconnect_gesture <-from_handleHandle name at the fromsideconnect_gesture <-to_handleHandle name at the toside
<-device’or connect_gesture<-link
equals @nil.
Otherwise assigns connect_gesture<-device
to the graphical<-device
and succeed.
<-device,
computed using‘device
connect_gesture<-pointed_objects’.
May be redefined.