C++ API Reference
Public Types | Public Member Functions | Static Public Member Functions | List of all members
MExternalDropCallback Class Referenceabstract
OpenMayaUI - API module for user interface

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

#include <MExternalDropCallback.h>

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 &targetName, 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 general list. More...
 
static MStatus removeCallback (MExternalDropCallback *)
 Remove a callback from the general list. More...
 
static MStatus addUFEItemCallback (MExternalDropCallback *, int priority=0)
 Add a callback to the list containing UFE item callbacks. More...
 
static MStatus removeUFEItemCallback (MExternalDropCallback *)
 Remove a callback from the list containing UFE item callbacks. More...
 

Detailed 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() or addSceneItemCallback() methods.

Each of the callback methods gets passed the name of the drop site control (in case of using addCallback() for registration) or UFE path string (in case of using addSceneItemCallback() for registration). Also, the callback methods get passed 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:
externalDropCallback/externalDropCallback.cpp.

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

OPENMAYA_NAMESPACE_CLOSEMExternalDropCallback::MExternalDropStatus externalDropCallback ( bool  doDrop,
const MString &  targetName,
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.

In case of using addCallback() for registration, the targetName provided is the full path to the control, and can be for example passed to MEL commands that query or operate on UI objects.

In case of using addSceneItemCallback() for registration, the targetName provided is the full ufe path string to the ufe scene item under the mouse cursor (for example in Outliner).

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]doDroptrue 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]targetNamethe full name of the UI element or the scene item onto which the drop will take place
[in]dataan 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:
externalDropCallback/externalDropCallback.cpp.
MStatus addCallback ( MExternalDropCallback *  cb,
int  priority = 0 
)
static

Add a callback to the general list.

Parameters
[in]cbThe callback object to add.
[in]priorityThe 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:
externalDropCallback/externalDropCallback.cpp.
MStatus removeCallback ( MExternalDropCallback *  cb)
static

Remove a callback from the general list.

Parameters
[in]cbThe 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:
externalDropCallback/externalDropCallback.cpp.
MStatus addUFEItemCallback ( MExternalDropCallback *  cb,
int  priority = 0 
)
static

Add a callback to the list containing UFE item callbacks.

Parameters
[in]cbThe callback object to add.
[in]priorityThe 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
MStatus removeUFEItemCallback ( MExternalDropCallback *  cb)
static

Remove a callback from the list containing UFE item callbacks.

Parameters
[in]cbThe 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
The documentation for this class was generated from the following files: