Drag and Drop

version 2004.2 (Modified)

4th Dimension allows built-in drag and drop capability between objects in your forms. You can drag and drop one object to another, in the same window or in another window. In other words, drag and drop can be performed within a process or from one process to another.

4th Dimension does not include built-in drag and drop to and from the desktop or another application. However, this functionality is provided using plug-ins developed by 4D Partners or using the "system" drag and drop (for more information about this, refer to the end of this section).

Note: As an introduction, we assume that a drag and drop action "transports" some data from one point to another. Later, we will see that drag and drop can also be a metaphor for any type of operation.

To drag and drop an object to another object, you must select the Draggable property for that object in the Property List window. In a drag-and-drop operation, the object that you drag is the source object.

To make an object the destination of a drag and drop operation, you must select the Droppable property for that object in the Property List window. In a drag-and-drop operation, the object that receives data is the destination object.

By default, newly created objects can be neither dragged nor dropped. It is up to you to set these properties.

All objects in an input or dialog form can be made to be dragged and dropped. Individual elements of an array (i.e., scrollable area), items of a hierarchical list or rows in a list box can be dragged and dropped. Conversely, you can drag and drop an object onto an individual element of an array or an item of a hierarchical list or a list box row. However, you cannot drag and drop objects from the detail area of an output form.

You can easily create a drag-and-drop user interface, because 4D allows you to use any type of active object (field or variable) as source or destination objects. For example, you can drag and drop a button.

Notes:

•To drag a button labeled "draggable," you must first press the Alt (Windows) or Option (Mac OS) keys.

• When the "Draggable" and "Movable Rows" properties are both set for a List box object, the "Movable Rows" property takes priority when a row is moved. Dragging is not possible in this case.

An object that is capable of being both dragged and dropped can also be dropped onto itself, unless you reject the operation. For details, see the discussion below.

The following figure shows the Property List window with the Droppable and Draggable properties set for the selected object:

4th Dimension ensures the user interface part of the drag-and-drop capability. If you click on a draggable object and then drag the mouse, 4D drags the object; it reflects this operation on the screen with a dotted rectangle that follows the movements of the mouse. In the following figure, a hierarchical list item is being dragged over a text field:

Note the reverse gray frame highlight around the text field area. This highlight indicates the destination object (in this case, the text field). If you release the mouse button at this point, 4D assumes that you want to drop the dragged object onto the highlighted destination object.

In the Preferences dialog box, you can set the drag and drop highlight of the destination object to be a frame or a pattern (or both):

The default highlight is Frame. It is a rectangular, gray, reverse highlight around the object. If you use colored background or object frames, using this highlight may be confusing. You can alternatively use the Pattern highlight, which fills the destination object with a diagonal lines pattern, as shown.

Here a hierarchical list item is dragged over a text field:

Here a list item is dragged inside the same list:

You can also choose both types of highlight.

Note: The highlight of the destination object "follows" elements or items when the destination object is an array (scrollable area), a list box or a hierarchical list.

4th Dimension performs the user interface part of a drag and drop—it is up to you to perform the programmatical part. To enable you to do so, 4D provides you with two form events: On Drag Over and On Drop. Both events are sent to the destination object. During a drag-and-drop operation, the object method of the source object is never involved.

In order to accept On Drag Over and On Drop, the destination object must have these two events activated in their properties, as shown here:

• Property List:

The On Drag Over event is repeatedly sent to the destination object when the mouse pointer is moved over the object. In response to this event, you usually:

• Call the DRAG AND DROP PROPERTIES command, which informs you about the source object.

• Depending on the nature and type of both the destination object (whose object method is currently being executed) and the source object, you accept or reject the drag and drop.

To accept the drag, the destination object method must return 0 (zero), so you write $0:=0. To reject the drag, the object method must return -1 (minus one), so you write $0:=-1. In this case, the object is not activated graphically. During an On Drag Over event, 4D treats the object method as a function. If no result is returned, 4D assumes that the drag is accepted.

If you accept the drag, the destination object is highlighted. If you reject the drag, the destination is not highlighted. Accepting the drag does not mean that the dragged data is going to be inserted into the destination object. It only means that if the mouse button was released at this point, the destination object would accept the dragged data.

If you do not process the On Drag Over event for a droppable object, that object will be highlighted for all drag over operations, no matter what the nature and type of the dragged data.

The On Drag Over event is the means by which you control the first phase of a drag-and-drop operation. Not only can you test whether the dragged data is of a type compatible with the destination object, and then accept or reject the drag; you can simultaneously notify the user of this fact, because 4D highlights (or not) the destination object, based on your decision.

The code handling an On Drag Over event should be short and execute quickly, because that event is sent repeatedly to the current destination object, due to the movements of the mouse.

WARNING: If the drag and drop is an interprocess drag and drop, which means the source object is located in a process (window) other than that of the destination object, the object method of the destination object for an On Drag Over event is executed within the context of the source process (the source object's process), and not in the process of the destination object. This is the only case in which such an execution occurs. The advantages of this type of execution are described at the end of this section.

The On Drop event is sent once to the destination object when the mouse pointer is released over the object. This event is the second phase of the drag-and-drop operation, in which you perform an operation in response to the user action.

This event is not sent to the object if the drag was not accepted during the On Drag Over events. If you process the On Drag Over event for an object and reject a drag, the On Drop event does not occur. Thus, if during the On Drag Over event you have tested the data type compatibility between the source and destination objects and have accepted a possible drop, you do not need to re-test the data during the On Drop. You already know that the data is suitable for the destination object.

An interesting aspect of the 4D drag-and-drop implementation is that 4D lets you do whatever you want. Examples:

• If a hierarchical list item is dropped over a text field, you can insert the text of the list item at the beginning, at the end, or in the middle of the text field.

• Your form contains a two-state picture button, which could represent an empty or full trash can. Dropping an object onto that button could mean (from the user interface standpoint) "delete the object that has been dragged and dropped into the trash can." Here, the drag and drop does not transport data from one point to another; instead, it performs an action.

• Dragging an array element from a floating window to an object in a form could mean "in this window, show the Customer record whose name you just dragged and dropped from the floating window listing the Customers stored in the database."

• And so on.

So, the 4D drag-and-drop interface is a framework which enables you to implement any user interface metaphor you may devise.

The DRAG AND DROP PROPERTIES command returns:

• A pointer to the dragged object (field or variable)

• The element or item number, if the dragged object is an array element or a list item

• The process number of the source process.

The Drop position command returns the element number of the item position of the target element or list item, if the destination object is an array (i.e., scrollable area) or a hierarchical list, as well as the column number if the object is a list box.

Commands like RESOLVE POINTER and Type are useful for testing the nature and type of the source object.

When the drag-and-drop operation is intended to copy the dragged data, the functionality of these commands depend on how many processes are involved:

• If the drag and drop is limited to one process, use these commands to perform the appropriate actions (i.e., simply assigning the source object to the destination object).

• If the drag and drop is an interprocess drag and drop, you need to be careful while getting access to the dragged data; you must access the data instance from the source process. If the dragged data comes from a variable, use GET PROCESS VARIABLE to get the right value. If the dragged data comes from a field, remember that the current record for a table is probably different for the two processes, so you need to access the right record.

In this last case, several solutions are available:

• If the On Drag Over event for the destination object method is executed in the context of the source process, you can copy the field data or the record number to an interprocess variable that will be reused during the On Drop event.

• You can get the required data by starting an interprocess communication during the On Drop event.

If the drag and drop is not intended to move data, but is instead a user interface metaphor for a particular operation, you can perform whatever you want.

Text areas in native control (fields, variables and List boxes) allow the "system" drag and drop, which is the movement or copy of a text selection from one area to another. It can be used in the same 4D area, between two 4D areas, or between 4D and another application, for example WordPad. This only works between two text areas that are both in native control.

When system drag and drop is used, the 4th Dimension drag-and-drop management mechanisms described above are NOT used.

Consequently, the On Drag Over and On Drop form events are NOT generated and the drop area is not activated as defined in the Preferences.

If you wish to "force" the use of the internal 4th Dimension drag and drop with areas in native control, hold down the Alt (Windows) or Option (Mac OS) key before performing the drag and drop.

DRAG AND DROP PROPERTIES, Drop position, Form event, GET PROCESS VARIABLE, Is a list, RESOLVE POINTER, Type.