Class ClassDesc
See Also: Class ClassDesc2, Class IParamBlock2, Class ParamBlockDesc2, Class ILoad, Class ISave, Class Interface, Class Class_ID.
class ClassDesc
Description:
Class descriptors provide the system with information about the plug-in classes in the DLL. The developer creates a class descriptor by deriving a class from ClassDesc and implementing several of its methods.
In release 3.0 and later there are new methods which are supplied and implemented by ClassDesc2. These methods relate to the parameter block2 system.
In release 4.0 plug-ins wishing to use the new Function Publishing system must use ClassDesc2 rather than this class for their class descriptors. See Function Publishing System.
Methods Groups:
The hyperlinks below take you to the start of groups of related methods within the class:
ClassID / SuperClassID / ClassName, Category Methods
Class Parameter Related Methods
Function Publishing Related Methods
Schematic View Related Methods
Methods:
Prototype:
virtual int IsPublic()=0;
Remarks:
Implemented by the Plug-In.
Controls if the plug-in shows up in lists from the user to choose from.
Return Value:
If the plug-in can be picked and assigned by the user, as is usually the case, return TRUE. Certain plug-ins may be used privately by other plug-ins implemented in the same DLL and should not appear in lists for user to choose from. These plug-ins would return FALSE.
Prototype:
virtual void *Create(BOOL loading=FALSE)=0;
Remarks:
Implemented by the Plug-In.
3ds max calls this method when it needs a pointer to a new instance of the plug-in class. For example, if 3ds max is loading a file from disk containing a previously used plug-in (procedural object, modifier, controller, etc...), it will call the plug-in's Create() method. The plug-in responds by allocating a new instance of its plug-in class. See the Advanced Topic section on Memory Allocation for more details.
Parameters:
BOOL loading=FALSE
This parameter is a flag indicating if the class being created is going to be loaded from a disk file. If the flag is TRUE, the plug-in may not have to perform any initialization of the object because the loading process will take care of it. See the Advanced Topics section on Loading and Saving for more information.
Note: If this parameter is TRUE, developers must initialize their references to NULL. Otherwise 3ds max may crash.
3ds max provides a default plug-in object creation process. Many plug-ins fit this form. When the system is about to create an instance of the plug-in object it calls a method BaseObject::GetCreateMouseCallBack().This method returns a callback object whose proc() method handles the mouse input during its creation phase. Most of the work is then handled by the system. The procedural sphere is an example of this type of plug-in. Certain plug-ins may have special creation needs however. The target camera is an example of such a plug-in. Because it needs to create two nodes in the scene (the camera and the target) it requires a custom creation process. To support these plug-ins the following two methods are provided. They allow the plug-in to manage the creation process themselves. See the Advanced Topics section on Object Creation Methods for more details.
Prototype:
virtual int BeginCreate(Interface *i)
Remarks:
Implemented by the Plug-In.
The custom creation process of the plug-in object is handled by this method. For example, a plug-in can create a custom command mode and push it on the command stack to handle the creation process.
Important Note: A plug-in that doesn't want to participate in the standard object creation mechanism using CreateMouseCallBack must push a CommandMode on the stack in this method and remove it in EndCreate(). This is true even if the plug-in doesn't do anything inside the mode. A mode has to be pushed on the stack and then later popped off otherwise a crash will occur (if the default implementation of this method is not used). For more details on object creation see the Advanced Topics section Object Creation Methods.
Parameters:
Interface *i
An interface pointer the plug-in may use to call functions in 3ds max.
Return Value:
To use the default creation process (the system implementation for this method) return 0; Return nonzero if the plug-in implements this method.
Default Implementation:
{ return 0; }
Prototype:
virtual int EndCreate(Interface *i)
Remarks:
Implemented by the Plug-In.
The termination of the custom creation process is managed by the implementation of this method. For example, the plug-in could remove a custom command mode from the command stack. See the Advanced Topics section on Object Creation Methods for more details.
Parameters:
Interface *i
An interface pointer the plug-in may use to call functions in 3ds max.
Return Value:
To use the system implementation for this method return 0; Return nonzero if the plug-in implements this method.
Default Implementation:
{ return 0; }
Prototype:
virtual BOOL OkToCreate(Interface *i)
Remarks:
Implemented by the Plug-In.
This method is used to enable or disable the button that allows the plug-ins class to be created. For example, at certain times it is not appropriate to for the Boolean object to be created. When there is not an object of the appropriate type selected the Boolean object cannot be created. At these times the button should be disabled (the button will appear as grayed out in the Create branch of the command panel). The button should be enabled if there is an object of the appropriate type selected. This method allows a plug-in to control the state of the button.
Parameters:
Interface *i
An interface pointer the plug-in may use to call functions in 3ds max.
Return Value:
TRUE to enable the class creation button; FALSE to disable it.
Default Implementation:
{ return TRUE; }
Sample Code:
The following code from \MAXSDK\SAMPLES\OBJECTS\BOOLOBJ.CPP demonstrates an implementation of this method. If there is not a node selected, it is not OK to use the command so the button should appear disabled. To disable the button OkToCreate() returns FALSE. If the object that is selected is not of the appropriate type it the button is disabled as well.
BOOL BoolObjClassDesc::OkToCreate(Interface *i)
{
if (i->GetSelNodeCount()!=1) return FALSE;
ObjectState os = i->GetSelNode(0)->GetObjectRef()->Eval(i->GetTime());
if (os.obj->SuperClassID()!=GEOMOBJECT_CLASS_ID) {
return FALSE;
}
return TRUE;
}
ClassName, ClassID, SuperClass ID, Category Methods
Prototype:
virtual const TCHAR* ClassName()=0;
Remarks:
Implemented by the Plug-In.
This method returns the name of the class. This name appears in the button for the plug-in in the 3ds max user interface.
Return Value:
The name of the class.
Prototype:
virtual SClass_ID SuperClassID()=0;
Remarks:
Implemented by the Plug-In.
This method returns a system defined constant describing the class this plug-in class was derived from. For example, the Bend modifier returns OSM_CLASS_ID. This super class ID is used by all object space modifiers. See List of SuperClassIDs.
Return Value:
The SuperClassID of the plug-in.
Prototype:
virtual Class_ID ClassID()=0;
Remarks:
Implemented by the Plug-In.
This method must return the unique ID for the object. If two ClassIDs conflict, the system will only load the first one it finds. The ClassID consists of two unsigned 32-bit quantities. The constructor assigns a value to each of these, for example Class_ID(0xA1C8E1D1, 0xE7AA2BE5). A developer should use the random Class_ID generator to avoid conflicts (Generate a random Class_ID). See Class Class_ID for more information.
Return Value:
The unique ClassID of the plug-in.
Prototype:
virtual Class_ID SubClassID();
Remarks:
This method is available in release 4.0 and later only.
Implemented by the Plug-In.
This method can be used for further categorizing plugin's. If a plugin has sub-plugins(like light > shadows, particles > operators), this method can be used to differentiate them. sub-plugins can be derived off reference target but return a particular class ID published by the parent plugins SDK headers. Then parent plugin can get a list of all reference targets whose SubClassID matches the published SubClassID
Default Implementation:
{ return Class_ID(); }
Prototype:
virtual const TCHAR* Category()=0;
Remarks:
Implemented by the Plug-In.
This methods returns a string describing the category a plug-in fits into. The category is usually selected in the drop down list in the create, or utility branch of the command panel. In the create branch, if this is set to be an existing category (i.e. "Standard Primitives", "Splines", ...) then the plug-in will appear in that category. If the category doesn't yet exists then it is created. If the plug-in does not need to appear in the list, it may simply return a null string as in _T("").
In the modify branch, the category determines which group it appears in the Configure Button Sets / Modifiers list. These are the categories such as "MAX STANDARD", "MAX EDIT", and "MAX SURFACE".
This method is also used to distinguish between the various types of texture maps so they can be separated in the Material/Map Browser. The appropriate string should be returned by this method of the Texmap. For example:
const TCHAR* Category() { return TEXMAP_CAT_3D; }
The options for texture maps are:
TCHAR TEXMAP_CAT_2D[]; - 2D maps.
TCHAR TEXMAP_CAT_3D[]; - 3D maps.
TCHAR TEXMAP_CAT_COMP[]; - Composite.
TCHAR TEXMAP_CAT_COLMOD[]; - Color modifier.
TCHAR TEXMAP_CAT_ENV[]; - Environment.
Class Parameter Related Methods
The following three methods deal with default settings for plug-in classes. Most plug-in do not need to be concerned with these methods.
In the 3ds max user interface, from the Files / Preferences... menu on the Animation page there is an option for Controller Defaults. There are buttons for 'Set Defaults...' and 'Restore to Factory Settings...'. When the user presses the 'Set Defaults...' button the user is presented with a list of plug-ins that have responded TRUE to the HasClassParams() method. These plug-ins have default parameters that the user can edit. These are the defaults used when a new instance of the plug-in class is created. When the user picks an item from the list, its EditClassParams() method is called to allow the plug-in to put up a modal dialog to let the user edit the default parameters. If the user presses the 'Reset to Factory Defaults...' button, the ResetClassParams() method is called. The plug-in can then be reset to use any default settings that it has.
Prototype:
virtual BOOL HasClassParams()
Remarks:
Implemented by the Plug-In.
If a plug-in class has default parameters that it needs to allow the user to edit, TRUE should be returned and EditClassParams() and ResetClassParams() should be implemented. Otherwise return FALSE (the default). See the description above.
Default Implementation:
{return FALSE;}
Prototype:
virtual void EditClassParams(HWND hParent);
Remarks:
Implemented by the Plug-In.
If the user picks the class from the list this method is called. The plug-in should put up a modal dialog that allows the user to edit the plug-ins default parameters. The plug-in should not return until the user has finished editing the parameters. See the description above.
Parameters:
HWND hParent
The parent window handle.
Prototype:
virtual void ResetClassParams(BOOL fileReset=FALSE);
Remarks:
Implemented by the Plug-In.
When the user executes File / Reset or presses the 'Reset to Factory Settings...' button in the File / Preferences... / Animation tab / Controller Defaults section this method is called. The plug-in can respond by resetting itself to use its default values. See the description above.
Parameters:
BOOL fileReset=FALSE
When TRUE, the user has performed a File / Reset operation. When FALSE, the user is in the Preferences... dialog doing a reset controller defaults operation.
These two functions return keyboard action tables that plug-ins can use
Prototype:
virtual int NumActionTables();
Remarks:
This method is available in release 4.0 and later only.
This method is called at Dll-load time to get the number of action tables from a plug-in. Note: If more than one class uses the table only one of the classes should export the table, but they can all use them. See Class ActionTable.
Default Implementation:
{ return 0; }
Prototype:
virtual ActionTable* GetActionTable(int i);
Remarks:
This method is available in release 4.0 and later only.
Returns a pointer to the 'i-th' action table. See Class ActionTable.
Parameters:
int i
The zero based index of the table to return.
Default Implementation:
{ return NULL; }
The following methods support manipulators. These methods are called on the class descriptors of manipulators when manipulate mode is entered, or when selection changes while in manipulate mode.
Prototype:
virtual BOOL UseSelectionBrackets();
Remarks:
This method is available in release 4.0 and later only.
This method allows an object to choose whether or not it will display selection brackets in shaded viewports. The method will return FALSE if no selection brackets are displayed or TRUE if it does display selection brackets.
Default Implementation:
{ return TRUE; }
Prototype:
virtual BOOL IsManipulator();
Remarks:
This method is available in release 4.0 and later only.
This methods is what is used by the system to determine whether the ClassDesc describes a manipulator. Returns TRUE if the class implements a manipulator object; otherwise FALSE.
Default Implementation:
{ return FALSE; }
Prototype:
virtual BOOL CanManipulate(ReferenceTarget* hTarget);
Remarks:
This method is available in release 4.0 and later only.
The method returns true if the class is a manipulator and it manipulates the given base object, modifier or controller. When starting "Manipulate" mode, this is called on selected nodes for the base object, all modifiers, the TM controller and the position, rotation and scale controllers, if the TM controller is a PRSController.
Parameters:
ReferenceTarget* hTarget
A pointer to a reference target.
Default Implementation:
{ return FALSE; }
Prototype:
virtual BOOL CanManipulateNode(INode* pNode);
Remarks:
This method is available in release 4.0 and later only.
Returns TRUE if the manipulator applies to the given node; otherwise FALSE. This is a general case if CanManipulateClassID() isn't sufficient.
Parameters:
INode* pNode
The node to check.
Default Implementation:
{ return FALSE; }
Prototype:
virtual void* CreateObjectManipulator(Object* pObject);
Remarks:
This method is available in release 4.0 and later only.
When a manipulator returns TRUE to CanManipulateClassID(), the system calls this method to create an instance and return a pointer to it.
Parameters:
Object* pObject
Points to the Object that the manipulator said it could manipulate.
Default Implementation:
{return NULL;}
Prototype:
virtual void* CreateTMControlManipulator(Control* pControl);
Remarks:
This method is available in release 4.0 and later only.
When a manipulator returns TRUE to CanManipulateClassID(), the system calls this method to create an instance and return a pointer to it.
Parameters:
Control* pControl
Points to the Controller that the manipulator said it could manipulate.
Default Implementation:
{return NULL;}
Prototype:
virtual void* CreateModifierManipulator(Modifier* pModifier);
Remarks:
This method is available in release 4.0 and later only.
When a manipulator returns TRUE to CanManipulateClassID(), the system calls this method to create an instance and return a pointer to it.
Parameters:
Modifier* pModifier
Points to the Modifier that the manipulator said it could manipulate.
Default Implementation:
{return NULL;}
Prototype:
virtual void* CreateManipulator(ReferenceTarget* hTarget, INode* pNode);
Remarks:
This method is available in release 4.0 and later only.
When a manipulator returns TRUE to CanManipulateNode(INode*), the system calls this version of CreateManipulator() to create an instance.
Parameters:
ReferenceTarget* hTarget
Points to the reference target.
INode* pNode
Points to the node that the manipulator said it could manipulate.
Return Value:
{ return NULL; }
Load / Save Related Methods
The following three methods may be used to save data associated with a class in a 3ds max file. If you want to save data associated with the class have NeedsToSave() return TRUE and implement the Save() and Load() methods.
Prototype:
virtual BOOL NeedsToSave();
Remarks:
Implemented by the Plug-In.
Returns TRUE if there is data associated with the class that needs to be saved in the 3ds max file. If this is so, implement the Save() and Load() methods below. If there is no class data to save return FALSE.
Default Implementation:
{ return FALSE; }
Prototype:
virtual IOResult Save(ISave *is);
Remarks:
Implemented by the Plug-In.
If NeedsToSave() returns TRUE then this method should be implemented to save the data associated with the class.
Parameters:
ISave *is
A pointer that may be used to call methods to save data to disk.
Return Value:
IO_OK if the save was successful; otherwise IO_ERROR.
Prototype:
virtual IOResult Load(ILoad *il);
Remarks:
Implemented by the Plug-In.
If NeedsToSave() returns TRUE then this method should be implemented to load the data associated with the class.
Parameters:
ILoad *il
A pointer that may be used to load data from a file.
Return Value:
IO_OK if the load was successful; otherwise IO_ERROR.
Parameter Map 2 Related Methods
Prototype:
virtual DWORD InitialRollupPageState();
Remarks:
This method is available in release 3.0 and later only.
This method returns a DWORD which is used to initialize the rollup state in both the create branch and the modify branch. The semantics are different, however for these two cases. Whenever the rollups are created in the create branch, their state will be that specified by this method. In the modify branch, the first time an object of this type is modified the state will be that of this method, but after that it will remain what it was last set to.
Return Value:
The bits of this DWORD set indicate the corrresponding rollup page is closed. The zero bit corresponds to the plug-ins first rollup, the first bit is the second rollup, etc. The value 0x7fffffff is returned by the default implementation so the command panel can detect this method is not being overridden, and just leave the rollups as is.
Default Implementation:
{ return 0x7fffffff; }
Prototype:
virtual const TCHAR* InternalName();
Remarks:
This method is available in release 3.0 and later only.
Implemented by the Plug-In.
Returns a string which provides a fixed, machine parsable internal name for the plug-in. This name is used by MAXScript.
Default Implementation:
{ return NULL; }
Prototype:
virtual HINSTANCE HInstance();
Remarks:
This method is available in release 3.0 and later only.
Implemented by the Plug-In.
Returns the DLL instance handle of the plug-in. This is used so that string resources can be loaded by the ParamBlock2 system.
Default Implementation:
{ return NULL; }
Prototype:
virtual int NumParamBlockDescs();
Remarks:
This method is available in release 3.0 and later only.
Implemented by the System.
Returns the number or ParamBlockDesc2s used by the plug-in.
Default Implementation:
{ return 0; }
Prototype:
virtual ParamBlockDesc2* GetParamBlockDesc(int i);
Remarks:
This method is available in release 3.0 and later only.
Implemented by the System.
Returns a pointer to the 'i-th' parameter block 2 descriptor.
Parameters:
int i
The zero based index of the descriptor to return.
Default Implementation:
{ return NULL; }
Prototype:
virtual ParamBlockDesc2* GetParamBlockDescByID(BlockID id);
Remarks:
This method is available in release 3.0 and later only.
Implemented by the System.
Returns a pointer to the specified parameter block 2 descriptor.
Parameters:
BlockID id
The ID of the parameter block.
Default Implementation:
{ return NULL; }
Prototype:
virtual void AddParamBlockDesc(ParamBlockDesc2* pbd);
Remarks:
This method is available in release 3.0 and later only.
Implemented by the System.
Adds the specified parameter block 2 descriptor to the list of those maintained by the class.
Parameters:
ParamBlockDesc2* pbd
Points to the parameter block 2 descriptor to add.
Default Implementation:
{ }
Prototype:
virtual void BeginEditParams(IObjParam *ip, ReferenceMaker* obj, ULONG flags, Animatable *prev);
Remarks:
This method is available in release 3.0 and later only.
Implemented by the System.
This method is called to handle the beginning of the automatic command panel user interface management provided by the param map 2 system. This method is called by the plug-in from its Animatable::BeginEditParams() method. The parameters passed to that method are simply passed along to this method.
Parameters:
IObjParam *ip
The interface pointer passed to the plug-in.
ReferenceMaker* obj
Points to the plug-in class calling this method.
ULONG flags
The flags passed along to the plug-in in Animatable::BeginEditParams().
Animatable *prev
The pointer passed to the plug-in in Animatable::BeginEditParams().
Default Implementation:
{ }
Prototype:
virtual void EndEditParams(IObjParam *ip, ReferenceMaker* obj, ULONG flags, Animatable *prev);
Remarks:
This method is available in release 3.0 and later only.
Implemented by the System.
This method is called to handle the ending of the automatic command panel user interface management provided by the param map 2 system. This method is called by the plug-in from its Animatable::EndEditParams() method. The parameters passed to that method are simply passed along to this method.
Parameters:
IObjParam *ip
The interface pointer passed to the plug-in.
ReferenceMaker* obj
Points to the plug-in class calling this method.
ULONG flags
The flags passed along to the plug-in in Animatable::EndEditParams().
Animatable *prev
The pointer passed to the plug-in in Animatable::EndEditParams().
Default Implementation:
{ }
Prototype:
virtual void InvalidateUI(ParamBlockDesc2* pbd);
Remarks:
This method is available in release 3.0 and later only.
Implemented by the System.
Invalidates the user interface for the rollup or dialog managed by the specified descriptor. This will cause the controls in that rollup to be redrawn.
Parameters:
ParamBlockDesc2* pbd
Points to the parameter block 2 descriptor whose corresponding UI is invalidated.
Default Implementation:
{ }
Prototype:
virtual void MakeAutoParamBlocks(ReferenceMaker* owner);
Remarks:
This method is available in release 3.0 and later only.
Implemented by the System.
This method creates the automatic parameter blocks for the specified plug-in. These are the ones with the ParamBlockDesc2.flags P_AUTO_CONSTRUCT bit set.
Parameters:
ReferenceMaker* owner
Points to the owner of the parameter block.
Default Implementation:
{ }
Prototype:
virtual int NumParamMaps();
Remarks:
This method is available in release 3.0 and later only.
Implemented by the System.
Returns the number of parameter map2s used by the plug-in.
Default Implementation:
{ return 0; }
Prototype:
virtual IParamMap2* GetParamMap(int i);
Remarks:
This method is available in release 3.0 and later only.
Implemented by the System.
Returns a pointer to the 'i-th' parameter map2.
Parameters:
int i
The zero based index of the parameter map2 to return.
Default Implementation:
{ return NULL; }
Prototype:
virtual IParamMap2* GetParamMap(ParamBlockDesc2* pbd);
Remarks:
This method is available in release 3.0 and later only.
Implemented by the System.
Returns a pointer to the parameter map2 whose descriptor is passed.
Parameters:
ParamBlockDesc2* pbd
Points to the parameter block2 descriptor.
Default Implementation:
{ return NULL; }
Prototype:
virtual void SetUserDlgProc(ParamBlockDesc2* pbd, ParamMap2UserDlgProc* proc=NULL);
Remarks:
This method is available in release 3.0 and later only.
Implemented by the System.
Sets the parameter map 2 user dialog proc for the specified descriptor.
Parameters:
ParamBlockDesc2* pbd
Points to the parameter block 2 descriptor.
ParamMap2UserDlgProc* proc=NULL
This object manages user interface control that require special processing. See Class ParamMap2UserDlgProc.
Default Implementation:
{ }
Prototype:
virtual ParamMap2UserDlgProc* GetUserDlgProc(ParamBlockDesc2* pbd);
Remarks:
This method is available in release 3.0 and later only.
Implemented by the System.
Returns a pointer to the parameter map 2 user dialog proc (if any) for the specified descriptor.
Parameters:
ParamBlockDesc2* pbd
Points to the parameter block 2 descriptor.
Return Value:
See Class ParamMap2UserDlgProc.
Default Implementation:
{ return NULL; }
Function Publishing Related Methods
Prototype:
virtual int NumInterfaces();
Remarks:
This method is available in release 4.0 and later only.
Implemented by the System.
Returns the number of function publishing interfaces maintained by the class descriptor.
Prototype:
virtual FPInterface* GetInterface(int i);
Remarks:
This method is available in release 4.0 and later only.
Implemented by the System.
Returns a pointer to the 'i-th' function publishing interface.
Parameters:
int i
The zero based index of the interface to return.
Prototype:
virtual FPInterface* GetInterface(Interface_ID id);
Remarks:
This method is available in release 4.0 and later only.
Returns a pointer to the function publishing interface whose ID is specified.
Parameters:
Interface_ID id
The inteface ID.
Prototype:
virtual FPInterface* GetInterface(TCHAR* name);
Remarks:
This method is available in release 4.0 and later only.
Returns a pointer to the function publishing interface whose name is specified.
Parameters:
TCHAR* name
The name of the interface.
Prototype:
virtual void AddInterface(FPInterface* fpi);
Remarks:
This method is available in release 4.0 and later only.
Adds the specified interface to the list maintained by this class descriptor.
Parameters:
FPInterface* fpi
Points to the interface to add.
Prototype:
virtual void ClearInterfaces();
Remarks:
This method is available in release 4.0 and later only.
Deletes all the interfaces maintained by the class descriptor.
Schematic View Related Methods
Prototype:
virtual bool DrawRepresentation(COLORREF bkColor, HDC hDC, Rect &rect);
Remarks:
This method is available in release 3.0 and later only.
This method allows this plug-in class to provide a custom image for display in Schematic View.
Parameters:
COLORREF bkColor
The background color. See COLORREF-DWORD format.
HDC hDC
The handle for the device context.
Rect &rect
The rectangle to draw in.
Return Value:
TRUE if this class can draw an image to represent itself graphically; otherwise FALSE.
Default Implementation:
{ return FALSE; }
Prototype:
virtual INT_PTR Execute(int cmd, ULONG arg1=0, ULONG arg2=0, ULONG arg3=0);
Remarks:
This method is available in release 3.0 and later only.
This is a general purpose function that allows the API to be extended in the future. The 3ds max development team can assign new cmd numbers and continue to add functionality to this class without having to 'break' the API.
This is reserved for future use.
Parameters:
int cmd
The command to execute.
ULONG arg1=0
Optional argument 1 (defined uniquely for each cmd).
ULONG arg2=0
Optional argument 2.
ULONG arg3=0
Optional argument 3.
Return Value:
An integer return value (defined uniquely for each cmd).
Default Implementation:
{ return 0; }