MExternalDropCallback Class Reference

#include <MExternalDropCallback.h>

Class Description

Provides a callback hook into Maya's drag-and-drop mechanism.

This class is used to register callbacks to gain access to Maya's drag-and-drop information during dropping an external object to Maya. You can replace or augment Maya's drop behavior for external drag-and-drop operations.

To register callbacks, inherit from this class and override externalDropCallback(). The method can be overridden by the callback. Then register the callbacks by calling the addCallback() method.

Each of the callback methods gets passed the name of the drop site control and an MExternalDropData instance which contains additional information provided by the system (for example, text or URL information associated with the drop).

If multiple callbacks need to be registered, the order of invocation can be set by adding each callback with a priority number, 0 being the highest priority. Callbacks are then invoked in priority order. Note that the first callback that does not return kMayaDefault will cause the invocations to stop; lower priority callbacks will then not be invoked.

Examples:

Public Types
enum	MExternalDropStatus { kMayaDefault = 0, kNoMayaDefaultAndAccept, kNoMayaDefaultAndNoAccept }
	Possible return values from externalDropCallback(), used to inform Maya of what further action to take, if any. More...

Public Member Functions
	MExternalDropCallback ()
	Constructor.
virtual	~MExternalDropCallback ()
	Destructor.
virtual MExternalDropStatus	externalDropCallback (bool doDrop, const MString &controlName, const MExternalDropData &data)=0
	This pure virtual method must be implemented by derived callback classes. More...

Static Public Member Functions
static MStatus	addCallback (MExternalDropCallback *, int priority=0)
	Add a callback to the list. More...
static MStatus	removeCallback (MExternalDropCallback *)
	Remove a callback from the list. More...

Member Enumeration Documentation

enum MExternalDropStatus

Possible return values from externalDropCallback(), used to inform Maya of what further action to take, if any.

Enumerator
kMayaDefault	Run Maya default action.
kNoMayaDefaultAndAccept	Skip Maya default action and accept the drop.
kNoMayaDefaultAndNoAccept	Skip Maya default action and do not accept the drop.

Member Function Documentation

MExternalDropCallback::MExternalDropStatus externalDropCallback ( bool  doDrop, const MString &  controlName, const MExternalDropData &  data  )

pure virtual

This pure virtual method must be implemented by derived callback classes.

It is called one or more times during a drag-and-drop operation, as a user drags the mouse over various UI elements.

When called with doDrop false, the callback is simply checking whether it is valid to drop the current item onto the control in question. If doDrop is true, the callback should actually perform the drop operation, if any.

The controlName provided is the full path to the control, and can be for example passed to MEL commands that query or operate on UI objects.

The MExternalDropData instance contains the actual drop data provided by the operating system. For example, if a file is being dragged from the desktop into Maya, the drop data might contain the path (as a URL) of the file.

Parameters

[in]	doDrop	true if the drop action should actually be performed (on mouse up), or false if this callback is just checking for a valid drop (on mouse drag)
[in]	controlName	the full name of the UI element onto which the drop will take place
[in]	data	an instance of MExternalDropData, allowing access to the data associated with the drop

Returns

a status code indicating what action Maya should take following the callback

Examples:

MStatus addCallback ( MExternalDropCallback *  cb, int  priority = 0  )

static

Add a callback to the list.

Parameters

[in]	cb	The callback object to add.
[in]	priority	The priority of the callback (zero is highest priority).

Returns

status code

Status Codes:

• MS::kSuccess operation successful
• MS::kFailure operation failed - the callback object has already been added
• MS::kInvalidParameter invalid callback object provided

Examples:

MStatus removeCallback ( MExternalDropCallback *  cb )

static

Remove a callback from the list.

Parameters

[in]

cb

The callback object to remove.

Returns

status code

Status Codes:

• MS::kSuccess operation successful
• MS::kFailure operation failed - the callback object has not been previously added
• MS::kInvalidParameter invalid callback object provided

Examples:

---

The documentation for this class was generated from the following files:

• MExternalDropCallback.h
• MExternalDropCallback.cpp