11.8 Drag and drop interface

XPCE's drag-and-drop interface allows the user to drag-and-drop graphical objects and dict_item objects. Drag-and-drop is a common GUI technique to specify operations that require two objects in a specific order. Moving files to another directory by dragging them to the icon of the target directory is a common example.

It may also be used to specify operations on a single object, where the operation is represented by an icon. Dragging files to a trash-bin is the most commonly found example.

For the drag-and-drop interface to work, the programmer must connect a drag_and_drop_gesture to the object to be dragged.^{12Attach a drag_and_drop_dict_item_gesture to a list_browser to enable dragging the items in the dictionary}. A Drop-zone defines the method ->drop and (not strictly obligatory) ->preview_drop. ->drop is called to actually perform the associated operation, while ->preview_drop may be used to indicate what will happen if the object is dropped now.

Below is a complete example that allows the user to drag objects for moving and copying on another window.

Class drop_picture defines a graphical window that imports graphical objects when they are dropped onto it. The feedback is a dotted rectangle indicating the area of the graphical to be imported. See `graphical ->preview_drop' for a description of the arguments.

:- pce_begin_class(drop_picture, picture).

preview_drop(P, Gr:graphical*, Pos:[point]) :->
        (   Gr == @nil                  % pointer leaves area
        ->  (   get(P, attribute, drop_outline, OL)
            ->  send(OL, free),
                send(P, delete_attribute, drop_outline)
            ;   true
            )
        ;   (   get(P, attribute, drop_outline, OL)
            ->  send(OL, position, Pos)
            ;   get(Gr?area, size, size(W, H)),
                new(OL, box(W, H)),
                send(OL, texture, dotted),
                send(P, display, OL, Pos),
                send(P, attribute, drop_outline, OL)
            )
        ).

The method ->drop. If the graphical originates from the same picture just move it. Otherwise <-clone the graphical and display the clone.

drop(P, Gr:graphical, Pos:point) :->
        (   get(Gr, device, P)
        ->  send(Gr, position, Pos)
        ;   get(Gr, clone, Gr2),
            send(P, display, Gr2, Pos)
        ).

:- pce_end_class.

Class dragbox defines a simple subclass of class box that can be resized and dragged.

:- pce_begin_class(dragbox, box).

:- pce_autoload(drag_and_drop_gesture, library(dragdrop)).
:- pce_global(@dragbox_recogniser, make_dragbox_recogniser).

make_dragbox_recogniser(G) :-
        new(G, handler_group(resize_gesture(left),
                             drag_and_drop_gesture(left))).

event(B, Ev:event) :->
        (   send(B, send_super, event, Ev)
        ;   send(@dragbox_recogniser, event, Ev)
        ).

:- pce_end_class.

The toplevel predicate creates two drop_pictures in one frame (note that drag-and-drop-gestures work accross frames, but not accross multiple XPCE processes at the moment). It displays one dragbox in one of the windows. Dragging it inside a picture moves the box, dragging it to the other windows makes a copy of the box.

dragdropdemo :-
        new(F, frame('Drag and Drop Demo')),
        send(F, append, new(P1, drop_picture)),
        send(new(drop_picture), right, P1),
        send(P1, display, dragbox(100, 50), point(20,20)),
        send(F, open).

11.8.1 Related methods

drag_and_drop_gesture ->initialise: Button, Modifier, Warp, GetSource

Initialises a new drag_and_drop_gesture. Button is the name of the pointer-button the gesture should be connected to (left, middle or right). Modifier is a modifier description (see class modifier). Warp is for compatibility with older releases of this library. GetSource is a function used to fetch the object dragged from the graphical representing it. Suppose the graphical to which the gesture is attached represents a database record. In this case it is much more natural to pass the identifier for the database record to the ->drop and ->preview_drop methods than to pass the icon representing it. GetSource is a function that is evaluated with @arg1 bound to the graphical when the gesture is activated. An example could be:

drag_and_drop_gesture(left,
                      get_source :=
                             @arg1?db_record)

graphical ->drop: Object:<Type> [, Pos:point]

This method may be defined on any graphical object that is a drop-zone. It will only be activated if the drag_and_drop_gesture can locate the method and make the necessary type transformations. Thus, if the type is specified as file, this method will only be activated if the dragged object can be converted to a file object. See also the discussion about the get_source argument above.

If the method accepts a point for the second argument, a point will be passed that represents the location of the pointer in the coordinate system of the drop-zone, subtracted by the distance between the top-left corner of the dragged graphical to the pointer at the moment the button was depressed. To get the position of the pointer itself, just ask for the position of @event relative to the drop-zone.

graphical ->preview_drop: Object:<Type>* [, Pos:[point]]

Sent by the drag_and_drop_gesture to allow the drop-zone providing feedback. The arguments and semantics are the same as for ->drop, but the first argument can be @nil, indicating that the mouse has left the drop-zone. Under this condition, the position argument is @default.

If a position argument is available, the drag_and_drop_gesture will be activated on each drag event. Otherwise it is only activated if the pointer enters the area of the drop-zone.