<     > 

Advise (XSIApplication)

Description

Installs a new event handler.

An event is a specific "action" or "situation" that can happen during the execution of XSI. When the event occurs XSI will call any "event handlers" which are "bound" to this event. The "event handler" is a "callback function" implemented inside a script, .dll or .so file.

For example the XSIApplication.OnBeginSceneSave events are called whenever a user starts to save a scene, while the XSIApplication.OnSelectionChange events are called whenever a selection changes.

An event can be bound to more than one event handler; when the event occurs, each handler is called in the order in which they were bound.

XSI expects a specific name for the callback function which implements the event. For C++ clients the name is always XSIOnEvent(). For VBScript, PerlScript and Python the name is XSIApplication_{event name}. For JScript the name is XSIApplication::{event name}.

Certain actions inside XSI actually fire two events, for example OnBeingSceneSave and OnEndSceneSave. The first event is the "Begin" event which happens before the action has been performed. This gives the event handler a chance to abort the action. The second event is the "End" event which happens after the action is completed. At this stage it is too late to abort the event, but the event handler can be sure that the action has already been successfully completed.

When an event is installed in this fashion it is always considered a "user" event, no matter where the implementation file is. However an event can be moved to a workgroup by packaging it in an xsiaddon file and then installed the xsiaddon inside the workgroup.

In many cases it is desirable to persist the event so that it is not lost when XSI is stopped and restarted. This is controlled by the "Save" parameter. Persisted events are remembered inside the \Data\xsicustom.data file.

Scripting Syntax

XSIApplication.Advise (EventName, FileName, [HandlerFunction], [Language], [Name], [Attributes], [CustomData], [Save])

COM API Syntax

HRESULT Advise(
   BSTR in_event,
   BSTR in_filename,
   BSTR in_handlerFunc,
   BSTR in_language,
   BSTR in_name,
   VARIANT in_varAttrib,
   VARIANT in_varCustomData,
   VARIANT_BOOL in_saveEvent,
   LONG* out_pToken
);

Parameters

Return Value

The connection token (see EventInfo.Token) which uniquely identifies the

event. This token can be used to unregister the event (see XSIApplication.Unadvise).

Examples

1. JScript Example

//--------------------------------------------------------------------
// JScript example to illustrate the installing custom events
// using XSIApplication.Advise.
//
// Installs a JScript handler functions for the OnSelectionChange &
// OnBeginSceneSave events. Once you have installed the event, a message
// will log in the history when a new scene is created or when an object
// is selected or deselected.
//
// README: Copy and paste the example into the script editor
// and run (F5).
//
// The events will now be listed in the Plugin Manager's event
// tab.
//
// NOTE: The event callbacks have be coded as functions so that
// we can take advantage of the JScript function.toString(). You
// cannot call toString() on an event callback for example,
// XSIApplication::OnSelectionChange.toString(). Furthermore the
// object XSIApplication is only known within the context of
// an event script installed using the Application.Advise. It is not
// understood by the scripting engine in the general scripting
// context.
//-------------------------------------------------------------------
function ExXSIApplicationAdviseDemo(filename)
{
   Application.Advise
   (
       "OnBeginNewScene",
       filename,
       ""/*not used*/,
       "JScript",
       "MyNewSceneEvent",
       null /*event specific attributes*/,
       Array(1,"cone") /*custom data*/,
       false /*persists event between session*/
   );

   Application.Advise
   (
       "OnSelectionChange",
       filename,
       ""/*not used*/,
       "JScript",
       "MySelectionChangeEvent",
       null /*event specific attributes*/,
       "bob" /*custom data*/,
       false /*persists event between session*/
   );

   // this line will trigger the new scene event
   NewScene();

   // this line will trigger the selection event
   CreatePrim("Cone", "MeshSurface", null, null);
}

/*
   Binds a JScript handler function to the OnSelectionChange event.
   After you run this sample you will see a message in the script history each
   time you select an object.
*/
function XSIApplication_OnSelectionChange( data, change )
{
Application.logMessage( "OnSelectionChange: userdata= " + data.toString() );
}

/*
   Binds a JScript handler function to the OnBeginNewScene event.
   After you run this sample you will see a message in the script history each
   time you create a new scene.
*/
function XSIApplication_OnBeginNewScene( data, Unused )
{
   LogMessage( "OnBeginNewScene userdata=" + data.toString() );
}

//--------------------------------------------------------------------
// Code to bootscrap example into system
//--------------------------------------------------------------------
function ExampleSourceCode()
{

   // turn functions into event callbacks by replacing the '_' with
   // '::' to form XSIApplication_OnSelectionChange.

   return "// XSISDK Doc Example\n" +
       XSIApplication_OnSelectionChange.toString().replace(/_/,"::") + "\n" +
       XSIApplication_OnBeginNewScene.toString().replace(/_/,"::") + "\n" +
       "";
}

// if we are running from script editor save code to
// examples addon folder in the user's directory.
if (GetUserPref("ScriptingSessionActive"))
{
   var ex_name  = "ExXSIApplicationAdvise";
   var ex_subfolder  = "Scripts";
   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,
       "Data",
       ex_subfolder,
       ex_name+ex_langsuffix );

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

   ExXSIApplicationAdviseDemo(filename);
}

2. C++ Example

'
' Binds a C++ handler function to the OnBeginNewScene event.
'
' NB: The event handler name is not required for C++ clients. You need to
' implement an event handler in MyEventHandler.dll to run this example.
'
filename = "C:\MyEventHandler.dll"
language = "cpp"
Application.Advise "OnBeginNewScene",filename,,language,"MyEvent1",,,TRUE

See Also

 <     >