Object

DragItem Class

Used to transfer data being dragged by the user.

Properties
Destination | FolderItemAvailable | RawData
DropHeight | Handle | RawDataAvailable
DropLeft | MouseCursor | Text
DropTop | Picture | TextAvailable
DropWidth | PictureAvailable |
FolderItem | PrivateRawData |

Methods
AddItem
Drag
NextItem

# Notes

When the user wishes to drag some data from a Window or Control, a new DragItem object must be created to hold that data in order to transfer it to the object the data will be dropped on. REALbasic implements true drag and drop -- which means that the recipient of the data can be anything that supports drag and drop and supports the kind of data being dragged. For example, text can be dragged to the desktop to create a text clipping file or any application that accepts dropped text (like SimpleText or the NotePad). Pictures can be dragged to the Desktop to create picture clipping files. Other types of data can be dragged using the RawData property.

By default, a DragItem can contain only one row containing a single entry for each data type. Using the AddItem method, you can add more rows to the DragItem allowing multiple entries of the same data type. For example, if you wanted a drag item to contain two separate pictures, you would assign one picture to the Picture property then call the AddItem method to add a row and then assign the second picture to the Picture property.

The RawData and PrivateRawData properties allow you to support drag and drop for other data formats. You specify the data format using a four-character Type, corresponding to a Macintosh resource type. RawData and PrivateRawData return the dragged item as a String. It is up to the control or window that receives the DragItem to manage it. Typically, this will mean that you will have to make API calls or use a plug-in that is designed to handle the data format.

You can also use RawData or PrivateRawData to control internal drag and drop. If you make up a four-character Type (not an existing Macintosh resource type), you can prevent a control from receiving dragged text from other sources. See the example of dragging from one ListBox to another.

For EditFields, drag and drop is supported only if the MultiLine property is True (checked). There is no need to create a DragItem for EditFields as this is handled automatically by REALbasic.

ListBoxes support the dragging of rows automatically if the EnableDrag property of the ListBox is True (checked). Like EditFields, REALbasic creates the DragItem for the ListBox automatically but you must populate the DragItem in the DragRow event handler. See the notes for the ListBox control for more information on dragging from ListBoxes.

The DropWidth and DropHeight properties have no meaning in Win32 and will return 0 unless set using NewDragItem.

## Dragging Promised Files

Mac OS X supports the concept of dragging a file before it actually exists in the file system. It could be a new document that hasn't been saved yet or a file that exists on a remote server or on the web.

In these cases, the drag and drop gesture serves the purpose of specifying the location at which to save the new file. When the drag and drop operation is complete, it tells the source where it wants the files saved and the dragging source creates the files. This special type of file drag is called a promise because the drag operation contains a promise from the source to the destination that the source will create the specified files if the drag and drop is accepted.

To drag and drop promised files, call the RectControl or Window's AcceptRawDataDrop method with "phfs" as the data type. When an application that sends file promises is dropped on your application, you will find a FolderItem in the dragged item. Usually this will point to a file in the TemporaryItems folder and you should ordinarily delete it when you are finished with it.

# Examples

This example shows how to implement dragging the picture in a Canvas control. This example uses the Me keyword to refer to the Canvas control.

Function MouseDown(X As Integer, Y As Integer) As Boolean
Dim d as DragItem
d=NewDragItem( Me.left, Me.top, Me.width, Me.height)
d.picture= Me.Backdrop
d.Drag //Allow the drag

See also the example for ImageWell, which illustrates drag and drop between two ImageWells and PICT files or clippings on the desktop and the ListBox control, which has an example of drag and drop between two ListBoxes.

The following example implements a 'mover' interface in which a user can drag rows from ListBox1 to ListBox2 (and in the reverse direction), but neither ListBox accepts dragged text from other controls or from outside the REALbasic application. It uses PrivateRawData since it also prevents text from being dragged outside the application.

To permit drag and drop in both directions, the two ListBoxes are set up in an identical manner.

Each ListBox has its EnableDrag property set to True. The DragRow event handler is:

Function DragRow (drag as DragItem, row as Integer) As Boolean
Drag.PrivateRawData("text")= Me.List(Row)+ EndOfLine //get the text
Me.RemoveRow(Row)
Return True //allow the drag

To enable each ListBox to accept the dragged text, the following statement appears in its Open event handler:

Me.AcceptRawDataDrop("text")

The DropObject event handler is as follows:

Sub DropObject (obj as DragItem)
If obj.RawDataAvailable("text") then
Me.AddRow(obj.RawData("text"))
end if

The following example allows the user to drag several text files from the desktop to an EditField. The example places the contents of all the text files in the EditField, appending each file's contents to the Text property of the EditField.

To support several files, the NextItem function is used to determine whether there are any more files remaining to be dropped.

Dim textStream as TextInputStream
If obj.folderItemAvailable then
Do
textStream=obj. FolderItem.Openastextfile
Me.text= Me.text+textstream.readall+ Chr(13)
loop until not obj.NextItem
End if

The EditField has the line:

Me.AcceptFileDrop("text")

in its Open event handler, where "text" is as a File Type of files of Macintosh type TEXT.

# See Also

Canvas, EditField, ImageWell, ListBox controls; Picture, FileType, FolderItem classes.