AfterCreateTable | Hackers Guide to Visual FoxPro 7.0

ClearData, GetData, SetData

These are all methods of the DataObject, a COM object that provides access to data being dragged with OLE drag and drop. ClearData removes all data from the data object. GetData retrieves data, and SetData puts data into the data object.

Usage

oDataObject.ClearData() uResult = oDataObject.GetData( [ nFormat | cFormat ]                                 [, @aHoldData ] ) oDataObject.SetData( uData | @aData [, nFormat | cFormat ] )

Parameter	Value	Meaning
nFormat	1, 7 or 13	Retrieve or place textual data in ASCII, OEM or Unicode format, respectively. As far as we can tell, in the U.S. Windows version of VFP, no native controls automatically supply either OEM or Unicode format data, though other applications might, and you can provide data in one of those formats.
	15	Retrieve or place a list of files.
	16	Documented (for SetData only) as providing a handle to the locale identifier for text on the clipboard, but we haven't been able to retrieve any data in this format.
	Any other number	Retrieve or place data in a custom format.
	Omitted	If cFormat is also omitted, place scalar data in the data object in the text (1) and "OLE Variant" formats, or place array data in the "OLE Variant Array" format.
cFormat	"OLE Variant Array"	Retrieve or place multiple data items in their original format. Use this one to drag a whole array of data.
	"OLE Variant"	Retrieve or place data in its original type. For example, data from a spinner is treated as numeric, using this format.
	"VFP Source Object"	Retrieve a reference to the data source for this drag. By default, all VFP controls make this format available. Data cannot be placed in the data object in this format.
	Any other string	Retrieve or place data in a custom format.
	Omitted	If nFormat is also omitted, place scalar data in the data object in the text (1) and "OLE Variant" formats or place array data in the "OLE Variant Array" format.
aHoldData	Array name	The name of an array holding the data retrieved from the data object. Relevant only for some data formats.
uResult	.T.	Data in one of the array formats was successfully retrieved.
	.F.	The data object doesn't contain any data in the specified format.
	Other	The data retrieved from the data object.
uData	Expression	The data to be placed in the data object for one of the single-valued formats.
aData	Array name	The name of the array holding the data to be placed in the data object. Relevant only for the multi-valued formats.

The more we look at OLE drag and drop, the more we are impressed with its richness and depth. These methods (and, in fact, the whole idea of the data object) are among the things that make OLE drag and drop really powerful.

When you start dragging, the data object is created and data is put into it, based on what you're dragging and from where. For any given drag source, the data object can contain data in several different formats, and a drop target might choose to accept any one (or none) of those formats.

Left to its own devices, VFP (and Windows, as a whole) makes some pretty good decisions about what to do when you drop data. But sometimes you want to go a little further than that. These methods let you do so.

SetData lets you store data in the data object in whatever format you need at the moment, rather than just using the default for this particular pair of objects (the drag source and the drop target). Consider using the format constants in FoxPro.H to make your code easier to read. You can call SetData to stuff data into the data object in the drag source's OLEStartDrag or OLESetData methods. (Despite documentation to the contrary, OLESetData is called right after any custom code in the drop target's OLEDragDrop—that is, before the data is actually dropped.)

You can put just about any kind of data into the data object with SetData, but making sure it'll work is a little trickier. If you're retrieving the data yourself (with GetData), the precise format doesn't matter. But if you want to be able to drag into other applications, you need to get it right, so those apps find what they expect.

For example, with format 15, which provides a list of files, you must be sure each file in your list has a complete path, including drive designator. You can stuff a list of files collected with ADIR(), for example, into the data object, but if you don't add the drive and path, Explorer chokes when you drop them.

GetData is the other end of the process. It lets you pull out the data in whichever format you need at the moment. If you specify a nonexistent format, VFP ignores you and does whatever it would have done if you hadn't spoken up in the first place.

The formats provided actually cover a pretty wide range, so most of the time you won't need to create a custom format. When you do, be aware that the only data you can put there is character data or specially formatted character data created with CreateBinary(). You can't stick numbers or an array or anything fancy like that into a custom data format.

The "VFP Source Object" data type is particularly powerful because it gives you a reference to the object containing the dragged data. You can then do anything you want with that object, including referencing or changing its properties and calling its methods.

ClearData is the easy one to understand here. It pricks a data object and lets out all the air. That is, it removes all the data and all the formats and leaves an empty shell of an object. You can then fill it in with whatever you want. We haven't actually found a reason to use this method yet, other than to test it, but we're sure we will eventually.

Example

* If the data being dragged is a list of files, put * the contents of the first file into the receiving  * edit box's Value. This code would go in the edit box's * DragDrop method. LPARAMETERS oDataObject, nEffect, nButton, nShift, ;             nXCoord, nYCoord   #INCLUDE FOXPRO.H   LOCAL lHasFiles, FileArray[1]   IF oDataObject.GetFormat(CF_FILES)    lHasFiles = oDataObject.GetData(CF_FILES, @FileArray)    This.Value = FileToStr(FileArray[1]) ENDIF