RegisterEvent (PluginRegistrar)

Introduced

5.0

Description

Registers an event as a PluginItem object. The plug-in item is used to create an EventInfo object by binding a user-defined function to an action associated with the registered event.

Scripting Syntax

PluginRegistrar.RegisterEvent( Name, Type )

C# Syntax

PluginItem PluginRegistrar.RegisterEvent( String in_eventName, siEventID in_eventID );

Parameters

Parameter

Type

Description

Name

String

The name of the custom event to register. It should begin with a letter and contain only letters, numbers and the underscore character.

The event name is used to name the 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 EventInfoCollection returned by XSIApplication.EventInfos.

Type

siEventID

Type of event to register.

Note: The following identifiers are not supported: siOnWindowEvent, siOnTimer, siOnCustomFileImport,siOnCustomFileExport. Rather than this method, use PluginRegistrar.RegisterTimerEvent for the siOnTimer event type and PluginRegistrar.RegisterConverterEvent for the siOnCustomFileImport and siOnCustomFileExport event types.

Return Value

PluginItem

Examples

JScript Example

/*-------------------------------------------------------------------
   The example shows how to register and implement an event plug-in.

   README: Copy and paste the example into the script editor 
   and run (F5).

   The events will now be listed in the plugin manager's pluginitem
   tab and under the plugin node in the plugin browser tab.

   The events will fire whenever there the user creates a newscene,
   either from the menu File->New Scene or from scripting using
   the NewScene() command.
-------------------------------------------------------------------*/

function  XSILoadPlugin( in_reg )
{
   in_reg.Author = "Softimage Co." 
   in_reg.Name = "PluginRegistrar.RegisterEvent Example" 

   // register the event plug-in item 
   in_reg.RegisterEvent( "ExRegisterEvent_BeginNewScene", siOnBeginNewScene );
   in_reg.RegisterEvent( "ExRegisterEvent_EndNewScene", siOnEndNewScene );

   // register a command to illustrate events firing.
   in_reg.RegisterCommand( "ExRegisterEventDemo", "ExRegisterEventDemo" );

   return true;
} 

function  ExRegisterEvent_BeginNewScene_OnEvent( in_context )
{
   Application.LogMessage( "ExRegisterEvent_BeginNewScene_OnEvent called" );
}

function  ExRegisterEvent_EndNewScene_OnEvent( in_context )
{
   Application.LogMessage( "ExRegisterEvent_EndNewScene_OnEvent called");
}

function  ExRegisterEventDemo_Execute()
{
   NewScene();
}

//--------------------------------------------------------------------
// Code to bootstrap example into system
//--------------------------------------------------------------------
function ExampleSourceCode()
{
   return "//XSISDK Doc Example\n" +
       ExRegisterEvent_BeginNewScene_OnEvent.toString() + "\n" + 
       ExRegisterEvent_EndNewScene_OnEvent.toString() + "\n" + 
       ExRegisterEventDemo_Execute.toString() + "\n" + 
       XSILoadPlugin.toString();
}

// if we are running from script editor save code to 
// examples addon folder in the user's directory.
if (GetUserPref("ScriptingSessionActive"))
{
   var ex_name  = "ExPluginRegistrarRegisterEvent";
   var ex_subfolder  = "Plugins";
   var ex_folder  = "XSISDKDocExamples";
   var ex_langsuffix = ".js";

   CreateAddonDirectories( InstallationPath(siUserPath), ex_folder );

   var fso = XSIFactory.CreateActiveXObject("Scripting.FileSystemObject");

   var filename = XSIUtils.BuildPath( 
       InstallationPath(siUserAddonPath), 
       ex_folder,
       "Application",
       ex_subfolder,
       ex_name+ex_langsuffix );

   if (!fso.FileExists(filename))
   {
       var f = fso.CreateTextFile ( filename );
       f.write( ExampleSourceCode() );
       f.close();

       Application.LoadPlugin(filename);
   }

   // run demo
   ExRegisterEventDemo();
}

See Also

Plugin.Items

Definition Callbacks for Events

Autodesk Softimage v7.5