This reference page is linked to from the following overview topics: Incremental Improvements, Deferred Loading of Plug-ins.

Detailed Description

The base class from which specialized drag-and-drop handlers should be derived.

#include <idraganddrop.h>

Inheritance diagram for DragAndDropHandler:

[legend]

List of all members.

Public Member Functions
	DragAndDropHandler ()
	constructor
virtual CoreExport HRESULT	DragEnter (HWND window, IDataObject pDataObject, DWORD grfKeyState, POINTL pt, DWORD pdwEffect)
	Gets low level control over drag and drop operations.
virtual CoreExport HRESULT	Drop (HWND window, IDataObject pDataObject, DWORD grfKeyState, POINTL pt, DWORD pdwEffect)
virtual CoreExport HRESULT	DragOver (HWND window, DWORD grfKeyState, POINTL pt, DWORD *pdwEffect)
virtual CoreExport HRESULT	DragLeave (HWND window)
virtual HRESULT	DragEnter (HWND window, DropType type, DWORD grfKeyState, POINT &pt, DWORD pdwEffect)
virtual HRESULT	Drop (HWND window, DropType type, DWORD grfKeyState, POINT &pt, DWORD pdwEffect)
virtual HRESULT	DragOver (HWND window, DWORD grfKeyState, POINT &pt, DWORD *pdwEffect)
virtual void	Acquire ()
virtual void	Release ()
	This method is called called during a when the drag and drop manager stops managing drag and drop events for a particular window for this handler.
Protected Attributes
DropType *	current_droptype
	Cache for the currently parsed DropType.
Static Protected Attributes
static CoreExport IDragAndDropMgr *	dndMgr
	Cached pointer to drag and drop manager.

Constructor & Destructor Documentation

DragAndDropHandler ( ) [inline]

constructor

        : current_droptype(NULL)
    {
        if (dndMgr == NULL)
            dndMgr = GetDragAndDropMgr();
    }

Member Function Documentation

virtual CoreExport HRESULT DragEnter	(	HWND	window,
		IDataObject *	pDataObject,
		DWORD	grfKeyState,
		POINTL	pt,
		DWORD *	pdwEffect
	)		`[virtual]`

Search for all occurrences

Gets low level control over drag and drop operations.

Override this method in your DragAndDropHandler subclass to get low-level control over drag and drop operations. This is just a redirect of the identical method called on the OLE IDropTarget interface, see MSDN docs for details.

The default implementation for this methods use the DropClipFormat and DropType classes to recognize and parse the incoming IDataObject into a DropType instance and hand this to the associated high-level drag and drop handler methods desribed next.

As an example, here is the default DragEnter() implementation which does the initial parsing on entry to a window:

    HRESULT DragAndDropHandler::DragEnter(HWND hWnd, IDataObject* pDataObject, DWORD grfKeyState, POINTL pt, DWORD* pdwEffect)
    {
        current_droptype = NULL;
        // look for one of our accepted clip formats
        DropClipFormat* cf = DropClipFormat::FindClipFormat(pDataObject);
        if (cf != NULL)
        {
            // have one, get it to parse it into a DropType subclass
            current_droptype = cf->ParseDataObject(pDataObject);
            if (current_droptype != NULL)
            {
                // got recognizable drop data,
                // pass on to high-level method
                if(pdwEffect)
                    *pdwEffect = DROPEFFECT_LINK|DROPEFFECT_COPY;

                POINT p = { pt.x, pt.y };
                DragEnter(hWnd, current_droptype, grfKeyState, p, pdwEffect);
                return S_OK;
            }
        }
        // nothing for us
        if(pdwEffect)
            *pdwEffect = DROPEFFECT_NONE;
        return S_OK;
    }

Parameters:

window	- The specified handle to the window in which the drag and drop event is occuring. This is one of the windows that was enabled via a IDragAndDropMgr::EnabledDnD() call, so it may be the parent of the lowest-level window that the mouse is actually over.
pDataObject	- The incoming IDataObject.
grfKeyState	- The specified 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.
pt	- The specified current cursor coordinates in the coordinate space of the drop-target window.
pdwEffect	- On entry, pointer to the value of the pdwEffect parameter of the DoDragDrop function. On return, must contain one of the effect flags from the Win32 DROPEFFECT enumeration, which indicates what the result of the drop operation would be.

Returns:: Standard return values of E_OUTOFMEMORY, E_INVALIDARG, F_UNEXPECTED, and E_FAIL, S_OK.

virtual CoreExport HRESULT Drop	(	HWND	window,
		IDataObject *	pDataObject,
		DWORD	grfKeyState,
		POINTL	pt,
		DWORD *	pdwEffect
	)		`[virtual]`

Search for all occurrences

Remarks:: This method will parse the dropped dataObject.

Parameters:: HWND window

The specified handle to the window in which the drag and drop event is occuring. This is one of the windows that was enabled via a IDragAndDropMgr::EnabledDnD() call, so it may be the parent of the lowest-level window that the mouse is actually over.

IDataObject* pDataObject

The incoming IDataObject.

DWORD grfKeyState

The specified 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.

POINTL pt

The specified current cursor coordinates in the coordinate space of the drop-target window.

DWORD* pdwEffect

On entry, pointer to the value of the pdwEffect parameter of the DoDragDrop function. On return, must contain one of the effect flags from the Win32 DROPEFFECT enumeration, which indicates what the result of the drop operation would be.

Returns:: Standard return values of E_OUTOFMEMORY, E_INVALIDARG, F_UNEXPECTED, and E_FAIL, S_OK.

virtual CoreExport HRESULT DragOver	(	HWND	window,
		DWORD	grfKeyState,
		POINTL	pt,
		DWORD *	pdwEffect
	)		`[virtual]`

Search for all occurrences

Remarks:: This method handles the process of dragging over a drop target.

Parameters:: HWND window

The specified handle to the window in which the drag and drop event is occuring. This is one of the windows that was enabled via a IDragAndDropMgr::EnabledDnD() call, so it may be the parent of the lowest-level window that the mouse is actually over.

DWORD grfKeyState

The specified 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.

POINTL pt

The specified current cursor coordinates in the coordinate space of the drop-target window.

DWORD* pdwEffect

On entry, pointer to the value of the pdwEffect parameter of the DoDragDrop function. On return, must contain one of the effect flags from the Win32 DROPEFFECT enumeration, which indicates what the result of the drop operation would be.

Returns:: Standard return values of E_OUTOFMEMORY, E_INVALIDARG, F_UNEXPECTED, and E_FAIL, S_OK.

virtual CoreExport HRESULT DragLeave ( HWND window ) [inline, virtual]

Search for all occurrences

Remarks:: This method handles the process of the drag operation leaving the drop target window.

Parameters:: HWND window

The specified handle to the window in which the drag and drop event is occuring. This is one of the windows that was enabled via a IDragAndDropMgr::EnabledDnD() call, so it may be the parent of the lowest-level window that the mouse is actually over.

Returns:: Standard return values of E_OUTOFMEMORY, E_INVALIDARG, F_UNEXPECTED, and E_FAIL, S_OK.

Default Implementation:: { return E_FAIL; }

{ return E_FAIL; }

virtual HRESULT DragEnter	(	HWND	window,
		DropType *	type,
		DWORD	grfKeyState,
		POINT &	pt,
		DWORD *	pdwEffect
	)		`[inline, virtual]`

Search for all occurrences

Remarks:: This is the high-level method called to handle drag and drop events with already recognized and parsed data object. Override the above methods as needed in your DragAndDropHandler subclass to handle drag and drop events.

Parameters:: HWND window

The specified handle to the window in which the drag and drop event is occuring. This is one of the windows that was enabled via a IDragAndDropMgr::EnabledDnD() call, so it may be the parent of the lowest-level window that the mouse is actually over.

DropType* type

The specified Pointer to the DropType instance that corresponds to the data in the dropped IDataObject. You can use the DropType::TypeCode() method to determine the droptype (see the built-in codes in the DropType section). Each DropType subclass instance has utility methods and public data members containing the parsed drop data. See each subclass definition for details.

DWORD grfKeyState

The specified 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.

POINT& pt

The specified current cursor coordinates in the coordinate space of the drop-target window.

DWORD* pdwEffect

On entry, pointer to the value of the pdwEffect parameter of the DoDragDrop function. On return, must contain one of the effect flags from the Win32 DROPEFFECT enumeration, which indicates what the result of the drop operation would be.

Returns:: Standard return values of E_OUTOFMEMORY, E_INVALIDARG, F_UNEXPECTED, and E_FAIL, S_OK.

Default Implementation:: { return E_FAIL; }

{ return E_FAIL; }

virtual HRESULT Drop	(	HWND	window,
		DropType *	type,
		DWORD	grfKeyState,
		POINT &	pt,
		DWORD *	pdwEffect
	)		`[inline, virtual]`

Search for all occurrences

Remarks:

This method will parse the dropped dataObject.

Here's an example implementation of Drop() in the default handler:

    HRESULT DefaultDragAndDropHandler::Drop(HWND hwnd, DropType* type, DWORD grfKeyState, POINT& pt, DWORD* pdwEffect)
    {
    // This could take a while, set wait cursor
    HCURSOR hOldCursor = SetCursor(LoadCursor(NULL, IDC_WAIT));
    HRESULT result = S_OK;

    // load the dropped data if needed
    if (type->Load()) {
    // see if dropped on a viewport, if so adjust point
    // to be vp-relative
    HWND vpwin = FindDropViewport(hwnd, pt);

    // Handle the drop depending on drop type
    BOOL bRet;
    switch (type->TypeCode()) {
    case SCENEFILE_DROPTYPE:
    bRet = HandleDroppedGeom(
    hwnd, vpwin, pt,
    sceneFileDropType.current_package[0]);
    break;
    case IMAGEFILE_DROPTYPE:
    bRet = HandleDroppedBitmap(
    hwnd, vpwin, pt,
    imageFileDropType.current_package[0]);
    break;
    case DROPSCRIPTEFILE_DROPTYPE:
    bRet = HandleDroppedDropScript(
    hwnd, vpwin, pt,
    dropScriptFileDropType.current_package[0]);
    break;
    }
    result = bRet ? S_OK : E_FAIL;
    }
    // restore cursor
    SetCursor(hOldCursor);
    return result;
    }

Parameters:: HWND window

The specified handle to the window in which the drag and drop event is occuring. This is one of the windows that was enabled via a IDragAndDropMgr::EnabledDnD() call, so it may be the parent of the lowest-level window that the mouse is actually over.

DropType* type

The specified Pointer to the DropType instance that corresponds to the data in the dropped IDataObject. You can use the DropType::TypeCode() method to determine the droptype (see the built-in codes in the DropType section). Each DropType subclass instance has utility methods and public data members containing the parsed drop data. See each subclass definition for details.

DWORD grfKeyState

The specified 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.

POINT& pt

The specified current cursor coordinates in the coordinate space of the drop-target window.

DWORD* pdwEffect

On entry, pointer to the value of the pdwEffect parameter of the DoDragDrop function. On return, must contain one of the effect flags from the Win32 DROPEFFECT enumeration, which indicates what the result of the drop operation would be.

Returns:: Standard return values of E_OUTOFMEMORY, E_INVALIDARG, F_UNEXPECTED, and E_FAIL, S_OK.

Default Implementation:: { return E_FAIL; }

{ return E_FAIL; }

virtual HRESULT DragOver	(	HWND	window,
		DWORD	grfKeyState,
		POINT &	pt,
		DWORD *	pdwEffect
	)		`[inline, virtual]`

Search for all occurrences

Remarks:: This method handles the process of dragging over a drop target.

Parameters:: HWND window

The specified handle to the window in which the drag and drop event is occuring. This is one of the windows that was enabled via a IDragAndDropMgr::EnabledDnD() call, so it may be the parent of the lowest-level window that the mouse is actually over.

DWORD grfKeyState

The specified 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.

POINT& pt

The specified current cursor coordinates in the coordinate space of the drop-target window.

DWORD* pdwEffect

On entry, pointer to the value of the pdwEffect parameter of the DoDragDrop function. On return, must contain one of the effect flags from the Win32 DROPEFFECT enumeration, which indicates what the result of the drop operation would be.

Returns:: Standard return values of E_OUTOFMEMORY, E_INVALIDARG, F_UNEXPECTED, and E_FAIL, S_OK.

Default Implementation:: { return E_FAIL; }

{ return E_FAIL; }

virtual void Acquire ( ) [inline, virtual]

Search for all occurrences

Remarks:: This method is called when the drag and drop manager starts managing a window for this handler. managing drag and drop events for a particular window for this handler. You can provide an implementation if you need to keep track of extant uses of the handler (say, by ref-counting) or to do handler-specific cleanup.

Default Implementation:: { }

{ };

virtual void Release ( ) [inline, virtual]

Search for all occurrences

This method is called called during a when the drag and drop manager stops managing drag and drop events for a particular window for this handler.

By default, the drag and drop manager will call this method on all registered DragAndDropHandler's during a NOTIFY_SYSTEM_SHUTDOWN broadcast. You should provide an implementation if you need to keep track of extant uses of the handler (say, by ref-counting) or to do handler-specific cleanup.

Default Implementation:: { }

{ };

Member Data Documentation

DropType* current_droptype [protected]

Search for all occurrences

Cache for the currently parsed DropType.

This is usually filled in during DragEnter() processing in the DragAndDropHandler for the current window.

CoreExport IDragAndDropMgr* dndMgr [static, protected]

Search for all occurrences

Cached pointer to drag and drop manager.

DragAndDropHandler Class Reference

Detailed Description

Public Member Functions

Protected Attributes

Static Protected Attributes

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation