Detailed Description

This class provides functions for registering a PluginItem in Softimage.

PluginRegistrar instances are created by Softimage and contain information such as the directory where the plug-in is being loaded/unloaded along with the filename of the plug-in. When Softimage starts up, a PluginRegistrar object is created for each plug-in to load and passed to the cb_XSILoadPlugin XSILoadPlugin function entry point exposed by the plug-in. The information gathered by Softimage is used for creating each PluginItem when required by the Softimage user. When a plug-in is unloaded, a PluginRegistrar object is created for this particular plug-in and passed to the optional cb_XSIUnloadPlugin XSIUnloadPlugin function entry point exposed by the plug-in. The information registered by the plug-in can be accessed through the Plugin class.

Since:: 4.0

Example:: Sample cb_XSILoadPlugin registration callback for a filter and a command

        XSI::CStatus XSILoadPlugin( XSI::PluginRegistrar& io_reg )
        {
            io_reg.PutAuthor( L"XYZ" );
            io_reg.PutName( L"XYZ simple plugin" );
            io_reg.PutVersion( 1, 0 );

            io_reg.RegisterFilter( L"Simple Command Filter", siFilterObject );
            io_reg.RegisterCommand( L"Simple Command", L"SimpleCommand );

            return XSI::CStatus::OK;
        }

#include <xsi_pluginregistrar.h>

Inheritance diagram for PluginRegistrar:

[legend]

List of all members.

Public Member Functions
	PluginRegistrar ()
	~PluginRegistrar ()
	PluginRegistrar (const CRef &in_ref)
	PluginRegistrar (const PluginRegistrar &in_obj)
bool	IsA (siClassID in_ClassID) const
siClassID	GetClassID () const
PluginRegistrar &	operator= (const PluginRegistrar &in_obj)
PluginRegistrar &	operator= (const CRef &in_ref)
PluginItem	RegisterFilter (const CString &in_strName, siFilterType in_type)
PluginItem	RegisterCustomDisplay (const CString &in_strName)
PluginItem	RegisterProperty (const CString &in_strName)
PluginItem	RegisterDisplayCallback (const CString &in_strName)
PluginItem	RegisterDisplayPass (const CString &in_strName)
PluginItem	RegisterMenu (siMenuAnchorPoints in_anchorID, const CString &in_menuName, bool in_bDisplayAsSubmenu=true, bool in_bDynamicMenu=true)
PluginItem	RegisterCommand (const CString &in_commandScriptName)
PluginItem	RegisterCommand (const CString &in_commandName, const CString &in_commandScriptName)
PluginItem	RegisterEvent (const CString &in_eventName, const siEventID in_eventID)
PluginItem	RegisterTimerEvent (const CString &in_eventName, LONG in_nInterval, LONG in_nDelay=0)
PluginItem	RegisterConverterEvent (const CString &in_eventName, const siEventID in_eventID, const CString &in_eventExtension)
PluginItem	RegisterOperator (const CString &in_name)
PluginItem	RegisterRenderer (const CString &in_name)
PluginItem	RegisterICENode (const ICENodeDef &in_nodedef)
PluginItem	RegisterPrimitive (const CString &in_name)
PluginItem	RegisterShaderLanguageParser (const CString &in_strParserName)
PluginItem	RegisterShader (const CString &in_strShaderClassName, ULONG in_ulMajorVersion, ULONG in_ulMinorVersion)
PluginItem	RegisterTool (const CString &in_name)
CString	GetAuthor () const
CString	GetURL () const
CString	GetEmail () const
CStatus	GetVersion (LONG &out_major, LONG &out_minor) const
CString	GetLanguage () const
CString	GetFilename () const
CStatus	PutAuthor (const CString &in_strName)
CStatus	PutURL (const CString &in_strURL)
CStatus	PutEmail (const CString &in_strEmail)
CStatus	PutVersion (LONG in_major, LONG in_minor)
CStatus	PutHelp (const CString &in_strHelp)
CStatus	PutCategories (const CString &in_strCat)
CStatus	PutUserData (const CValue &in_userdata)
CValue	GetUserData () const

Constructor & Destructor Documentation

PluginRegistrar ( )

Default constructor.

~PluginRegistrar ( )

Default destructor.

PluginRegistrar ( const CRef & in_ref )

Constructor.

Parameters:

in_ref constant reference object.

PluginRegistrar ( const PluginRegistrar & in_obj )

Copy constructor.

Parameters:

in_obj constant class object.

Member Function Documentation

bool IsA ( siClassID in_ClassID ) const [virtual]

Returns true if a given class type is compatible with this API class.

Parameters:

in_ClassID class type.

Returns:: true if the class is compatible, false otherwise.

Reimplemented from SIObject.

siClassID GetClassID ( ) const [virtual]

Returns the type of the API class.

Returns:: the class type.

Reimplemented from SIObject.

PluginRegistrar& operator= ( const PluginRegistrar & in_obj )

Creates an object from another object. The newly created object is set to empty if the input object is not compatible.

Parameters:

in_obj constant class object.

Returns:: New PluginRegistrar object.

PluginRegistrar& operator= ( const CRef & in_ref )

Creates an object from a reference object. The newly created object is set to empty if the input reference object is not compatible.

Parameters:

in_ref constant class object.

Returns:: New PluginRegistrar object.

Reimplemented from SIObject.

PluginItem RegisterFilter	(	const CString &	in_strName,
		siFilterType	in_type
	)

Registers a Filter.

Parameters:

in_strName The name of the custom filter.

The first character in a filter name must be a letter or an underscore (_). Subsequent characters can be letters, numbers, underscore (_) characters, or spaces.

The filter name is used to name the filter callback functions such as Match and Subset. For example, the Match callback for a filter named "My3DObjectFilter" is "My3DObjectFilter_Match". If a filter name contains spaces (for example, "My 3D Object Filter"), the callback function names must omit the spaces (for example, "My3DObjectFilter_Match").

The filter name also appears in the Softimage user interface, and is the name you use to reference the filter in scripting or C++ code. If the filter name contains spaces, you must replace the spaces with underscores to use the filter with commands or the object model.

in_type The type of filter to register.

Returns:: The PluginItem object for the filter.

PluginItem RegisterCustomDisplay ( const CString & in_strName )

Registers a custom display.

Parameters:

in_strName The name of the custom display.

The first character in a custom display name must be a letter or an underscore (_). Subsequent characters can be letters, numbers, underscore (_) characters, or spaces.

The custom display name is used to name the callback functions such as cb_CustomDisplay_Init Init and cb_CustomDisplay_Notify Notify . For example, the Notify callback for a custom display named "MyCustomDisplay" is "MyCustomDisplay_Notify". If the name contains spaces (for example, "My Custom Display"), the callback function names must omit the spaces (for example, "MyCustomDisplay_Notify").

Returns:: The PluginItem object for the custom display.

PluginItem RegisterProperty ( const CString & in_strName )

Registers a new type of CustomProperty. To create instances of this CustomProperty, use SceneItem::AddProperty.

Parameters:

in_strName The name of the property (actually, the name of the PluginItem object created for this property). Instances of the property have this name as their SIObject::Type.

The first character in a property name must be a letter or an underscore (_). Subsequent characters can be letters, numbers, underscore (_) characters, or spaces. If a property name contains spaces (for example, "My Custom Property"), the callback function names must omit the spaces (for example, "MyCustomProperty_DefineLayout").

Property names must be unique. To avoid naming conflicts, we recommend using a prefix based on your company name or the plug-in name.(for example, "ACME_TornadoKit_Configuration").

Returns:: The PluginItem object created for this property.

See also:: SceneItem::AddProperty, PPGLayout

Example:: Example of a C++ self-installing property. To try out this example, compile it and copy the DLL/SO to the Plugins folder of a workgroup. Then use the Plug-in Manager to load the plug-in (for example, by clicking Update All). To create an instance of the property, go to the Plug-in Tree, right-click the property, and choose Create Instance).

        #include <xsi_application.h>
        #include <xsi_context.h>
        #include <xsi_pluginregistrar.h>
        #include <xsi_status.h>
        #include <xsi_customproperty.h>
        #include <xsi_ppglayout.h>
        #include <xsi_ppgeventcontext.h>
        #include <xsi_selection.h>
        using namespace XSI;

        XSIPLUGINCALLBACK CStatus XSILoadPlugin( PluginRegistrar& in_reg )
        {
            in_reg.PutAuthor(L"Softimage SDK Team");
            in_reg.PutName(L"MySimplePropertyPlugin");
            in_reg.PutEmail(L"");
            in_reg.PutURL(L"");
            in_reg.PutVersion(1,0);
            in_reg.RegisterProperty(L"MySimpleProperty");
            //RegistrationInsertionPoint - do not remove this line

            return CStatus::OK;
        }

        XSIPLUGINCALLBACK CStatus XSIUnloadPlugin( const PluginRegistrar& in_reg )
        {
            CString strPluginName = in_reg.GetName();
            Application().LogMessage(strPluginName + L" has been unloaded.");
            return CStatus::OK;
        }

        XSIPLUGINCALLBACK CStatus MySimpleProperty_Define( CRef& in_ctxt )
        {
            Context ctxt( in_ctxt );
            CustomProperty oCustomProperty;
            Parameter oParam;
            oCustomProperty = ctxt.GetSource();
            oCustomProperty.AddParameter(L"U",CValue::siDouble,siPersistable,L"",L"",0l,0l,1l,0l,1l,oParam);
            oCustomProperty.AddParameter(L"V",CValue::siDouble,siPersistable,L"",L"",0l,0l,1l,0l,1l,oParam);
            oCustomProperty.AddParameter(L"LockUV",CValue::siBool,siPersistable,L"",L"",true,CValue(),CValue(),CValue(),CValue(),oParam);
            oCustomProperty.AddParameter(L"ShowInfo",CValue::siBool,siPersistable,L"",L"",true,CValue(),CValue(),CValue(),CValue(),oParam);

        // Some static text we will show optionally on the screen
            CString strInfo(L"This is a Softimage SDK example showing \r\n"
                              L"a Custom Property implemented as a \r\n"
                              L"self-installing plug-in.\r\n");

            oCustomProperty.AddParameter(L"InfoStatic",CValue::siString,siPersistable,L"",L"",L"",oParam);
            //oParam.PutCapabilityFlag( siNotInspectable, true ) ;
            oParam.PutValue( strInfo ) ;

            return CStatus::OK;
        }

        XSIPLUGINCALLBACK CStatus MySimpleProperty_DefineLayout( CRef& in_ctxt )
        {
            Context ctxt( in_ctxt );
            PPGLayout oLayout;
            PPGItem oItem;
            oLayout = ctxt.GetSource();
            oLayout.Clear();

            oLayout.AddGroup( L"Data" ) ;

            oLayout.AddRow() ;

            oItem = oLayout.AddItem(L"U");
            oItem.PutAttribute( siUIThumbWheel, true ) ;
            // The label is a single character, so to make sure it doesn't
            // get too much horizontal space, we set a small LabelPercentage
            // so that the MinPixels takes priority
            oItem.PutLabelPercentage(1);
            oItem.PutLabelMinPixels(20);

            oItem = oLayout.AddItem(L"V");
            oItem.SetAttribute( siUITreadmill, true ) ;
            oItem.PutLabelPercentage(1);
            oItem.PutLabelMinPixels(20);

            oLayout.EndRow() ;

            oLayout.AddItem(L"LockUV", L"Lock UV");

            oLayout.EndGroup();

            oLayout.AddGroup() ;

            // The InfoStatic is always in the layout,
            // but it is hidden if the siNotInspected
            // capability is set to False
            oItem = oLayout.AddItem( L"InfoStatic", L"", siControlStatic ) ;

            oLayout.AddItem( L"ShowInfo", L"Show Info" ) ;
            oLayout.EndGroup() ;

            oLayout.AddButton( L"Done" ) ;

            return CStatus::OK;
        }

        XSIPLUGINCALLBACK CStatus MySimpleProperty_PPGEvent( const CRef& in_ctxt )
        {
            // This callback is called when events happen in the user interface
            // This is where you implement the "logic" code.

            // If the value of a parameter changes but the UI is not shown then this
            // code will not execute.  Also this code is not re-entrant, so any changes
            // to parameters inside this code will not result in further calls to this function

            Application app ;

            // The context object is used to determine exactly what happened
            // We don't use the same "PPG" object that is used from Script-based logic code
            // but through the C++ API we can achieve exactly the same functionality.
            PPGEventContext ctxt( in_ctxt ) ;

            PPGEventContext::PPGEvent eventID = ctxt.GetEventID() ;

            if ( eventID == PPGEventContext::siOnInit )
            {
                // This event meant that the UI was just created.
                // It gives us a chance to set some parameter values.
                // We could even change the layout completely at this point.

                // For this event Source() of the event is the CustomProperty object

                CustomProperty prop = ctxt.GetSource() ;

                app.LogMessage( L"OnInit called for " + prop.GetFullName() ) ;

                // If you regenerate the layout then call this:
                ctxt.PutAttribute(L"Refresh",true);

            }
            else if ( eventID == PPGEventContext::siOnClosed )
            {
                // This event meant that the UI was just closed by the user.

                // For this event Source() of the event is the CustomProperty object

                CustomProperty prop = ctxt.GetSource() ;

                app.LogMessage( L"OnClosed called for " + prop.GetFullName() ) ;
            }
            else if ( eventID == PPGEventContext::siButtonClicked )
            {

                CustomProperty prop = ctxt.GetSource() ;

                // If there are multiple buttons
                // we can use this attribute to figure out which one was clicked.
                CValue scriptNameOfButton = ctxt.GetAttribute( L"Button" ) ;

                if ( scriptNameOfButton.GetAsText() == L"Done" )
                {
                    // See the scripting documentation for
                    // PPG.Close for more info about this
                    // technique.

                    // Self destruct the property page

                    CValueArray args( 1 ) ;
                    args[0] = prop ;
                    CValue retval ;
                    app.ExecuteCommand( L"DeleteObj", args, retval ) ;

                    // Tell the context that we want the
                    // the property page closed
                    ctxt.PutAttribute( L"Close", true ) ;
                }
                else
                {
                    // We only have a single button so this case is unexpected
                }
            }
            else if ( eventID == PPGEventContext::siTabChange )
            {
                // We will be called when the PPG is first opened
                // and every time the tab changes

                // Retrieve the label of the tab that is now active
                CValue tabLabel = ctxt.GetAttribute( L"Tab" ) ;

                app.LogMessage( L"Tab changed to: " + tabLabel .GetAsText() ) ;
            }
            else if ( eventID == PPGEventContext::siParameterChange )
            {
                // For this event the Source of the event is the parameter
                // itself
                Parameter changed = ctxt.GetSource() ;
                CustomProperty prop = changed.GetParent() ;

                if ( changed.GetName() == L"ShowInfo" )
                {
                    // Toggle the visibility of the static text
                    Parameter infoStatic = prop.GetParameters().GetItem( L"InfoStatic" ) ;
                    infoStatic.PutCapabilityFlag( siNotInspectable, changed.GetValue() == false ) ;

                    // It isn't strictly necessary to call this for
                    // simple cases of hiding and showing controls,
                    // but it ensures that the property page is fully
                    // redrawn and resized.
                    ctxt.PutAttribute( L"Refresh", true ) ;
                }
                else if ( changed.GetName() == L"U" )
                {
                    bool IsLocked = prop.GetParameterValue( L"LockUV" ) ;
                    if ( IsLocked )
                    {
                        // Note: Changing the value from
                        // within the logic code will not
                        // result in PPGEvent
                        // being called again.  So there is
                        // minimal risk of infinite loops.
                        prop.PutParameterValue( L"V", prop.GetParameterValue( L"U" ) );
                    }
                }
                else if ( changed.GetName() == L"V" )
                {
                    bool IsLocked = prop.GetParameterValue( L"LockUV" ) ;
                    if ( IsLocked )
                    {
                        prop.PutParameterValue( L"U", prop.GetParameterValue( L"V" ) );
                    }

                }
                else if ( changed.GetName() == L"LockUV" )
                {
                    bool IsLocked = prop.GetParameterValue( L"LockUV" ) ;
                    if ( IsLocked )
                    {
                        // When locking is enabled make sure
                        // that the two values snap to the same,
                        // value.

                        double avg = ( (double)prop.GetParameterValue( L"U" ) +
                                        (double)prop.GetParameterValue( L"V" ) ) / 2.0 ;

                        prop.PutParameterValue( L"U", avg );
                        prop.PutParameterValue( L"V", avg );
                    }
                }
            }

            return CStatus::OK ;
        }

PluginItem RegisterDisplayCallback ( const CString & in_strName )

Registers a Graphic Sequencer display callback.

Parameters:

in_strName The name of the display callback.

The first character in a display callback name must be a letter or an underscore (_). Subsequent characters can be letters, numbers, underscore (_) characters, or spaces.

The display callback name is used to name the callback functions such as cb_XGS_Init Init and cb_XGS_Execute Execute . For example, the Execute callback for a custom display named "MyDisplayPass" is "MyDisplayPass_Execute". If the name contains spaces (for example, "My Display Pass"), the callback function names must omit the spaces (for example, "MyDisplayPass_Execute").

Returns:: The PluginItem object for the display callback.

PluginItem RegisterDisplayPass ( const CString & in_strName )

Registers a Graphic Sequencer display pass.

Parameters:

in_strName The name of the display pass.

The first character in a display pass name must be a letter or an underscore (_). Subsequent characters can be letters, numbers, underscore (_) characters, or spaces.

The display pass name is used to name the callback functions such as cb_XGS_Init Init and cb_XGS_Execute Execute . For example, the Execute callback for a custom display named "MyDisplayCallback" is "MyDisplayCallback_Execute". If the name contains spaces (for example, "My Display Callback"), the callback function names must omit the spaces (for example, "MyDisplayCallback_Execute").

Returns:: The PluginItem object for the display pass.

PluginItem RegisterMenu	(	siMenuAnchorPoints	in_anchorID,
		const CString &	in_menuName,
		bool	in_bDisplayAsSubmenu = `true`,
		bool	in_bDynamicMenu = `true`
	)

Registers a custom Menu. The menu is loaded and initialized only when the user opens it from the UI. The location of a menu is specified by an anchor points (see siMenuAnchorPoints for a complete list). You can register the same menu at multiple locations, and multiple menus at the same location. A menu can be a submenu or a flat list of items. A menu can also be dynamic or static: a dynamic menu is rebuilt every time it is displayed, while a static menu is built once only.

See the Menu reference page for details about creating a custom menu.

Parameters:

in_anchorID	Specifies the location of the menu.
in_menuName	The name of the menu. The first character in a menu name must be a letter or an underscore (`_`). Subsequent characters can be letters, numbers, underscore (`_`) characters, or spaces. If a menu name contains spaces (for example, `"My Custom Menu"`), the names of the menu callback functions must omit the spaces (for example, `"MyCustomMenu_Init"`). If the menu is a submenu (`in_bDisplayAsSubmenu` `==` `true`), or if the menu is added to the top-level of the Softimage main menubar (`n_anchorID` `==` siMenuMainTopLevelID), then the menu name is used as the menu caption. You cannot change the caption of a top-level menu. For all other menus, you can change the caption by calling Menu::PutName in the cb_Menu_Init Init callback.
in_bDisplayAsSubmenu	Display the custom menu as a submenu.
in_bDynamicMenu	Sets the menu as dynamic or static: a dynamic menu is always rebuilt before the menu opens whereas static menus are only built once.

Returns:: The PluginItem object created for the menu.

PluginItem RegisterCommand ( const CString & in_commandScriptName )

Registers a regular custom Command in Softimage. The command will not register if a name clash occurs with another command. Using a consistent prefix or other naming convention can help avoid any conflicts with other commands. For example, "iy_Help" is less likely to be a duplicate than "Help".

Parameters:

in_commandScriptName The scripting name of the command.

To allow users to easily execute the command in scripts or in compiled code, the first character in the scripting name must be a letter. Subsequent characters can be letters, numbers, or underscore (_) characters.

Otherwise, if you use a scripting name like "123DoIt" or "Do It", the only way to execute the command is with Command::Execute and Application::ExecuteCommand. Note also that a scripting name like "_DoIt" will not work in VBScript, because VBScript does not allow the underscore as the first character in an identifier.

Returns:: The PluginItem object for the command.

Since:: 5.1

PluginItem RegisterCommand	(	const CString &	in_commandName,
		const CString &	in_commandScriptName
	)

Registers a custom Command in Softimage. This variation makes it possible to provide a different command name and command scripting name. This approach can cause some confusion and is no longer recommended. Instead it is better to set a descriptive label on the menu or toolbar itself.

Parameters:

in_commandName The name of the custom command. The first character in a command name must be a letter or an underscore (_). Subsequent characters can be letters, numbers, underscore (_) characters, or spaces.

The command name is used to name the command callback functions such as cb_Command_Execute Execute and cb_Command_Init Init . For example, the Execute callback for a command named "MyCommand" is "MyCommand_Execute". If a command name contains spaces (for example, "My Simple Command"), then you remove the spaces in the callback function names (for example, "MySimpleCommand_Init" and "MySimpleCommand_Execute").

The command name also appears in the Softimage user interface, and is the name of the command in the CommandArray returned by Application::GetCommands. It is also the name you use when you call Menu::AddCommandItem.

Command names must be unique. To avoid naming conflicts, we recommend using a prefix based on your company name or the plug-in name (for example, "ACME_TornadoKit_Apply").

in_commandScriptName The scripting name of the command.

To allow users to easily execute the command in scripts or in compiled code, the first character in the scripting name must be a letter. Subsequent characters can be letters, numbers, or underscore (_) characters.

Otherwise, if you use a scripting name like "123DoIt" or "Do It", the only way to execute the command is with Command::Execute and Application::ExecuteCommand. Note also that a scripting name like "_DoIt" will not work in VBScript, because VBScript does not allow the underscore as the first character in an identifier.

Returns:: The PluginItem object for the command.

PluginItem RegisterEvent	(	const CString &	in_eventName,
		const siEventID	in_eventID
	)

Registers a custom Event.

Parameters:

in_eventName The name of the event.

The first character in an event name must be a letter or an underscore (_). Subsequent characters can be letters, numbers, underscore (_) characters, or spaces.

The event name is used to name the cb_Event_OnEvent OnEvent callback function. For example, the OnEvent callback for an event named "MySelectionChange" is "MySelectionChange_OnEvent". If an event name contains spaces (for example, "My Selection Change"), the OnEvent callback function name must omit the spaces (for example, "MySelectionChange_OnEvent").

This name is also the name of the event in the array returned by Application::GetEventInfos.

in_eventID Type of event to register.

Note:: The following identifiers are valid but not supported: siOnWindowEvent, siOnTimer.

Returns:: Newly created event PluginItem object.

Since:: 5.0

PluginItem RegisterTimerEvent	(	const CString &	in_eventName,
		LONG	in_nInterval,
		LONG	in_nDelay = `0`
	)

Registers a TimerEvent. A TimerEvent invokes an event callback at specific timed intervals. You can also specify the delay time at which the event callback is called for the first time. This function doesn't require an event type argument as the event created is of type siOnTimer.

Parameters:

in_eventName	The name of the event. The first character in an event name must be a letter or an underscore (`_`). Subsequent characters can be letters, numbers, underscore (`_`) characters, or spaces. The event name is used to name the cb_Event_OnEvent OnEvent callback function. For example, the `OnEvent` callback for an event named `"MyTimer"` is `"MyTimer_OnEvent"`. If an event name contains spaces (for example, `"My timer Change"`), the OnEvent callback function name must omit the spaces (for example, `"MyTimer_OnEvent"`). This name is also the name of the event in the array returned by Application::GetEventInfos.
in_nInterval	The interval time value in milliseconds. This value specifies the amount of time to wait between each callback invocation. If the value is 0, the event timer is stopped (muted) after the first invocation. The timer can be restarted again by un-muting the event. If the value > 0, the timer will elapse indefinitely.
in_nDelay	The delay value, in milliseconds, is the amount of time to wait until the callback is first invoked. By default, the delay time is 0 and the timer starts immediately.

Returns:: Newly created timer event PluginItem object.

See also:: EventInfo::PutMute, siOnTimer

Since:: 5.1

PluginItem RegisterConverterEvent	(	const CString &	in_eventName,
		const siEventID	in_eventID,
		const CString &	in_eventExtension
	)

Registers a ConverterEvent. A ConverterEvent's callback is invoked whenever a file using a custom-defined file type has to be imported or exported.

Parameters:

in_eventName	The name of the event. The first character in an event name must be a letter or an underscore (`_`). Subsequent characters can be letters, numbers, underscore (_) characters, or spaces. The event name is used to name the cb_Event_OnEvent OnEvent callback function. For example, the `OnEvent` callback for an event named `"MyConverter"` is `"MyConverter_OnEvent"`. If an event name contains spaces (for example, `"My Converter"`), the OnEvent callback function name must omit the spaces (for example, `"MyConverter_OnEvent"`). This name is also the name of the event in the array returned by Application::GetEventInfos.
in_eventID	Type of event to register. Allowed IDs are siOnCustomFileImport and siOnCustomFileExport.
in_eventExtension	The file Extension to register the converter event for. The Extension should not contain any delimiters and be uppercase, so `"TXT"` for example is the extension for a file like `"myfile.txt"`.

Returns:: Newly created converter event PluginItem object.

See also:: PPGEventContext

Since:: 6.0

PluginItem RegisterOperator ( const CString & in_name )

Registers a custom Operator as a PluginItem object.

Parameters:

in_name User-defined name of the operator to register.

The first character in an operator name must be a letter or an underscore (_). Subsequent characters can be letters, numbers, underscore (_) characters, or spaces.

The operator name is used to name the operator callback functions. For example, the cb_Operator_Update Update callback for an operator named "Shake" is "Shake_Update". If an operator name contains spaces (for example, "Shake And Roll"), the Update callback function name must omit the spaces (for example, "ShakeAndRoll_Update").

Returns:: Newly created custom operator PluginItem object.

Since:: 5.1

PluginItem RegisterRenderer ( const CString & in_name )

Registers a custom Renderer as a PluginItem object.

Parameters:

in_name User-defined name of the renderer to register.

The first character in an renderer name must be a letter or an underscore (_). Subsequent characters can be letters, numbers, underscore (_) characters, or spaces.

The renderer name is used to name the renderer callback functions. For example, the cb_Renderer_Init Init callback for a renderer named "Fiesta" is "Fiesta_Init". If a renderer name contains spaces (for example, "Awesome Renderer"), the Init callback function name must omit the spaces (for example, "AwesomeRenderer_Init").

Returns:: Newly created custom renderer PluginItem object.

See also:: RendererContext

Since:: 6.0

PluginItem RegisterICENode ( const ICENodeDef & in_nodedef )

Registers a custom ICENode as a PluginItem object.

Parameters:

in_nodedef An ICENodeDef object describing the new node.

The first character in an ICENode name must be a letter or an underscore (_). Subsequent characters can be letters, numbers, underscore (_) characters, or spaces.

The ICENode name is used to name the ICENode callback functions. For example, the cb_ICENode_Evaluate Evaluate callback for an ICENode named "Drip" is "Drip_Evaluate". If an ICENode name contains spaces (for example, "Chilly Bean"), the Evaluate callback function name must omit the spaces (for example, "ChillyBean_Evaluate").

Returns:: Newly created custom ICENode PluginItem object.

See also:: ICENodeContext

Since:: 7.0

PluginItem RegisterPrimitive ( const CString & in_name )

Registers a custom primitive type.

Parameters:

in_name User-defined name of the new primitive type.

The first character in a custom primitive name must be a letter or an underscore (_). Subsequent characters can be letters, numbers, underscore (_) characters, or spaces.

The primitive type name must be unique.

Returns:: Newly created custom primitive type PluginItem object.

Since:: 12.0 (2014)

PluginItem RegisterShaderLanguageParser ( const CString & in_strParserName )

Registers a shader language parser as a PluginItem object.

Parameters:

in_strParserName The name of the Parser to Register.

Returns:: Newly created custom shader language parser PluginItem object.

See also:: cb_shaderparser Definition Callbacks for Shader Language Parsers; cus_shaders_CreatingShaderParsers Creating Shader Language Parsers

Since:: 9.0 (2011)

PluginItem RegisterShader	(	const CString &	in_strShaderClassName,
		ULONG	in_ulMajorVersion,
		ULONG	in_ulMinorVersion
	)

Registers a custom shader as a PluginItem object.

Parameters:

in_strShaderClassName	The class name of the ShaderDef to Register. This defines the classname part of the shader progid.
in_ulMajorVersion	The major version of the ShaderDef to Register. This defines the major version part of the shader progid.
in_ulMinorVersion	The minor version of the ShaderDef to Register. This defines the minor version part of the shader progid.

Returns:: Newly created custom shader language parser PluginItem object.

Note:: The shader ProgID will be build from the PluginName, ShaderClassName and Major and Minor versions.

See also:: cb_shader Definition Callbacks for Shaders; cus_shaders_CreatingDefPlugins Creating Shader Definition Plug-ins

Since:: 9.0 (2011)

PluginItem RegisterTool ( const CString & in_name )

Registers a custom tool. When the tool is registered a custom script command of the same name is registered which is used to invoke the tool or can be assigned to a keyboard shortcut in the keyboard mapping dialog.

See the ToolContext reference page for details about creating a custom tool.

Parameters:

in_name The name of the tool.

The first character in a tool name must be a letter or an underscore (_). Subsequent characters can be letters, numbers, underscore (_) characters.

The tool name must be unique.

Returns:: The PluginItem object created for the tool.

Since:: 10.0 (2012)

CString GetAuthor ( ) const

Returns the name of the plug-in author.

Returns:: CString

CString GetURL ( ) const

Returns the URL path that can be used to link to a help page for the plug-in (for example, the web site of the plug-in's author).

Returns:: CString

CString GetEmail ( ) const

Returns the email address of the plug-in (for example, the email address of the plug-in's author).

Returns:: CString

CStatus GetVersion	(	LONG &	out_major,
		LONG &	out_minor
	)		const

Returns the plug-in version.

Return values:

out_major	Major version number.
out_minor	Minor version number.

Returns:: CStatus OK if successful.

CString GetLanguage ( ) const

Returns the name of the language used to implement the plug-in. VBScript, JScript, Python, C# and C++ are all valid languages.

Returns:: CString

CString GetFilename ( ) const

Returns the filename of the plug-in.

Returns:: CString

CStatus PutAuthor ( const CString & in_strName )

Sets the name of the author of the plug-in.

Parameters:

in_strName The name of the plug-in's author.

Returns:: CStatus OK if successful

CStatus PutURL ( const CString & in_strURL )

Sets the author's URL path (for example, the URL to your company's website).

Parameters:

in_strURL The URL path.

Returns:: CStatus OK if successful

CStatus PutEmail ( const CString & in_strEmail )

Sets the author's email address (for example, a support contact).

Parameters:

in_strEmail The email address.

Returns:: CStatus OK if successful

CStatus PutVersion	(	LONG	in_major,
		LONG	in_minor
	)

Sets the plug-in version.

Parameters:

in_major	Major version number.
in_minor	Minor version number.

Returns:: CStatus OK if successful.

CStatus PutHelp ( const CString & in_strHelp )

Sets the help path for the plug-in being registered.

Parameters:

in_strHelp The help path

Returns:: CStatus OK if successful; CStatus Fail if not successful

CStatus PutCategories ( const CString & in_strCat )

Sets the categories for the plug-in being registered.

Parameters:

in_strCat A comma-separated string representing the user-defined categories of the plug-in.

Returns:: CStatus OK if successful

CStatus PutUserData ( const CValue & in_userdata )

Stores a CValue inside the plug-in object being registered. Softimage does not care about the content or meaning of the data. Once created, the data remains active as long as Softimage is running or until you manually unload the plug-in.

You can use this to store a value to be accessed locally in the plug-in module or accessed globally by other plug-ins. The user data is not persisted.

Warning:: In the case where a pointer is stored, the object should be destroyed during the cb_Plugin_Unload UnloadPlugin callback.

Parameters:

in_userdata User data to set.

See also:: Plugin.UserData, Plugin::PutUserData

Returns:: CStatus::OK success; CStatus::Fail failure.

Since:: 8.0 (2010)

CValue GetUserData ( ) const

Returns the user data stored in the plug-in referred by this PluginRegistrar object.

Returns:: The user data value.

Since:: 8.0 (2010)

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

xsi_pluginregistrar.h

Detailed Description

Public Member Functions

Constructor & Destructor Documentation

Member Function Documentation