drag-and-drop

Arguments: widget

Initiates a dragging operation from widget. The user may "drop" onto another control by clicking the mouse to associate the two controls together in some way.

The drag continues until the user "drops" by either pressing a mouse button (if no mouse buttons were down when drag-and-drop was called), releasing a mouse button (if a mouse button was down when drag-and-drop was called), or pressing ESCAPE to cancel the drag.

During this time, the mouse cursor changes to indicate whether a drop is allowed at the current mouse cursor location. A drop is allowed whenever the mouse cursor is over a control where droppable-p returns true when called on the dragged control and that dropped-onto control.

The default droppable-p method returns true when over any control other than the dragged control, and true when over the dragged control itself if droppable-onto-self returns true for it. The default droppable-onto-self method returns nil.

By convention, drag-and-drop should not be called for a particular control if

(draggable-p control) 

returns nil. The default draggable-p method returns true for any control.

If the user drops where a drop is allowed, then good-drop is called; if the user drops elsewhere, then bad-drop is called; if the user cancels by pressing ESCAPE, then neither function is called.

An application will typically add draggable-p methods to determine which controls may be dragged from, droppable-p methods to determine which controls may be dropped onto which, and good-drop methods to process successful drops.

drag-and-drop returns the control that was dropped onto if any, or nil otherwise. There is no dropped-onto control if the user either cancels the drag by pressing ESCAPE or drops at a location that is not over any control.

By default, the only visual indication that a drag is taking place is the changing mouse cursor. This is the standard drag-and-drop approach in Windows. But if

(drag-images (configuration *system*))

is set to true, then an attempt is made to drag an image of some part of the dragged-from control. (See configuration, *system*, and drag-images.)

This image is obtained by calling box-to-drag on the dragged-from control and copying pixels from the screen for that section of the control. box-to-drag methods are supplied for most of the controls to specify the area occupied by the currently selected value of the control. Note that this approach will not work well if the current value of the control is ever scrolled out of view. Depending on which types of controls are being dragged from, these images may or may not be considered sufficiently aesthetic for an application's interface, and so this dragging option should not be used if the result is unsatisfactory.

When the IDE is running, a general mouse-left-down method (shown below) causes drag-and-drop to be called if the ALT key is held down and a left click and drag is done on a control. A droppable-p method for the inspector allows dropping arbitrary values from arbitrary controls into inspector slots, and a droppable-p method specializing on both the main IDE toolbar and the extended IDE toolbar allows dragging commands between or within these toolbars. Other than these cases, the IDE does not make use of drag-and-drop, and the methods described in this paragraph exist in the IDE only. Applications must define their own gestures to call drag-and-drop, as well as their own droppable-p methods to define where drops are allowed.

The following code implements the IDE's mouse-left-down method for initiating drags. It checks to see if the alt-key is down (but not the control-key or shift-key) and if the mouse cursor was in the interior area of the widget that was clicked. If so, it then initiates a drag, and otherwise it calls the next method.

(defmethod mouse-left-down ((widget dialog-item)
                            buttons cursor-position)
  ;; This method exists in the IDE to allow initiating drags
  ;; by alt-clicking any widget.
  (with-boxes (box1)
    (case (logand buttons #.(logior control-key shift-key alt-key))
      (#.alt-key
       (when (and (draggable-p widget)
                  (inside-box-p cursor-position
                                (nvisible-box (window widget) box1)))
         (drag-and-drop widget)))
      (t (call-next-method)))))

Applications can add similar methods to initiate drags. Note that while a simple left click could alternately be used to initiate a drag, this should not be done for certain widgets where a mouse-left-down always waits for a mouse-left-up to complete a value selection gesture, since the mouse will not be in a meaningful position for this when the user finally releases the mouse button after dragging; this constraint appears to be limited to the single-item-list and multi-item-list widgets. See also wait-for-drag for another way to decide whether to initiate a drag.

Copyright (c) 1998-2002, Franz Inc. Oakland, CA., USA. All rights reserved.
Documentation for Allegro CL version 6.2. This page was not revised from the 6.1 page.
Created 2002.2.26.