Class IDragAndDropMgr
See Also: Class FPStaticInterface, Class DragAndDropHandler, Class URLTab
class IDragAndDropMgr : public FPStaticInterface
Description:
This class is available in release 4.0 and later only.
The Drag and Drop system is managed through a Core FP interface (DND_MGR_INTERFACE), defined by this class. It provides control over the DnD system, manages handler registration and exposes some useful utility methods for downloading URL’s, simulating drops, etc.
The DragAndDropMgr supports multiple DragAndDropHandlers regsitered against a single HWND window. This is to allow new components and 3rd-party developers to incrementally add handlers for new dropTypes to common windows such as viewports that the default handlers don't know how to handle.
The IDragAndDropMgr::EnableDandD(HWND hwnd, BOOL flag, DragAndDropHandler* handler) method can be called multiple times on the same window with different handler instances. The DnDMgr keeps track of all the DragAndDropHandlers on each window and will call their DnD event methods as needed, in order of registration, until one of them returns S_OK. For example, on a viewport, the DefaultDragAndDropHandler is registered by default. The event methods (such as DragEnter, DragOver, Drop, etc.) return E_FAIL if the dropping IDataObject or DropType is not recognized by them. Then, if a new component registers its own handler to deal with some new droptype it adds, the default handler will fail to recognize the new droptype and so its handler will be called to process the new drop type.
Note that this means DragAndDropHandler event methods must correctly return S_OK or E_FAIL depending on whether they handle the IDataObject or DropType currently dropping, so that the appropriate handler is found and called by the DnDMgr.
For an example, please refer to \MAXSDK\SAMPLES\HOWTO\DND_TEST.
Function:
IDragAndDropMgr* GetDragAndDropMgr();
Remarks:
This function, which is not part of the class, allows you to retrieve a pointer to the Drag and Drop Manager interface. This will return a pointer to the DnD manager interface from the core interface.
Methods:
public:
Prototype:
virtual void EnableDandD(BOOL flag)=0;
Remarks:
This method allows you to globally enable or disable the DnD interface.
Parameters:
BOOL flag
TRUE to enable, FALSE to disable.
Prototype:
virtual BOOL IsEnabled()=0;;
Remarks:
This method returns TRUE if the global DnD interface is enabled, otherwise FALSE.
Prototype:
virtual BOOL EnableDandD(HWND hwnd, BOOL flag, DragAndDropHandler* handler = NULL)=0;;
Remarks:
This method allows you to enable DnD for a given window (and its children). If no custom DragAndDropHandler is supplied, a default one is used that will accept dropped scene files for opening and scripts for running.
Parameters:
HWND hwnd
A handle to the window you wish to enable or disable DnD for.
BOOL flag
TRUE to enable, FALSE to disable.
DragAndDropHandler* handler = NULL
A pointer to a custom DnD handler, or NULL to accept a default one.
Return Value:
TRUE if the method was successful, otherwise FALSE.
Prototype:
virtual BOOL DropPackage(HWND hwnd, POINT& point, URLTab& package)=0;
Remarks:
This method allows the simulation of a package of files into a window at a given point. A package of files, specified as a list of URL strings is the common form of DropType data from iDrop sources and files dragged from the Windows desktop. The entire package is downloaded, as needed, but only the first file in the list is actually dropped into 3ds max. The other files in the package are presumed to be support files, such as texmaps or xref sources, for the main drop file. After the drop, the URL strings in the URLTab are converted to fully-specified path names to local file copies, if any had to be downloaded from the web.
Parameters:
HWND hwnd
A handle to the window. If this is set to NULL, the default 3ds max window is used.
POINT& point
The point at which to drop.
URLTab& package
A reference to the local copies of the URL strings.
Return Value:
TRUE if the drop was successful, otherwise FALSE.
Prototype:
virtual BOOL DownloadPackage(URLTab& package, TCHAR* directory, HWND hwnd = NULL, bool showProgress = false)=0;
Remarks:
This method serves as a utility function that can be used to download a package of URLs to the specified directory. If the hwnd argument is supplied, any progress or other messages are centered over that window.
Parameters:
URLTab& package
A reference to the local copies of the URL strings.
TCHAR* directory
The directory path string to download to.
HWND hwnd = NULL
A handle to the window. If this is set to NULL, the default window is used.
bool showProgress = false
The download progress dialog can be displayed by passing true.
Return Value:
TRUE if the download was successful, otherwise FALSE.
Prototype:
virtual TCHAR* GetDownloadDirectory()=0;
Remarks:
This method returns the fully-specified path to the directory in which package drops are downloaded.
Prototype:
virtual int NumHandlers(HWND hwnd)=0;
Remarks:
This method returns the number of handlers associated with the given window.
Parameters:
HWND hwnd = NULL
A handle to the window.
Prototype:
virtual DragAndDropHandler* GetHandler(HWND hwnd, int i)=0;
Remarks:
This method returns a pointer to a specified DnD hander of a specified window.
Parameters:
HWND hwnd = NULL
A handle to the window.
int i
The I-th handler.
Prototype:
virtual bool DownloadUrlToDisk(HWND hwnd, TCHAR* url, TCHAR* fileName, DWORD dlgflags=0)=0;
Remarks:
This method allows you to download the file referenced by the URL to disk.
Parameters:
HWND hwnd = NULL
A handle to the window.
TCHAR* url
The URL string of the file to download.
TCHAR* fileName
The filename string of the URL to store on disk.
DWORD dlgflags=0
Additional controls to the download behavior. Currently only one flag is supported, DOWNLOADDLG_NOPLACE, which hides an option in the progress dialog that allows the user to place (move) a dropped object immediately after being dropped.
Return Value:
TRUE if the download was successful, otherwise FALSE.
Prototype:
virtual INode* ImportContextNode()=0;
Remarks:
This method returns a pointer to the import context node.