Drag & Drop 101

Drag & Drop 101
Picking up the Dragon*
Tim Converse
dBASE Inc.
09/12/00

a primer on using drag and drop in dBASE

Introduction

dB2K introduced many new features to the dBASE developer. One of the best is Drag & Drop functionality. Drag & Drop is used in many programs currently used today and in Windows itself.

Now you can add the same functionality to your dBASE applications.

Let's take a quick look at the basics of Drag & Drop.

Drag & Drop is the ability to pick up and move objects or information in your application. To see a simple example of this open the Windows Notepad and the Windows Explorer. Find a text file in the Windows Explorer. Click and hold the left mouse button down on the text file, then move the mouse pointer to Notepad and let up on the mouse button. If you did everything correctly Notepad will open up the text file you dragged into it.

Example 1

Now let's create a simple dBL example.

Open up dBASE.
Create a new, blank form.
Place a Container on the form.
Place an EntryField on the form.
Inspect the Container and look for a property called allowDrop.
This is a True/False property. Set it to True.
Inspect the EntryField and look for a property called dragEffect.
This property has 3 possible settings; None, Copy, and Move. Set it to Move.
Go to the Events tab of the Inspector and modify the onLeftMouseDown event of the EntryField with the following line of code:

this.drag(this.name,"O","")

Save and run the form.
Click and hold the left mouse button down on the EntryField. Note that the mouse icon changes appearance.
Move the mouse over to the container and let up on the mouse button.

If you've done everything right, the EntryField should now be on top of the container. If it isn't, put the form in design mode, highlight the container and use the LAYOUT | SEND TO BACK menu choice, then rerun the form.

Explanation of Example 1

So, let's look at our simple example.

On the Container, we set it's allowDrop property to True. This tells the container that if an object is dragged to it, do the following things:

Change the mouse icon to reflect that this is a possible Drop Target.

Fire the appropriate events related to the drag operation:

onDragEnter

onDragLeave

onDragOver

If the object is dropped on the container, fire the appropriate event:

onDrop

(Note: This is true only on when the dragEffect of the object is set to 2-Copy. 1-Move will not fire the onDrop event.)

On the EntryField, we set the dragEffect property to 2-Move. This tells the EntryField that if a drag operation is initiated, do the following things:

Change the mouse icon to reflect that a drag operation has begun.

Allow the EntryField to be moved.

But what is this drag operation that is being referred to?

That's the line of code in the onLeftMouseDown event of the EntryField.

this.drag(this.name,"O","")

drag is the method which initiates all Drag & Drop events. Once a drag operation begins, all other mouse events are superseded. The three parameters passed in this case are the name of the object which has called the drag method, the letter "O" and nothing.

These parameters are referred to as:

cName - A character string which usually contains the data you want to pass in the drag operation.
cType - A character string which usually the type of the object which initiated the drag operation.
cIcon - Currently an unimplemented part of the drag operation. When implemented it will refer to an icon which will be used during the drag operation.

In this case, the cName parameter is the name of the object itself.

The cType parameter of "O" is a bit more mysterious. Although the parameter can be any string you choose up to 260 characters long, there are a couple of strings which have some meaning to dBASE internally.

O - simply means object and is a sort of default value for this parameter.
F - This means File. It is possible to drag outside objects into dBASE applications. When that happens, the cType parameter defaults to "F".

Finally, the empty parameter at the end is simply the unimplemented icon parameter. Although it currently is not used, the call to the drag method does require that it be included.

Definitions

There are two basic catagories of Drag & Drop objects. Drop Sources and Drop Targets. Some objects are both a Drop Source and a Drop Target.

Drop Sources are objects that initiate a Drag & Drop operation. These are the objects which can be 'dragged'.

Drop Targets are objects which accept a Drag & Drop operation. These are the objects which can have other objects 'dropped on them'.

Objects which can be Drop Sources all have:

dragEffect property

drag method

onDragBegin event

Objects which can be Drop Targets all have:

allowDrop property

onDragEnter event

onDragLeave event

onDragOver event

onDrop event

allowDrop

Defaults to False. When set to False, objects which are being dragged will not be allowed to drop on them. The drag Icon will not show any change indicating that this is a possible place to drop an object.
When set to True, the mouse icon will change indicating that it is possible to drop on this object.

dragEffect

Defaults to 0-None. It can be set to 1-Copy or 2-Move.

0-None - No dragEffect will be initiated with the object in question.

1-Copy - A dragEffect will be initiated, but the object will remain stationary on the form. In this case you are 'copying' data from one object to another.

2-Move - A dragEffect will be initiated and the object will be moved. In this case you are 'moving' the actual object on the form. onDrop is not fired when the object is released.

onDragBegin

This event is fired when a drag event has been initiated.

onDragEnter

This event is fired when the mouse pointer enters a possible drop target during a drag event.

onDragLeave

This event is fired when the mouse pointer leaves a possible drop target during a drag event.

onDragOver

This event is fired when the mouse pointer is over a possible drop target during a drag event.

onDrop

This event is fired when a drag event is ended on a possible drop target.

drag

This method is the heart of Drag & Drop. It is called to begin a Drag & Drop operation. It takes the following three parameters:

cName - a String of up to 260 characters long.

cType - a String of up to 260 characters long.

cIcon - Not currently implemented. It will be a string used to locate an icon to be used during the drag event.

The drag event is usually initiated inside the onLeftMouseDown event of a Drop Source, though it can be initiated anywhere you choose.
The parameters are not enforced in dBASE. They can contain any information you need to accomplish the operation you are attempting.

Example 2

Now let's try another example.

In this example we will use Drag & Drop to move items from one Listbox to another.

Create a new form.

Put two listboxes on the form.

Modify the first Listbox as follows:

Set it's dragEffect property to 1-Copy

In it's onLeftMouseDown event put the following code:

this.drag(this.name,this.value,"")

Inspect the Listbox and click on the 'wrench' button of it's dataSource property.

In the dialog click on the 'wrench' button.

Add the following items to the Array Elements list:

Red

Green

Blue

Yellow

White

Click 'OK' and then 'OK' again.

Modify the second Listbox as follows:

Set it's allowDrop property to TRUE

In it's onOpen event put the following code:

this.sourcearray = new array()
this.dataSource := "array this.sourcearray"

In the second Listbox's onDrop event put the following code:

this.sourcearray.add(cName)
this.dataSource := "array this.sourcearray"

Save and run the form.

Click and hold on any item in the first Listbox.

The Mouse Pointer should change, showing that a drag operation is in effect.

Move the mouse over the second Listbox and let up on the mouse button.

The item you selected from the first Listbox is copied into the second.

What did we do here?

In the onOpen of the second Listbox we created a new property of the Listbox called sourcearray and then set it's datasource to that array.

In the onLeftMouseDown event of the first Listbox we initiated a drag operation, passing the parameters of the name and current value of the first Listbox.

In the onDrop of the second Listbox we took the value being carried in the drag operation and added it to the sourcearray property of the second Listbox and then refreshed the datasource of the second Listbox with that sourcearray.

List of Drag & Drop Objects

So what objects have Drag & Drop capabilities?

The following objects all can be used as Drop Sources:

ActiveX, Browse, CheckBox, ComboBox, Editor, EntryField, Grid,
HScrollBar, VScrollBar, Image, NoteBook, Ole, PaintBox, Progress,
PushButton, RadioButton, ReportViewer, Slider, SpinBox, TabBox,
Text, TextLabel, TreeView.

The following objects all can be used as Drop Targets:

Container, Browse, Listbox, Image, Grid, Notebook, Paintbox,
ReportViewer, TreeView.

Summary

What can you do with Drag & Drop? Just about anything you want really. You will find that it's very flexible and will allow you to do many things. For a really superior example of just how much you can do with Drag & Drop, look at dQuery.

dQuery takes full advantage of the possibilities of Drag & Drop capability and may inspire you to create your own Drag & Drop capable applications.

Information about dBASE, Inc. can be found at:
http://www.dbase.com

* The hard part isn't the drop. It's picking up the dragon in the first place.