eXept Software AG Logo

Smalltalk/X Webserver

Documentation of class 'DragAndDropManager':

Home

Documentation
www.exept.de
Everywhere
for:
[back]

Class: DragAndDropManager


Inheritance:

   Object
   |
   +--DragAndDropManager

Package:
stx:libview2
Category:
Interface-DragAndDrop
Version:
rev: 1.100 date: 2017/09/01 08:00:04
user: cg
file: DragAndDropManager.st directory: libview2
module: stx stc-classLibrary: libview2
Author:
Claus Gittinger

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.


Related information:

    DemoView1,
    DemoView2,
    ...
    SelectionInListView
    FileBrowser
    -
    for
    a
    concrete
    example

Class protocol:

Signal constants
o  dragContextQuerySignal

o  dragOffsetQuerySignal

o  dragOriginatorQuerySignal

defaults
o  autoScrollDelayTimeMs
time measured in milli-seconds the autoscroll task is delayed

helpers
o  disabledFlag: aBoolean device: aDevice

o  postDraggingOnDevice: aDevice

o  rereadSaveAreaOnDevice: aDevice

o  saveDraw: aBlock device: aDevice

initialization
o  initialize
self initialize

instance creation
o  new

queries
o  isDragAndDropActiveOnDevice: aDevice

simple start-drop source
o  startDragFrom: aView dropSource: aDropSource
start a drop at the current pointer position.

simple start-generic
o  startDrag: draggableObjects from: aView
start a drop at the current pointer position

o  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

o  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

o  startDrag: draggableObjects from: aView display: something
start a drop at the current pointer position

o  startDrag: draggableObjects from: aView offset: anOffset
start a drop at the current pointer position

o  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

o  startDrag: draggableObjects from: aView offset: anOffset 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

o  startDrag: draggableObjects from: aView offset: anOffset display: something
start a drop at the current pointer position

simple start-lines
o  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

o  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

translation
o  translatePointFromScreen: aPoint to: aView
translate a point from screen to view coordinates

o  translatePointFromScreen: aPoint toView: aView
translate a point from screen- to view coordinates

o  translatePointToScreen: aPoint from: aView
translate a point from view- to screen coordinates


Instance protocol:

accessing
o  device
returns the device of the source view

o  disabledFlag

o  disabledFlag: something

o  dragHandler
returns the current active handler which is responsible for drawing ...

o  dragHandler: aNewHandler
set the active handler which is responsible for drawing ...

o  dropContext
return the current context

o  dropObjects
return the current dropObject collection

o  dropObjects: aCollectionOfDropObjects
set the current dropObject collection

o  font
returns the font of the source view

o  giveFocusToTargetWidget: aBoolean

o  isDisabled

o  notifyEndOfDropAction: aNoneArgBlock
the action is triggered after the drop has finished

o  passiveAction: aBlockOrNil

o  removePassiveAction

o  sourceWidget

accessing-cursor
o  alienCursor: aCursorOrImage
set the cursor used for an alien widget; not an ST/X view

o  disabledCursor: aCursorOrImage
set the cursor for an ST/X view, which can not drop the objects

o  enabledCursor: aCursorOrImage
set the cursor for an ST/X view, which can drop the objects

change & update
o  contentsWillChange
called by the dropTarget-widget if the contents will change during a
dragAndDrop operation

dragging-drop source
o  startDragFrom: aView dropSource: aDropSource
start a drag at the current pointer position.

o  startDragFrom: aView dropSource: aDropSource offset: anOffset
start a drag at the current pointer position.

dragging-easy startup
o  startDrag: draggableObjects from: aView
start a drop at the current pointer position

o  startDrag: draggableObjects from: aView display: something
start a drop at the current pointer position.

o  startDrag: draggableObjects from: aView offset: anOffset
start a drop at the current pointer position with an offset

o  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

o  startDrag: draggableObjects from: aView offset: anOffset atEnd: aFourArgBlock 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.

o  startDrag: draggableObjects from: aView offset: anOffset display: something
start a drop at the current pointer position.

dragging-generic
o  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

o  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
o  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

o  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

drawing
o  displayObjectFor: anObject on: aDevice
converts an object to a display object.
CG (to CA): this is an ugly hack and must be fixed to be OO,
in sending something like #asDragAndDropDisplayObjectOn:aDevice
to anObject, and doing all specific optimizations there.

o  showDragging: items in: aView at: p
helper for dragging dragObjects: draw them all

event catching
o  buttonMotion: buttonAndModifierState x: x y: y view: aView

o  buttonRelease: button x: x y: y view: aView
restore context before start drag

o  escapePressed
handle the escape key

o  keyPress: aKey x: x y: y view: aView
stop the drag operation, when the escape key is pressed

o  keyRelease: aKey x: x y: y view: aView
redraw if shift, alt or ctrl key is released

o  processAutoScroll
process an autoScroll event

o  processEvent: event
filter keyboard events.
Return true, if I have eaten the event

o  triggerEndOfDropAction
handle the escape key

o  updateDragKind
stop the drag operation, when the escape key is pressed

initialization
o  initialize

private
o  doDrop: aContext in: aWidget
old drop mechanism

o  doFindDropTargetIn: aView at: aPoint
get the drop target for a view and source at a point or nil

o  doStart: aHandler for: aView atEnd: aFourArgEndBlock
setup a handler and a restore block

o  forceGiveUp
called if the DragAndDropManager no longer should be
active; a second one is started

o  isActive
returns true if a drag operation is active

o  saveDraw: aBlock
reread and show drag 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 ...
   |o top v|

   top := StandardSystemView new.
   v := Button label:'press for drag' in:top.
   v pressAction:[
              |o|
              o := DropObject newFile:('/etc').
              DragAndDropManager startDrag:o from:v.
              v turnOff
            ].
   top openWithExtent:200@200
initiate a drag with some offset:
   |o top v|

   top := StandardSystemView new.
   v := Button label:'press for drag' in:top.
   v pressAction:[
              |o|
              o := DropObject newFile:('.').
              DragAndDropManager startDrag:o from:v offset:10@10.
              v turnOff
            ].
   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:[
              DragAndDropManager 
                  startLineDragIn:v at:10@10 atEnd:endAction.
              v turnOff
            ].
   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:[
          DragAndDropManager startDrag:dropObj from:button offset:offset display:dispObj.
          button turnOff.
      ]
  ].

  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.1.0.0; WebServer 1.663 at exept.de:8081; Mon, 19 Nov 2018 01:42:00 GMT