Dragon Droppings

Clarion for Windows Tips
May 1997

I was talking to a co-worker one day and noticed a box of "Dragon Droppings" candy on his shelf. WordPerfect Corporation produced the candy to promote drag-and-drop support in WordPerfect for Windows. This tip looks at what is required to provide the same support in Clarion for Windows applications.

Considerations for Drag-and-Drop

Drag-and-drop is a user interface component that can provide an intuitive method for users to interact with your program. In order for drag-and-drop to be effective in a user interface, there are two rules that must be followed:

The drag-and-drop action should use a real-world metaphor. This means that the objects involved in drag-and-drop should be real objects where possible: some paper, a pencil, a trash can, a desk, an envelope, or a similar object.
The drag-and-drop action should be intuitive. If the user drags an object and drops it on a mailbox, the program action should be that the object is mailed. Deleting an object dropped on a mailbox is not an intuitive action and is likely to confuse the user.

Steps to Implement Drag-and-Drop

There are three steps you should follow to implement drag-and-drop. They are

Enable drag-and-drop on the controls
Build the code structure to support drag-and-drop
Provide visual feedback to the user

Enable Drag-and-Drop on the Controls

A successful drag-and-drop operation involves two controls: a drag source and a drop target. The drag source is the control where the drag action begins. You can use a LIST box or a REGION as a drag source in Clarion. The drop target is where the user releases the cursor to complete the drop action. Any Clarion control can be designated as a drop target except for IMAGE, VBX, or OLE controls or graphic primitives (BOX, LINE, ELLIPSE).

There will be time where you want to use an unsupported control (often an image) as a drag source or drop target. The key to making this work is to create a REGION that covers the same window area as the IMAGE (or other) control and use the REGION as the source or target.

To designate a control as a drag source or drop target, you must specify a target string for the control on the Extra tab of the Properties dialog. A target string is a series of one or more string values separated by commas that identifies a drag-and-drop control. There are three types of string values you can specify in a target string:

Regular string values, such as TRASH, which allow drag-and-drop between controls in a single application
String values beginning with ~, such as ~TRASH, which allow drag-and-drop between two different Clarion applications
The special string value ~FILE, which allows a CW application to accept files from File Manager or the Windows Explorer

You will only get a successful drop operation when one of the string values in the drag source target string matches one of the string values in the target string of the drop target. You can determine which component of the target strings matched by calling either the DRAGID or DROPID function after a successful drop.

Depending on the type of control, you may be able to specify a Drag ID, a Drop ID, or both. The Properties dialog for a REGION control is shown here with the fields for the Drag ID and Drop ID target strings marked with red arrows. Specifying a Drag ID (such as TRASH) makes a control into a drag source. Specifying a Drop ID (such as TRASH,~FILE) makes a control into a drop target.

Build the Code Structure to Support Drag-and-Drop

Once you have enabled drag-and-drop on the controls, it is time to build the code structure to support drag-and-drop. There are three new events you have to deal with when doing drag and drop:

EVENT:Dragging is posted to your window's accept loop when a drag-and-drop operation is in progress. This event is posted while the user is moving the mouse with the button held down. (The user must press the button down on a valid drag source first.)
EVENT:Drag is posted to the accept loop when the user releases the mouse button.
EVENT:Drop is posted after a successful drag-and-drop. You will only receive this event if the Drag ID and Drop ID target strings have a match.

At a minimum, you will want to add code to be processed for EVENT:Drop. This code should check the DRAGID or DROPID function to determine which target string value matched and perform whatever action needs to happen after a successful drop. The basic code structure looks like this:

ACCEPT
  CASE EVENT()
  OF EVENT:Drop
    IF DRAGID() = 'TRASH'
      !Do the trash action here
    END
  END
END

Provide Visual Feedback to the User

An important part of drag-and-drop is providing visual feedback to the user during the operation. The Clarion run-time libraries handle the basics of this by changing the cursor during the drag operation. When the user is dragging and is not over a valid drop target, the cursor changes to the familiar "no" symbol. As the user moves the cursor over valid drop targets, the cursor changes from the "no" symbol to a down arrow.

You can override the standard drag-and-drop cursors by providing your own cursor handling code. To do this, you add code to the Dragging and Drag events. The EVENT:Dragging code can check the current value of the DRAGID function to determine if the cursor is over a valid target. Based on the results of this function, the code can change the cursor to indicate to the user what will happen.

The EVENT:Drag code simply cleans up any cursor changes made in the EVENT:Dragging code. (Without this code, the cursor will be "stuck" after the mouse button is released.) The code structure to do make this happen (from the sample program) looks like this:

ACCEPT
  CASE EVENT()
  OF EVENT:Dragging
    CASE DRAGID()
    OF ''
      SETCURSOR('~NO.CUR')
    OF 'NORMAL'
      SETCURSOR('~DROPPAPR.CUR')
    OF 'TOPSECRET'
      SETCURSOR('~DROPFOLD.CUR')
    END
  OF EVENT:Drag
    SETCURSOR()
  OF EVENT:Drop
    !Handle drop action here
  END
END

Advanced Drag-and-Drop

Drag-and-drop can be as simple as dragging from one control to another on the same window or as complex as you want to make it. The sample program demonstrates drag-and-drop with multiple sources and targets.

The program represents the filing system for Private Eyes, Inc. The window has two list boxes, one containing normal files and one containing top secret files. You can drag items between list boxes or drop them on a group of icons representing different actions. The program is also set up to handle drag-and-drop from File Manager or Explorer. Try dragging a file onto the trash can (don't worry - it doesn't really delete the file) to see this in action.

By mastering drag-and-drop you add another tool to your arsenal of user interface items. It is simple to implement but when used correctly provides a powerful, intuitive way for your users to tell your program what they want it to do.