COleDropTarget Class

 

The new home for Visual Studio documentation is Visual Studio 2017 Documentation on docs.microsoft.com.

The latest version of this topic can be found at COleDropTarget Class.

Provides the communication mechanism between a window and the OLE libraries.

Syntax

class COleDropTarget : public CCmdTarget  

Members

Public Constructors

Name	Description
COleDropTarget::COleDropTarget	Constructs a COleDropTarget object.

Public Methods

Name	Description
COleDropTarget::OnDragEnter	Called when the cursor first enters the window.
COleDropTarget::OnDragLeave	Called when the cursor is dragged out of the window.
COleDropTarget::OnDragOver	Called repeatedly when the cursor is dragged over the window.
COleDropTarget::OnDragScroll	Called to determine whether the cursor is dragged into the scroll region of the window.
COleDropTarget::OnDrop	Called when data is dropped into the window, default handler.
COleDropTarget::OnDropEx	Called when data is dropped into the window, initial handler.
COleDropTarget::Register	Registers the window as a valid drop target.
COleDropTarget::Revoke	Causes the window to cease being a valid drop target.

Remarks

Creating an object of this class allows a window to accept data through the OLE drag-and-drop mechanism.

To get a window to accept drop commands, you should first create an object of the COleDropTarget class, and then call the Register function with a pointer to the desired CWnd object as the only parameter.

For more information on drag-and-drop operations using OLE, see the article Drag and Drop (OLE).

Inheritance Hierarchy

CObject

CCmdTarget

COleDropTarget

Requirements

Header: afxole.h

COleDropTarget::COleDropTarget

Constructs an object of class COleDropTarget.

COleDropTarget();

Remarks

Call Register to associate this object with a window.

COleDropTarget::OnDragEnter

Called by the framework when the cursor is first dragged into the window.

virtual DROPEFFECT OnDragEnter(
    CWnd* pWnd,  
    COleDataObject* pDataObject,  
    DWORD dwKeyState,  
    CPoint point);

Parameters

pWnd
Points to the window the cursor is entering.

pDataObject
Points to the data object containing the data that can be dropped.

dwKeyState
Contains the state of the modifier keys. This is a combination of any number of the following: MK_CONTROL, MK_SHIFT, MK_ALT, MK_LBUTTON, MK_MBUTTON, and MK_RBUTTON.

point
Contains the current location of the cursor in client coordinates.

Return Value

The effect that would result if a drop were attempted at the location specified by point. It can be one or more of the following:

• DROPEFFECT_NONE A drop would not be allowed.

• DROPEFFECT_COPY A copy operation would be performed.

• DROPEFFECT_MOVE A move operation would be performed.

• DROPEFFECT_LINK A link from the dropped data to the original data would be established.

• DROPEFFECT_SCROLL A drag scroll operation is about to occur or is occurring in the target.

Remarks

Override this function to allow drop operations to occur in the window. The default implementation calls CView::OnDragEnter, which simply returns DROPEFFECT_NONE by default.

For more information, see IDropTarget::DragEnter in the Windows SDK.

COleDropTarget::OnDragLeave

Called by the framework when the cursor leaves the window while a dragging operation is in effect.

virtual void OnDragLeave(CWnd* pWnd);

Parameters

pWnd
Points to the window the cursor is leaving.

Remarks

Override this function if you want special behavior when the drag operation leaves the specified window. The default implementation of this function calls CView::OnDragLeave.

For more information, see IDropTarget::DragLeave in the Windows SDK.

COleDropTarget::OnDragOver

Called by the framework when the cursor is dragged over the window.

virtual DROPEFFECT OnDragOver(
    CWnd* pWnd,  
    COleDataObject* pDataObject,  
    DWORD dwKeyState,  
    CPoint point);

Parameters

pWnd
Points to the window that the cursor is over.

pDataObject
Points to the data object that contains the data to be dropped.

dwKeyState
Contains the state of the modifier keys. This is a combination of any number of the following: MK_CONTROL, MK_SHIFT, MK_ALT, MK_LBUTTON, MK_MBUTTON, and MK_RBUTTON.

point
Contains the current location of the cursor in client coordinates.

Return Value

The effect that would result if a drop were attempted at the location specified by point. It can be one or more of the following:

• DROPEFFECT_NONE A drop would not be allowed.

• DROPEFFECT_COPY A copy operation would be performed.

• DROPEFFECT_MOVE A move operation would be performed.

• DROPEFFECT_LINK A link from the dropped data to the original data would be established.

• DROPEFFECT_SCROLL Indicates that a drag scroll operation is about to occur or is occurring in the target.

Remarks

This function should be overridden to allow drop operations to occur in the window. The default implementation of this function calls CView::OnDragOver, which returns DROPEFFECT_NONE by default. Because this function is called frequently during a drag-and-drop operation, it should be optimized as much as possible.

For more information, see IDropTarget::DragOver in the Windows SDK.

Example

DROPEFFECT COleContainerView::OnDragOver(COleDataObject* pDataObject, 
   DWORD dwKeyState, CPoint point)
{
   UNREFERENCED_PARAMETER(pDataObject);
   UNREFERENCED_PARAMETER(point);

   DROPEFFECT de = DROPEFFECT_NONE;
   //Determine the type of operation
   if((dwKeyState & MK_SHIFT) && (dwKeyState & MK_CONTROL))
      de = DROPEFFECT_LINK;
   else if(dwKeyState &  MK_CONTROL)
      de = DROPEFFECT_COPY;
   else if(dwKeyState & MK_SHIFT)
      de = DROPEFFECT_MOVE;
   return de;
}

COleDropTarget::OnDragScroll

Called by the framework before calling OnDragEnter or OnDragOver to determine whether point is in the scrolling region.

virtual DROPEFFECT OnDragScroll(
    CWnd* pWnd,  
    DWORD dwKeyState,  
    CPoint point);

Parameters

pWnd
Points to the window the cursor is currently over.

dwKeyState
Contains the state of the modifier keys. This is a combination of any number of the following: MK_CONTROL, MK_SHIFT, MK_ALT, MK_LBUTTON, MK_MBUTTON, and MK_RBUTTON.

point
Contains the location of the cursor, in pixels, relative to the screen.

Return Value

The effect that would result if a drop were attempted at the location specified by point. It can be one or more of the following:

• DROPEFFECT_NONE A drop would not be allowed.

• DROPEFFECT_COPY A copy operation would be performed.

• DROPEFFECT_MOVE A move operation would be performed.

• DROPEFFECT_LINK A link from the dropped data to the original data would be established.

• DROPEFFECT_SCROLL Indicates that a drag scroll operation is about to occur or is occurring in the target.

Remarks

Override this function when you want to provide special behavior for this event. The default implementation of this function calls CView::OnDragScroll, which returns DROPEFFECT_NONE and scrolls the window when the cursor is dragged into the default scroll region inside the border of the window.

COleDropTarget::OnDrop

Called by the framework when a drop operation is to occur.

virtual BOOL OnDrop(
    CWnd* pWnd,  
    COleDataObject* pDataObject,  
    DROPEFFECT dropEffect,  
    CPoint point);

Parameters

pWnd
Points to the window the cursor is currently over.

pDataObject
Points to the data object that contains the data to be dropped.

dropEffect
The effect that the user chose for the drop operation. It can be one or more of the following:

• DROPEFFECT_COPY A copy operation would be performed.

• DROPEFFECT_MOVE A move operation would be performed.

• DROPEFFECT_LINK A link from the dropped data to the original data would be established.

point
Contains the location of the cursor, in pixels, relative to the screen.

Return Value

Nonzero if the drop is successful; otherwise 0.

Remarks

The framework first calls OnDropEx. If the OnDropEx function does not handle the drop, the framework then calls this member function, OnDrop. Typically, the application overrides OnDropEx in the view class to handle right mouse-button drag and drop. Typically, the view class OnDrop is used to handle simple drag and drop.

The default implementation of COleDropTarget::OnDrop calls CView::OnDrop, which simply returns FALSE by default.

For more information, see IDropTarget::Drop in the Windows SDK.

COleDropTarget::OnDropEx

Called by the framework when a drop operation is to occur.

virtual DROPEFFECT OnDropEx(
    CWnd* pWnd,  
    COleDataObject* pDataObject,  
    DROPEFFECT dropDefault,  
    DROPEFFECT dropList,  
    CPoint point);

Parameters

pWnd
Points to the window the cursor is currently over.

pDataObject
Points to the data object that contains the data to be dropped.

dropDefault
The effect that the user chose for the default drop operation based on the current key state. It can be DROPEFFECT_NONE. Drop effects are discussed in the Remarks section.

dropList
A list of the drop effects that the drop source supports. Drop effect values can be combined using the bitwise OR ( |) operation. Drop effects are discussed in the Remarks section.

point
Contains the location of the cursor, in pixels, relative to the screen.

Return Value

The drop effect that resulted from the drop attempt at the location specified by point. Drop effects are discussed in the Remarks section.

Remarks

The framework first calls this function. If it does not handle the drop, the framework then calls OnDrop. Typically, you will override OnDropEx in the view class to support right mouse-button drag and drop. Typically, the view class OnDrop is used to handle the case of support for simple drag and drop.

The default implementation of COleDropTarget::OnDropEx calls CView::OnDropEx. By default, CView::OnDropEx simply returns a dummy value to indicate the OnDrop member function should be called.

Drop effects describe the action associated with a drop operation. See the following list of drop effects:

• DROPEFFECT_NONE A drop would not be allowed.

• DROPEFFECT_COPY A copy operation would be performed.

• DROPEFFECT_MOVE A move operation would be performed.

• DROPEFFECT_LINK A link from the dropped data to the original data would be established.

• DROPEFFECT_SCROLL Indicates that a drag scroll operation is about to occur or is occurring in the target.

For more information, see IDropTarget::Drop in the Windows SDK.

COleDropTarget::Register

Call this function to register your window with the OLE DLLs as a valid drop target.

BOOL Register(CWnd* pWnd);

Parameters

pWnd
Points to the window that is to be registered as a drop target.

Return Value

Nonzero if registration is successful; otherwise 0.

Remarks

This function must be called for drop operations to be accepted.

For more information, see RegisterDragDrop in the Windows SDK.

COleDropTarget::Revoke

Call this function before destroying any window that has been registered as a drop target through a call to Register to remove it from the list of drop targets.

virtual void Revoke();

Remarks

This function is called automatically from the OnDestroy handler for the window that was registered, so it is usually not necessary to call this function explicitly.

For more information, see RevokeDragDrop in the Windows SDK.

See Also

MFC Sample HIERSVR
MFC Sample OCLIENT
CCmdTarget Class
Hierarchy Chart
COleDropSource Class