7.2 Drop Handler Interfaces

only for RuBoard - do not distribute or recompile

Now that you know how a drop handler works, let's discuss the interfaces involved in a little more detail.

7.2.1 IDropTarget

As Table 7.1 shows, IDropTarget contains four methods : DragEnter , DragOver , DragLeave , and Drop .

Table7.1. IDropTarget

Method	Description
`DragEnter`	Determines whether a drop is valid.
`DragOver`	Provides drop information as object is dragged over the target.
`DragLeave`	Called when object leaves drop target.
`Drop`	Called when object is dropped on the target.

7.2.1.1 DragEnter

DragEnter is used to determine whether a drop is acceptable. For instance, if the file being dropped is not of a particular type, the operation could be cancelled (we will not do this here). This method also provides us with some minimal keyboard state information, such as whether the Alt, Shift, or Ctrl keys were pressed during the drop. Left- and right-mouse button states are also provided.

The syntax of the DragEnter method is as follows :

 HRESULT DragEnter(IDataObject *pDataObj,                   DWORD grfKeyState,                   POINTL pt,                   DWORD *pdwEffect);

The method's parameters are:

pDataObj

[in] A pointer to an IDataObject interface on a data object. This object contains the data being transferred via the drag-and-drop operation.

grfKeyState

[in] The current state of the keyboard. It can contain one or more of the following values:

Constant	Description
`MK_LBUTTON`	Left mouse button is pressed.
`MK_RBUTTON`	Right mouse button is pressed.
`MK_SHIFT`	Shift key is pressed.
`MK_CONTROL`	Ctrl key is pressed.
`MK_MBUTTON`	Middle mouse button is pressed.
`MK_ALT`	Alt key is pressed.

You should never compare grfKeyState for equality with one of these KEYSTATES values, as in the following code fragment:

 'Do not check for equality If grfKeyState = MK_CONTROL Then . . .

Always mask for the desired values using the And operator, as follows:

 'This is the proper way to determine mouse/key state If grfKeyState And MK_CONTROL Then . . .

pt

[in] The current cursor coordinates. This a POINTL structure that is defined as follows (it's really the same as the POINTAPI structure):

 typedef struct _POINTL {     long x;      long y;  } POINTL;

pdwEffect

[in, out] Upon return, this parameter should contain one or more of the following values from the DROPEFFECT enumeration:

 typedef enum tagDROPEFFECT {      DROPEFFECT_NONE = 0,      DROPEFFECT_COPY = 1,      DROPEFFECT_MOVE = 2,      DROPEFFECT_LINK = 4,      DROPEFFECT_SCROLL = 0x80000000  }DROPEFFECT;

These values have the following meaning:

Constant	Description
`DROPEFFECT_NONE`	Drop target cannot accept the data.
`DROPEFFECT_COPY`	Drop results in a copy. Original data is unmodified.
`DROPEFFECT_MOVE`	Drag source should remove the data.
`DROPEFFECT_LINK`	Drag source should create a link to the original data.
`DROPEFFECT_SCROLL`	Scrolling is about to start or is currently occurring at the target. This value is used in addition to the other values.

As with the grfKeyState parameter, these values should never be checked for equality. Mask the values using the And operator.

7.2.1.2 DragOver

DragOver is implemented in a similar manner to DragEnter . It is called whenever a drag occurs over a respective target, not just upon entry. We will not implement this method, since DragEnter provides all the functionality that we will need. The syntax of DragOver is:

 HRESULT DragOver(   DWORD grfKeyState,    POINTL pt,            DWORD * pdwEffect   );

The parameters to this method are the same as those for DragEnter .

7.2.1.3 DragLeave

DragLeave provides a means to free any references to IDataObject that were possibly held as a result of a DragEnter or DragOver call. We do not store any references to IDataObject ; therefore, this method is not necessary for our drop handler to function properly. Its syntax is:

 HRESULT DragLeave(void);

7.2.1.4 Drop

This method is where the actual drop takes place. Its syntax is as follows:

 HRESULT Drop(   IDataObject * pDataObject,   DWORD grfKeyState,    POINTL pt,            DWORD * pdwEffect   );

The parameters for this method are exactly the same as DragEnter .

7.2.2 IPersistFile

IPersistFile is used to get the target file of the drop. It is implemented exactly as it was in our icon handler. Load is the only method that is implemented. The name of the target file is stored in a private data member, which allows it to be accessed from Drop . See Chapter 5 for an explanation of this interface.

only for RuBoard - do not distribute or recompile