<     > 

Creating an Event

Declaring Event Handlers

VBScript supports implicit binding, which means that you only have to supply a function implementation in the following format for successful binding:

   sub EventSource_EventName( argument_list )
       ' event handler code goes here
   end sub

Compiled handlers need to hook into XSI, which makes them more involved to deal with, but you can use the callback function for the API you are using:

• To use the XSIOnEvent callback function to declare your event handler (COM API)

• To use the XSIOnEventCPP callback function to declare your event handler (C++ API)

To use the XSIOnEvent callback function to declare your event handler (COM API)

This is the simplest way to handle events: you need to provide an external DLL or SO that includes the XSIOnEvent function containing a case for each bound event:

HRESULT WINAPI XSIOnEvent
(
   LONG        in_lEventID,
   LPVARIANT   in_pVar,
   LONG        in_lNum
)
{
   switch (in_lEventID)
   {
       case siOnBeginSceneSave:
       {
          if (!CanSaveMyCurrentScene())
          {
              // abort the operation using the predefined abort argument
              LPVARIANT pVar = V_VARIANTREF(&in_pVar[1]);
              V_BOOL(pVar) = VARIANT_TRUE;
          }
       }
       break;
   };
   return S_OK;
}

The XSIOnEvent callback function takes these arguments:

It returns an HRESULT with one possible value:

To abort the operation, set the Abort argument to TRUE. The position of this argument in the argument array is specific to the event itself.

Not all events support an Abort argument. For example, OnTerminate cannot be interrupted.

To use the XSIOnEventCPP callback function to declare your event handler (C++ API)

You need to provide an external DLL or SO that includes the XSIOnEventCPP:

   XSI::CStatus XSIOnEventCPP( long in_eventID,  XSI::CValueArray& in_args);

Exporting Event Handlers

As is the case with developing any compiled function as part of a plug-in for XSI, you need to export your function with a DEF file so that XSI can find it.

To export your event handler function

- Specify a a DEF file similar to this one:

   LIBRARY MYHNDL
   DESCRIPTION "Event and command handler function."
   EXPORTS
       XSIOnEvent @1 PRIVATE
       XSIOnCommand @1 PRIVATE

XSIOnEvent needs to be exported only if it is defined in the .dll.

Remember that for calling callback functions, XSI uses the name of the function, not its ordinal value.

How To Capture XSI's Initialization And Termination

You can use the DllMain function in your DLL to run any customization routines while XSI loads your DLL(DLL_PROCESS_ATTACH) or terminates (DLL_PROCESS_DETACH). For example, you may want to perform some process initialization local to the DLL. For more information, see the MSDN Library.

 <     >