Revision as of 19:20, 21 September 2007

API

DropEffect = { iup.DROP_NONE, iup.DROP_COPY, iup.DROP_MOVE, iup.DROP_SCROLL } (iup.DROP_SCROLL is unimplemented)

QueryContinueEffect = { iup.DRAG_OK, iup.DRAG_DROP, iup.DRAG_CANCEL }

iup.DoDragDrop(dataobject, datasource, effectsallowed) returns true if datasource supports drag and drop

 Called by user to initiate drag drop process.
 User should create a dataobject and tag it approriately so targets can find out if they can accept it.
 Typical dataobjects look like this: {type="invitem", itemid=itemid, ...}
 Datasource is the source control that implements the source callbacks listed below.
 effectsallowed is sent to dragenter_cb/dragover_cb/drop_cb callbacks. This should be tested in target to see if target supports what is requested.

iup.CancelDragDrop()

 Called by user to cancel the drag drop process, usually due to the source window closing or the dataobject being removed.

User-created functions

Target:dragenter_cb(dataobject, x, y, keystate, effect) returns DropEffect (returning nothing is equivalent to returning iup.DROP_NONE)

   If this function doesn't exist or returns nothing, it is equivalent to returning iup.DROP_NONE.
 Created by user to determine if target supports dataobject and returns appropriate value.
 This function can be used to display feedback in target control.
 The user can store a reference to the dataobject to be used in dragover_cb, but will need to clean up the reference in dragleave_cb.
 Return value is sent to Source:givefeedback_cb()

Target:dragleave_cb() no return value

 Created by user to clean up feedback and remove any references to the dataobject.

Target:dragover_cb(x, y, keystate, effect) returns DropEffect (returning nothing is equivalent to returning iup.DROP_NONE)

   If this function doesn't exist or returns nothing, it is equivalent to returning iup.DROP_NONE.
 Created by user to update feedback in the target control.
 This function is called often, so it should do as little as possible.
 Return value is sent to Source:givefeedback_cb()

Target:drop_cb(dataobject, x, y, keystate, effect) returns DropEffect (returning nothing is equivalent to returning iup.DROP_NONE)

   If this function doesn't exist or returns nothing, it is equivalent to returning iup.DROP_NONE.
 Created by user to insert dataobject's info into Target or to perform the move or copy operation.
 This function is called when querycontinuedrag_cb returns iup.DRAG_DROP.
 This function should clean up feedback and remove any references to the dataobject, similar to dragleave_cb().
 Return value is sent to Source:dragresult_cb()

Source:givefeedback_cb(effect) returns 1/0 whether cursor was updated (returning nothing is equivalent to returning 0)

   If this function doesn't exist or returns nothing, it is equivalent to returning 0.
 Created by user to update feedback in source control and to optionally update cursor.
 If this function updates the cursor, then return 1, else return 0 or nothing.

Source:querycontinuedrag_cb(escapekeystate, keystate) returns QueryContinueEffect

   If this function doesn't exist or returns nothing, it is equivalent to returning iup.DRAG_OK.
 Created by user to determine if drag drop should continue.
 This function is called when a mouse button state changes.
 iup.DRAG_OK means to continue normally.
 iup.DRAG_DROP means to drop the item on the target.
 iup.DRAG_CANCEL means to cancel the drag.

Source:dragresult_cb(effect)

 Created by user to determine when drag drop is completed.
 This function is called when querycontinuedrag_cb returns iup.DRAG_DROP or iup.DRAG_CANCEL or iup.CancelDragDrop() is called.
 This function should update Source feedback. The cursor is automatically returned to a normal arrow.

Source:begindrag_cb([index]) no return value

 Created by user to determine when a drag begins. Call iup.DoDragDrop(...) at this time.
 The index argument only exists when the control is a list or tree control.
 Only list, tree, matrix, and button controls support this callback at this time. More will be added in the future.