Platforms to show: All Mac Windows Linux Cross-Platform

Back to WindowsDropTargetMBS class.

WindowsDropTargetMBS.DragEnter(dataObject as WinDataObjectMBS, keystate as Integer, x as Integer, y as Integer, byref effect as Integer) as Integer

Type Topic Plugin Version macOS Windows Linux iOS Targets
event Drag & Drop MBS Win Plugin 10.5 ❌ No ✅ Yes ❌ No ❌ No
Indicates whether a drop can be accepted, and, if so, the effect of the drop.

dataObject: This data object contains the data being transferred in the drag-and-drop operation. If the drop occurs, this data object will be incorporated into the target.

KeyState: The current state of the keyboard modifier keys on the keyboard. Possible values can be a combination of any of the flags MK_CONTROL, MK_SHIFT, MK_ALT, MK_BUTTON, MK_LBUTTON, MK_MBUTTON, and MK_RBUTTON.

x and y: A point containing the current cursor coordinates in screen coordinates.

effect: The value of the Effect parameter of the DoDragDrop function. On return, must contain one of the DROPEFFECT flags, which indicates what the result of the drop operation would be.

Return S_OK on success. Other possible values include the following.

Return codeDescription
E_UNEXPECTEDAn unexpected error has occurred.
E_INVALIDARGThe Effect parameter is NULL on input.
E_OUTOFMEMORYThere was insufficient memory available for this operation.

You do not call DragEnter directly; instead the DoDragDrop function calls it to determine the effect of a drop the first time the user drags the mouse into the registered window of a drop target.

To implement DragEnter, you must determine whether the target can use the data in the source data object by checking three things:

  • The format and medium specified by the data object
  • The input value of Effect
  • The state of the modifier keys

To check the format and medium, use the WinDataObjectMBS object.

On entry to WindowsDropTargetMBS.DragEnter, the Effect parameter is set to the effects given to the OkEffect parameter of the DoDragDrop function. The WindowsDropTargetMBS.DragEnter method must choose one of these effects or disable the drop.

The following modifier keys affect the result of the drop.

Key CombinationUser-Visible FeedbackDrop Effect
CTRL + SHIFT=DROPEFFECT_LINK
CTRL+DROPEFFECT_COPY
No keys or SHIFTNoneDROPEFFECT_MOVE

On return, the method must write the effect, one of the DROPEFFECT flags, to the Effect parameter. DoDragDrop then takes this parameter and writes it to its Effect parameter. You communicate the effect of the drop back to the source through DoDragDrop in the Effect parameter. The DoDragDrop function then calls WindowsDragSourceMBS.GiveFeedback so that the source application can display the appropriate visual feedback to the user through the target window.

Some examples using this event:

WindowsDropTargetMBS.DragLeave as Integer

Type Topic Plugin Version macOS Windows Linux iOS Targets
event Drag & Drop MBS Win Plugin 10.5 ❌ No ✅ Yes ❌ No ❌ No
Removes target feedback and releases the data object.

Return S_OK on success. Other possible values include the following.

Return codeDescription
E_OUTOFMEMORYThere is insufficient memory available for this operation.

You do not call this method directly. The DoDragDrop function calls this method in either of the following cases:

  • When the user drags the cursor out of a given target window.
  • When the user cancels the current drag-and-drop operation.

To implement WindowsDropTargetMBS.DragLeave, you must remove any target feedback that is currently displayed. You must also release any references you hold to the data transfer object.

Some examples using this event:

WindowsDropTargetMBS.DragOver(keystate as Integer, x as Integer, y as Integer, byref effect as Integer) as Integer

Type Topic Plugin Version macOS Windows Linux iOS Targets
event Drag & Drop MBS Win Plugin 10.5 ❌ No ✅ Yes ❌ No ❌ No
Provides target feedback to the user and communicates the drop's effect to the DoDragDrop function so it can communicate the effect of the drop back to the source.

KeyState: The current state of the keyboard modifier keys on the keyboard. Valid values can be a combination of any of the flags MK_CONTROL, MK_SHIFT, MK_ALT, MK_BUTTON, MK_LBUTTON, MK_MBUTTON, and MK_RBUTTON.
x and y: The point containing the current cursor coordinates in screen coordinates.
Effect: On input, pointer to the value of the Effect parameter of the DoDragDrop function. On return, must contain one of the DROPEFFECT flags, which indicates what the result of the drop operation would be.

Return S_OK on success. Other possible values include the following.

Return codeDescription
E_UNEXPECTEDAn unexpected error has occurred.
E_INVALIDARGThe Effect value is not valid.
E_OUTOFMEMORYThere was insufficient memory available for this operation.

You do not call DragOver directly. The DoDragDrop function calls this method each time the user moves the mouse across a given target window. DoDragDrop exits the loop if the drag-and-drop operation is canceled, if the user drags the mouse out of the target window, or if the drop is completed.

In implementing WindowsDropTargetMBS.DragOver, you must provide features similar to those in WindowsDropTargetMBS.DragEnter. You must determine the effect of dropping the data on the target by examining the FORMATETC defining the data object's formats and medium, along with the state of the modifier keys. The mouse position may also play a role in determining the effect of a drop. The following modifier keys affect the result of the drop.

Key CombinationUser-Visible FeedbackDrop Effect
CTRL + SHIFT=DROPEFFECT_LINK
CTRL+DROPEFFECT_COPY
No keys or SHIFTNoneDROPEFFECT_MOVE

You communicate the effect of the drop back to the source through DoDragDrop in Effect. The DoDragDrop function then calls WindowsDragSourceMBS.GiveFeedback so the source application can display the appropriate visual feedback to the user.

On entry to WindowsDropTargetMBS.DragOver, the Effect parameter must be set to the allowed effects passed to the OkEffect parameter of the DoDragDrop function. The WindowsDropTargetMBS.DragOver method must be able to choose one of these effects or disable the drop.

Upon return, Effect is set to one of the DROPEFFECT flags. This value is then passed to the Effect parameter of DoDragDrop. Reasonable values are DROPEFFECT_COPY to copy the dragged data to the target, DROPEFFECT_LINK to create a link to the source data, or DROPEFFECT_MOVE to allow the dragged data to be permanently moved from the source application to the target.

You may also wish to provide appropriate visual feedback in the target window. There may be some target feedback already displayed from a previous call to WindowsDropTargetMBS.DragOver or from the initial WindowsDropTargetMBS.DragEnter. If this feedback is no longer appropriate, you should remove it.

For efficiency reasons, a data object is not passed in WindowsDropTargetMBS.DragOver. The data object passed in the most recent call to WindowsDropTargetMBS.DragEnter is available and can be used.

When WindowsDropTargetMBS.DragOver has completed its operation, the DoDragDrop function calls WindowsDragSourceMBS.GiveFeedback so the source application can display the appropriate visual feedback to the user.

Notes to Implementers

This function is called frequently during the DoDragDrop loop so it makes sense to optimize your implementation of the DragOver method as much as possible.

Some examples using this event:

WindowsDropTargetMBS.Drop(dataObject as WinDataObjectMBS, keystate as Integer, x as Integer, y as Integer, byref effect as Integer) as Integer

Type Topic Plugin Version macOS Windows Linux iOS Targets
event Drag & Drop MBS Win Plugin 10.5 ❌ No ✅ Yes ❌ No ❌ No
Incorporates the source data into the target window, removes target feedback, and releases the data object.

dataObject: The data object being transferred in the drag-and-drop operation.
KeyState: The current state of the keyboard modifier keys on the keyboard. Possible values can be a combination of any of the flags MK_CONTROL, MK_SHIFT, MK_ALT, MK_BUTTON, MK_LBUTTON, MK_MBUTTON, and MK_RBUTTON.
x and y: The point containing the current cursor coordinates in screen coordinates.
Effect: On input, the value of the Effect parameter of the DoDragDrop function. On return, must contain one of the DROPEFFECT flags, which indicates what the result of the drop operation would be.

Return S_OK on success. Other possible values include the following.

Return codeDescription
E_UNEXPECTEDAn unexpected error has occurred.
E_INVALIDARGThe pdwEffect parameter is not valid.
E_OUTOFMEMORYThere is insufficient memory available for this operation.

You do not call this method directly. The DoDragDrop function calls this method when the user completes the drag-and-drop operation.

In implementing Drop, you must incorporate the data object into the target. Use the formats available in WinDataObjectMBS, available through dataObject, along with the current state of the modifier keys to determine how the data is to be incorporated, such as linking or embedding.

In addition to incorporating the data, you must also clean up as you do in the WindowsDropTargetMBS.DragLeave method:

Remove any target feedback that is currently displayed.
Release any references to the data object.
You also pass the effect of this operation back to the source application through DoDragDrop, so the source application can clean up after the drag-and-drop operation is complete:

Remove any source feedback that is being displayed.
Make any necessary changes to the data, such as removing the data if the operation was a move.

The items on this page are in the following plugins: MBS Win Plugin.


The biggest plugin in space...