Back to Contents

The DragDrop class

Summary:

• Syntax
• Methods
• Usage
  • Defining the possible Drag & Drop operations
  • Getting the index of the target row where the object was dropped
  • Getting the index of the parent node where the object was dropped
  • Identifying the type of operation on drop
  • Defining the type of Drag & Drop operation
  • Defining the appearance of the target during Drag & Drop
  • Selecting the MIME type
  • Getting the selected MIME type before getting data
  • Getting Drag & Drop data from the buffer
  • Defining the MIME type of the dragged object
  • Setting the text data of the dragged object
  • Performing built-in row drop in trees

See also: Classes and Objects, Drag & Drop.

Syntax

The DragDrop class is used to control the events related to Drag & Drop.

Syntax:

ui.DragDrop

Methods:

Usage:

When implementing Drag & Drop in a dialog, the ON DRAG* / ON DROP dialog control blocks take a ui.DragDrop variable as a parameter to let you configure and control the Drag & Drop procedure. The ui.DragDrop variable must be declared in the scope of the dialog implementing Drag & Drop.

In the next example, the code defines a ui.DragDrop variable named dnd, and implements an ON DRAG_ENTER block taking dnd as the argument:

01 DEFINE dnd ui.DragDrop
02 ...
03 DISPLAY ARRAY arr TO sr.* ...
04 ...
05   ON DRAG_ENTER(dnd)
06     IF ok_to_drop THEN
07       CALL dnd.setOperation("move")
08     ELSE
09       CALL dnd.setOperation(NULL)
10     END IF
11 ...
12 END DISPLAY

Adding a possible operation

Drag & Drop actions can be of different kinds; you can do a copy of the dragged object, or move the dragged object from the source to the destination. The default Drag & Drop operation is defined by a call to setOperation() in ON DRAG_START, you can then use the addPossibleOperation() method to define additional operations that are allowed.

See setOperation() for possible values.

Getting the index of the target row where the object was dropped

The getLocationRow() method returns the index of the row in the drop target list pointed to by the mouse cursor. This method is typically used in the ON DROP block to get the index of the target row to be modified or replaced by the dragged object. The method can also be used in ON DRAG_OVER to deny the drop according to the current target row returned by getLocationRow().

Getting the index of the parent node where the object was dropped

When using a TreeView, a node can be dropped as a sibling or as a child node to another node. In order to distinguish between the cases, you must use the getLocationParent() method, which returns the index of the parent node of the drop target node returned by getLocationRow(). If both methods return the same row index, you must append the dropped row as a child of the target node. Otherwise, getLocationParent() identifies the parent node where the dropped row has to be added as a child, and getLocationRow() is the index of a sibling node. In the last case the dropped node must be inserted before the node identified by getLocationRow(). These methods are typically used in the ON DROP block, but can also be used in ON DRAG_OVER to deny the drop according to the indexes returned; for example, the program might only allow the drop of objects as new children for a given parent node.

Identifying the type of operation on drop

The getOperation() method returns the type of the current Drag & Drop operation (i.e. copy, move, none). According to the value returned by this method, the program can make the appropriate changes in the data model. For example, after a row has been dropped into another list, the source list can remove the original row if the operation was a "move", but keeps the original row if the operation was a "copy". The getOperation() method is typically called in the ON DRAG_FINISHED block.

Defining the type of Drag & Drop operation

Use the setOperation() method to define/force the type of Drag & Drop operation or to deny/cancel the Drag & Drop process.

The setOperation() method can be called in different Drag & Drop triggers. The most common usage is to deny Drag & Drop by passing NULL in the ON DRAG_ENTER and/or ON DRAG_OVER blocks because the dragged object does not correspond to the type of objects the target can receive. It is also typically used in ON DRAG_START to force a specific type of Drag & Drop operation (copy or move), or to deny drag start if the context does not allow a Drag & Drop action. When called in the ON DRAG_ENTER block, the method forces a specific Drag & Drop operation.

See also addPossibleOperation().

Defining the appearance of the target during Drag & Drop

The setFeedback() method defines the appearance the target object must have during the Drag & Drop action. For example, in a table or treeview, when the mouse is flying over rows in the drop target, a different visual indicator will appear according to the value that was passed to setFeedback().

Possible values for the setFeedback() method are:

Selecting the MIME type before getting the data

Call the selectMimeType() method to check that data is available in a format identified by the MIME type passed as parameter. If this type of data is available in the buffer, the method returns TRUE and you can later get the data with getBuffer().

The selectMimeType() method is typically used in ON DRAG_ENTER, ON DRAG_OVER to deny the Drag & Drop operation if none of the supported MIME types is available in the buffer.

Getting the previously selected MIME type

Before retrieving data from the Drag & Drop buffer with getBuffer(), you must first call the getSelectedMimeType() method to identify the data format that was previously selected by a selectMimeType() call.

The getSelectedMimeType() method is typically called in ON DROP to identity the format of the dropped object.

Getting Drag & Drop data from the buffer

Once the MIME type of the dropped object was identified with getSelectedMimeType(), you can call the getBuffer() method to get text data from the Drag & Drop buffer.

Drag & Drop data is only available at ON DROP time, thus the getBuffer() method must be called in ON DROP only.

Defining the MIME type of the dragged object

Objects dragged from a BDL application to an external application need to be identified with a MIME type and the program must provide the data. The MIME type can be specified with the setMimeType() method. 

The setMimeType() method is typically used in an ON DRAG_START block in conjunction with setBuffer().

By default the source target will use the text/plain MIME type and copy the data of the selected rows into the Drag & Drop buffer.

Setting the text data of the dragged object

In order to provide the text data of objects dragged from a BDL application to an external application, you must use the setBuffer() method. 

The setBuffer() method is typically used in an ON DRAG_START block in conjunction with setMimeType().

By default, the dialog will serialize the data of the selected rows as a tab-separated list of values (text/plain MIME type is the default).

Performing built-in row drop in trees

In order to simplify Drag & Drop programming in the same list, the ui.DragDrop class provides the dropInternal() utility method, to be called in the ON DROP block. This method will perform all the row changes in the array and move row selection as well as cell attributes.

When implementing Drag & Drop on a tree-view, dropping an element on the tree requires complex code in order to handle parent-child relationships. Nodes can be inserted under a parent between two children, appended at the end of the children list, and at different levels in the tree hierarchy. However, the dropInternal() method can also be used when the decoration is a regular table.

Note that a call to dropInternal() will silently be ignored, if the drag source is not the drop target, or if the method is called in a different context as ON DROP.

For more details about dropping elements in tree-views, see the usage of ON DROP in the Drag & Drop page.