PluginRegistrar.RegisterEvent

Introduced

v5.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.

C# Syntax

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

Scripting Syntax

oReturn = PluginRegistrar.RegisterEvent( Name, Type );

Return Value

PluginItem

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.

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