Smalltalk/X Webserver

Documentation of class 'DragAndDropManager':

Class: DragAndDropManager

Inheritance
Description
Class protocol
Instance protocol
Examples

Inheritance:

   Object
   |
   +--DragAndDropManager

Package:: stx:libview2

Category:: Interface-DragAndDrop

Version:: rev: 1.141 date: 2023/11/22 08:46:44; user: stefan; file: DragAndDropManager.st directory: libview2; module: stx stc-classLibrary: libview2

Description:

this class provides low-level drag & drop mechanisms.

Easy to use interface interfaces:

A drag is usually initiated by a view or its application model,
when a selection is moved (for example, SelectionInListView can
be initializd to do so). 
There, the view creates a collection of dropObjects from its selection,
and starts the drag operation with:

    DragAndDropManager startDrag:collectionOfDragObjects from:aView.

This easy to use interface starts a drag and also drops the collection
into the target view.
While dragging, a thumbsUp cursor is shown, if the view-under-the-drag
can handle a drop, a thumbsDown is shown if not, and a question mark
is shown for alien views (which means: we don't know).
Alien view drop is supported (but no 'canDrop' query).

For rubber-band line dragging, two more easy-to-use startup methods are
provided:

    DragAndDropManager
            startLineDragIn:aView at:position
            atEnd:aFourArgEndBlock

and:
    DragAndDropManager
            startArrowDragIn:aView at:position
            atEnd:aFourArgEndBlock

both of the above expect a 4-arg block to be passed, which will be
evaluated at end-drag, with the target view, its viewID, the drop position
on the screen and within the target view as arguments.


Expert interface:

More control over the dragging (i.e. the drawing procedure)
can be optained, by passing a dragBlock and an endDrag action:
    
    aDragAndDropMgr := DragAndDropManager new.
    aDragAndDropMgr dropObjects:(self collectionOfDragObjects).
    aDragAndDropMgr 
        startOpaqueDrag:[:aPoint :aView :dropObjects | 
                            self 
                                showDragging:dropObjects
                                in:aView 
                                at:aPoint - (xOffset@0)
                        ]
        offset:clickOffset
        extent:saveUnderExtent
        in:self
        at:clickPoint
        atEnd:[:v :vId :posScreen :posView | ... ]

the arguments are:
  startOpaqueDrag:
    a 3-arg block, which is evaluated by the d&d manager whenever the
    mouse moves; it is supposed to draw the dropObjects at some position
    in the passed view.

  offset:
    a clickOffset; drawing is offset by this amount

  extent:  
    a save extent; the size of the screen area that must be saved during
    the drag operation

  in:
    initiating view

  at:
    position where d&d operation starts

  atEnd:
    a 4-arg block that is evaluated when the d&d is finished.
    It gets the target view (or nil, for alien views), the targets
    view ID (needed if it's an alien view), the screen position and the
    relative position within the target view of the drop as arguments.

    For internal (ST/X) views, the dropBlock should perform
    a simple canDrop:/doDrop message.

    For alien views, the Display's d&d functions can be used.

copyrightCOPYRIGHT (c) 1996 by eXept Software AG / Claus Gittinger
             All Rights Reserved

This software is furnished under a license and may be used
only in accordance with the terms of that license and with the
inclusion of the above copyright notice.   This software may not
be provided or otherwise made available to, or used by, any
other person.  No title to or ownership of the software is
hereby transferred.

Class protocol:

Signal constants

dragContextQuerySignal
dragOffsetQuerySignal
dragOriginatorQuerySignal

defaults

autoScrollDelayTimeMs: time between autoscrolls in milli-seconds

** This is an obsolete interface - do not use it (it may vanish in future versions) **
autoScrollTimeInterval: time between autoscrolls in milli-seconds
autoScrollTimeInterval: millisOrNil: time between autoscrolls in milli-seconds

helpers

disabledFlag: aBoolean device: aDevice
postDraggingOnDevice: aDevice: cg: who uses this?
rereadSaveAreaOnDevice: aDevice
saveDraw: aBlock device: aDevice: cg: who uses this?

initialization

initialize: self initialize

instance creation

new: (comment from inherited method)
return an instance of myself without indexed variables

queries

isDragAndDropActiveOnDevice: aDevice

simple start-drop source

startDragFrom: aView dropSource: aDropSource: start a drop at the current pointer position.
The drag-object's topLeft is drawn at the mouse pointer;
returns the new dragAndDropManager
startDragFrom: aView dropSource: aDropSource offset: offsetOrSymbol: start a drop at the current pointer position.
anOffsetOrSymbol describes which point of the drag-object is drawn at the mouse pointer;
It can be a point or one of:
#center,
#topLeft, #topRight
#bottomLeft, #bottomRight
#rightCenter, #leftCenter, #topCenter, #bottomCenter;
returns the new dragAndDropManager

simple start-generic

startDrag: draggableObjects from: aView: start a drop at the current pointer position;
returns the new dragAndDropManager instance
startDrag: draggableObjects from: aView atEnd: aFourArgEndBlock: start a drop at the current pointer position
When finished, the endAction is called with four args:
the targetView, the targetViews windowID (useful, if it's an alien view),
the dropPoint in root-coordinates and the dropPoint within the targetView;
returns the new dragAndDropManager instance
startDrag: draggableObjects from: aView atEnd: aFourArgEndBlock display: something: start a drop at the current pointer position
When finished, the endAction is called with four args:
the targetView, the targetViews windowID (useful, if it's an alien view),
the dropPoint in root-coordinates and the dropPoint within the targetView;
returns the new dragAndDropManager instance
startDrag: draggableObjects from: aView display: something: start a drop at the current pointer position;
returns the new dragAndDropManager instance
startDrag: draggableObjects from: aView offset: anOffset: start a drop at the current pointer position;
returns the new dragAndDropManager instance
startDrag: draggableObjects from: aView offset: anOffset atEnd: aFourArgEndBlock: start a drop at the current pointer position
When finished, the endAction is called with four args:
the targetView, the targetViews windowID (useful, if it's an alien view),
the dropPoint in root-coordinates and the dropPoint within the targetView;
returns the new dragAndDropManager instance
startDrag: draggableObjects from: aView offset: anOffsetOrSymbol atEnd: aFourArgEndBlock display: something: start a drop at the current pointer position
When finished, the endAction is called with four args:
the targetView, the targetViews windowID (useful, if it's an alien view),
the dropPoint in root-coordinates and the dropPoint within the targetView;
returns the new dragAndDropManager instance
startDrag: draggableObjects from: aView offset: anOffset display: something: start a drop at the current pointer position;
returns the new dragAndDropManager instance

simple start-lines

startArrowDragIn: aView at: dragPoint atEnd: aFourArgBlock: start a rubber-arrow-line dragging in aView at dragPoint.
When finished, evaluate the fourArgBlock with targetView,
targetID, screenPosition and targetViewPosition as arguments
startLineDragIn: aView at: dragPoint atEnd: aFourArgBlock: start a rubber-line dragging in aView at dragPoint.
When finished, evaluate the fourArgBlock with targetView,
targetID, screenPosition and targetViewPosition as arguments
startRectangleDragIn: aView at: dragPoint atEnd: aFourArgBlock: start a rubber-rectangle dragging in aView at dragPoint.
When finished, evaluate the fourArgBlock with targetView,
targetID, screenRectangle and targetViewRectangle as arguments

translation

translatePointFromScreen: aPoint to: aView: translate a point from screen to view coordinates
translatePointFromScreen: aPoint toView: aView: translate a point from screen- to view coordinates
translatePointToScreen: aPoint from: aView: translate a point from LOGICAL view coordinates to (DEVICE) screen coordinates

Instance protocol:

accessing

device: returns the device of the source view
disabledFlag
disabledFlag: something
dragHandler: returns the current active handler which is responsible for drawing ...
dragHandler: aNewHandler: set the active handler which is responsible for drawing ...
dropContext: return the current context
dropObjects: return the current dropObject collection
dropObjects: aCollectionOfDropObjects: set the current dropObject collection
font: returns the font of the source view
giveFocusToTargetWidget: aBoolean
isDisabled
notifyEndOfDropAction: aNoneArgBlock: the action is triggered after the drop has finished
passiveAction: aBlockOrNil
removePassiveAction
sourceWidget

accessing-cursor

alienCursor: aCursorOrImage: set the cursor used for an alien widget; not an ST/X view
disabledCursor: aCursorOrImage: set the cursor for an ST/X view, which can not drop the objects
enabledCursor: aCursorOrImage: set the cursor for an ST/X view, which can drop the objects

autoscroll

processAutoScroll: process an autoScroll event.
(no direct senders; sent indirectly via pushUserEvent:#processAutoScroll)
startAutoScrollTaskForSensor: sensor: Transcript showCR: e'{Time now} a'.
stopAutoScroll

change & update

contentsWillChange: called by the dropTarget-widget if the contents will change during a
dragAndDrop operation.
This must be called before the widget performs
any changes to the view while being dragged over (eg. autoscroll),
to force the d&d operation to restore the view before
(from the bitmap image which it fetched before the opaque move)

dragging-drop source

startDragFrom: aView dropSource: aDropSource: start a drag at the current pointer position.
The drag-object's topLeft is drawn at the mouse pointer
startDragFrom: aView dropSource: aDropSource offset: anOffsetOrSymbol: start a drag at the current pointer position.
anOffsetOrSymbol describes which point of the drag-object is drawn at the mouse pointer;
It can be a point or one of:
#center,
#topLeft, #topRight
#bottomLeft, #bottomRight
#rightCenter, #leftCenter, #topCenter, #bottomCenter;
returns the receiver

dragging-easy startup

startDrag: draggableObjects from: aView: start a drag at the current pointer position;
returns the receiver
startDrag: draggableObjects from: aView display: something: start a drag at the current pointer position;
returns the receiver
startDrag: draggableObjects from: aView offset: anOffset: start a drag at the current pointer position with an offset;
returns the receiver
startDrag: draggableObjects from: aView offset: anOffset atEnd: aFourArgEndBlock: start a drag at the current pointer position.
When finished, the endAction is called with four args:
the targetView, the targetViews windowID (useful, if it's an alien view),
the dropPoint in root-coordinates and the dropPoint within the targetView;
returns the receiver
startDrag: draggableObjects from: aView offset: anOffsetOrSymbol atEnd: aFourArgBlock display: somethingToDisplay: start a drag&drop at the current pointer position.
When finished, the endAction is called with four args:
the targetView, the targetViews windowID (useful, if it's an alien view),
the dropPoint in root-coordinates and the dropPoint within the targetView.
startDrag: draggableObjects from: aView offset: anOffset display: something: start a drag at the current pointer position;
returns the receiver

dragging-generic

startGenericDrag: aTwoArgDragBlock in: aView at: p atEnd: aFourArgEndBlock: start a generic (caller-provided drag);
Here, an inverting drag is initiated (i.e. the drawing is undone
by inverting again). See startOpaqueDrag for another variant.
the dragBlock, aTwoArgDragBlock will be called with two args
aPoint and a drawingGC, to perform the drawing at some dragPoint.
The drag starts in aView at point p.
When finished, the endAction is called with four args:
the targetView, the targetViews windowID (useful, if it's an alien view),
the dropPoint in root-coordinates and the dropPoint within the targetView
startOpaqueDrag: aDragBlock offset: offs extent: anExtent in: aView at: aDummyPoint atEnd: aFourArgEndBlock: start an opaque or generic opaque (caller-provided drag);
opaque drag means, that the drawing cannot be undone by two inverting
draws, but instead, the area under the dragged object must be saved
and restored. The areas size to be saved/restored is passed in anExtent.
the dragBlock, aDragBlock will be called with up to three args aPoint, a
drawingGC and the display objects, to perform the drawing at some dragPoint.
The drag starts in aView at point p.
When finished, the endAction is called with four args:
the targetView, the targetViews windowID (useful, if it's an alien view),
the dropPoint in root-coordinates and the dropPoint within the targetView

dragging-lines

startArrowDragIn: aView at: aStartPoint atEnd: aFourArgEndBlock: start a line-drag of an arrow-line.
The drag starts in aView at point aStartPoint.
When finished, the endAction is called with four args:
the targetView, the targetViews windowID (useful, if it's an alien view),
the dropPoint in root-coordinates and the dropPoint within the targetView
startLineDragIn: aView at: aStartPoint atEnd: aFourArgEndBlock: start a line-drag of a normal line.
The drag starts in aView at point aStartPoint.
When finished, the endAction is called with four args:
the targetView, the targetViews windowID (useful, if it's an alien view),
the dropPoint in root-coordinates and the dropPoint within the targetView
startRectangleDragIn: aView at: aStartPoint atEnd: aFourArgEndBlock: start a rectangle-drag of a normal line.
The drag starts in aView at point aStartPoint.
When finished, the endAction is called with four args:
the targetView, the targetViews windowID (useful, if it's an alien view),
the dropRectangle in root-coordinates and the rectangle within the targetView

drawing

displayObjectFor: anObject on: aDevice: converts an object to a display object.
showDragging: items in: aView at: p: helper for dragging dragObjects: draw them all

event catching

buttonMotion: buttonAndModifierState x: x y: y view: aView: how can this happen - I did not get a buttonRelease!
buttonRelease: button x: x y: y view: aView: Logger trace:'buttonRelease'.
escapePressed: handle the escape key
keyPress: aKey x: x y: y view: aView: stop the drag operation, when the escape key is pressed
keyRelease: aKey x: x y: y view: aView: redraw if shift, alt or ctrl key is released
processEvent: event: filter keyboard events.
Return true, if I have eaten the event
triggerEndOfDropAction: handle the escape key
updateDragKind: change the kind of drag operation, when CTRL, META/ALT or SHIFT are pressed
(change from default to dragTypeCopy, dragTypeLink or dragTypeMove)

initialization

initialize: (comment from inherited method)
just to ignore initialize to objects which do not need it

private

doDrop: aContext in: aWidget: old drop mechanism
doFindDropTargetIn: aView at: aPoint: get the drop target for a view and source at a point or nil
doStart: aHandler for: aView atEnd: aFourArgEndBlock: setup a handler and a restore block
forceGiveUp: called if the DragAndDropManager no longer should be
active; a second one is started
isActive: returns true if a drag operation is active
saveDraw: aBlock: evaluate aBlock with the drag temporarily being undrawn
(i.e. restore original picture, evaluate the block, and draw dragged objects again).
Returns the block's value.
Use this, to change the contents while being dragged over,
especially for autoscroll and/or autoexpand/collapse of tree items.

Examples:

a button, which initiates dragging of a file-object Notice that this can be dropped into the launchers panel, to open a fileBrowser on that directory ... initiate a drag with some offset:

   |o top v|

   top := StandardSystemView new.
   v := Button label:'press for drag' in:top.
   v pressAction:[
              |o|
              v turnOff.
              v windowGroup processExposeEvents.
              o := DropObject newFile:('.').
              DragAndDropManager startDrag:o from:v offset:10@10.
            ].
   top openWithExtent:200@200

initiate a line drag:

   |o top v endAction|

   endAction := [ :v :vID :sPos :vPos |
                  Transcript show:'end drag in '.
                  v isNil ifTrue:[
                      Transcript show:'alien view'
                  ] ifFalse:[
                      Transcript show:v
                  ].
                  Transcript show:' at screen: '; show:sPos;
                             show:' in view: '; showCR:vPos
              ].
   top := StandardSystemView new.
   v := Button label:'press for drag' in:top.
   v pressAction:[
              v turnOff.
              v windowGroup processExposeEvents.
              DragAndDropManager 
                  startLineDragIn:v at:10@10 atEnd:endAction.
            ].
   top openWithExtent:200@200

more drag & drop; offset, displayObjects, ...

  |dropObj topView pannel icon buttonAction addButton|

  topView := StandardSystemView new.
  pannel  := VerticalPanelView origin:(0.0 @ 0.0) corner:(1.0 @ 1.0) in:topView.
  pannel  horizontalLayout:#fit.
  pannel  verticalLayout:#fitSpace.

  icon    := Image fromFile:('xpmBitmaps/QUESTION3.xpm').
  dropObj := DropObject newFile:('.').

  addButton := [:offset :label :dispObj| |button|
      button := Button label:label in:pannel.

      button pressAction:[
          button turnOff.
          button windowGroup processExposeEvents.
          DragAndDropManager startDrag:dropObj from:button offset:offset display:dispObj.
      ]
  ].

  addButton value:(0@-5)       value:'String'       value:'String'.
  addButton value:#topLeft     value:'String'       value:'String'.
  addButton value:#topRight    value:'Text'         value:(Text string:'hello' emphasis:#bold).
  addButton value:#bottomLeft  value:'Icon'         value:icon.
  addButton value:#bottomRight value:'LabelAndIcon' value:(LabelAndIcon icon:icon string:'Label & Icon').
  addButton value:#center      value:'Mixed'        value:(Array with:'String' with:icon).

  topView label:'Drag & Drop'.
  topView openWithExtent:200@200.

ST/X 7.7.0.0; WebServer 1.702 at 20f6060372b9.unknown:8081; Sat, 27 Jul 2024 07:52:44 GMT