Class DropScriptDropType
See Also: Class DropType, Class DragAndDropHandler, Class FPParams, Class MacroEntry, List of DropTypes
class DropScriptDropType : public DropType
Description:
This class is available in release 4.0 and later only.
This class is an intermediate base class for drop content that comes in the form of a dropScript. This is a special kind of macroScript that implements dropScript event handlers (see the DropScript documentation for details.) The prime subclass is DropScriptFileDropType which recognizes files of type .ds. The parsed data for this type is a single parsed macroScript, represented as a MacroEntry pointer. The DropScriptDropType class provides utility methods for compiling a .ds file into the current_dropscript slot and for running the DnD-associated handlers in the current dropScript.
The methods RunDropScriptDragEnter(FPParams* params), RunDropScriptDragOver(FPParams* params) and RunDropScriptDrop(FPParams* params) take care of the ‘on droppable’ handler in the current_dropscript, if supplied. The DragAndDropHandler::DragEnter call is usualy made once on initial entry to a registered DnD target window and DragAndDropHandler::DragOver is usually called as the mouse moves over this window. In both cases, the handler returns true or false to indicate whether the dropping dropScript will be accepted. If a handler is not supplied, the dropScript is always deemed droppable. If the handler returns false, the not-droppable cursor is shown.
The handler is called with a set of arguments, supplied by the DragAndDropHandler, that usually depends on the window currently under the mouse pointer. For example, over a viewport, the current mouse coordinates, scene node under the mouse, slot number in a list window, etc. By convention, the first argument is positional and always a window type name, such as "Viewport" or "MaterialEditor", and all the others are keyword arguments, since they will vary from window to window. They are delivered to the RunDropScriptXXX methods in a Function Publishing FPParam object, so that handler code needs to deal as little as possible with the MAXScript SDK. Here's an example code fragment from the default drop handler:
FPParams params (6,
TYPE_NAME, (vpwin ? _T("viewport") : _T("max")),
TYPE_KEYARG_MARKER,
TYPE_NAME, _T("node"),
TYPE_INODE, m_nodectx,
TYPE_NAME, _T("point"),
TYPE_POINT, &pt);
// run the dragEnter handler & set dropeffect based on result
if (dropScriptFileDropType.RunDropScriptDragEnter(¶ms))
*pdwEffect = DROPEFFECT_COPY;
else
*pdwEffect = DROPEFFECT_NONE;
In the above code, the handler is called with 3 actual arguments, one position and two keyword. They are loaded into the 'params' instance with the FPParams varargs constructor. The first is the positional window name, in this case either #viewport or #max, then comes a special TYPE_KEYARG_MARKER signalling that the following arguments are keyword. The keyword args are given in pairs, name then value, in this case node: and point:. See the Function Publishing system documentation for full details on using the FPParams class for passing parameter blocks. An example droppable handler might be as follows:
on droppable window node: do
return window == #viewport and superclassOf node == Shape
This handler effectively makes the dropScript droppable if the mouse is over a Shape object in a viewport window. Notice that the function only looks at the node: keyword argument in this definition; arguments delivered as keyword arguments can vary from call to call and the called function can choose to look at only subset of them.
Data Members:
public
static MacroEntry* current_dropscript;
Cache for current macroScript. See \MAXSDK\INCLUDE\iMacroScript.h for the MacroScript manager public API. There are also utility methods in DropScriptDropType that do all the necessary DnD compiling & running of macroScripts, so you only have to deal with the MacroScript manager for special processing.
Methods:
public:
Prototype:
virtual int TypeCode()=0;
Remarks:
This method returns the typecode of the DropType.
Default Implementation:
{ return DROPSCRIPT_DROPTYPE; }
Prototype:
virtual bool IsDropType(int code);
Remarks:
This method returns TRUE if the DropType is of the specified DropType code, otherwise FALSE.
Parameters:
int code
The DropType code.
Default Implementation:
{ return code == TypeCode() || code == DROPSCRIPT_DROPTYPE; }
Prototype:
virtual DWORD DropEffect();
Remarks:
This method returns the dropeffect currently supported by the accepted dropping type.
Default Implementation:
{ return DROPEFFECT_MOVE; }
The following methods provide assistance for developing custom drag-and-drop handlers that want to accept dropScripts. They work on the shared current_dropscript static data member in DropScriptDropType.
Prototype:
BOOL CompileDropScript(TCHAR* filename);
Remarks:
This method parses the given file, looking for a single macroScript definition. If successful, interns the macroScript and places its corresponding MacroEntry* in the current_dropscript static data member. Note that if there is more code than just a single macroScript in the file, only the last macroScript definition is taken; the other code is NOT executed, so you cannot include auxiliary global functions and other prep code in the file. These should be inside the body of the macroScript, as local data and functions.
Parameters:
TCHAR* filename
The filename of the script.
Return Value:
TRUE if successfully compiled, otherwise FALSE.
Prototype:
BOOL RunDropScriptDragEnter(FPParams* params);
Remarks:
This methods takes care of the ‘on droppable’ handler in the current_dropscript, if supplied. If the handler returns false, the not-droppable cursor is shown.
Parameters:
FPParams* params
The set of arguments for the handler.
Return Value:
TRUE if droppable script will be accepted, otherwise FALSE.
Prototype:
BOOL RunDropScriptDragOver(FPParams* params);
Remarks:
This methods takes care of the ‘on droppable’ handler in the current_dropscript, if supplied, during the process of dragging contents over the drop target. If the handler returns false, the not-droppable cursor is shown.
Parameters:
FPParams* params
The set of arguments for the handler.
Return Value:
TRUE if droppable script will be accepted, otherwise FALSE.
Prototype:
BOOL RunDropScriptDrop(FPParams* params);
Remarks:
This methods takes care of the ‘on droppable’ handler in the current_dropscript, if supplied and handles the parsing of the dropped script. If the handler returns false, the not-droppable cursor is shown.
Parameters:
FPParams* params
The set of arguments for the handler.
Return Value:
TRUE if droppable script will be accepted, otherwise FALSE.
Prototype:
void InitDragDropCheck(MacroEntry* dropscript, LPARAM mousePt, WPARAM keyState, HWND hwnd);
Remarks:
This method will initialize a drag and drop check.
Parameters:
MacroEntry* dropscript
The drop script macro entry.
LPARAM mousePt
The initial mouse cursor position.
WPARAM keyState
They initial state of the keyboard.
HWND hwnd
The handle to the initial start window.
Prototype:
bool ReadyToDrag();
Remarks:
This method returns TRUE if the system is ready to drag, otherwise FALSE.
Default Implementation:
{ return current_dropscript != NULL; }