Unadvise (XSIApplication)

Description

Cancels the binding of an event that was registered by XSIApplication.Advise.

Scripting Syntax

    XSIApplication.Unadvise (Token, [Erase])

COM API Syntax

    HRESULT Unadvise(
       LONG in_lToken,
       VARIANT_BOOL in_removeEvent
    );

Parameters

Parameter | Type | Description
Token | Long | Connection token returned by XSIApplication.Advise.
Erase | Boolean | Tells XSI to remove the event from the cache. If the flag is false then XSI will bind the event again the next time it starts. Default Value: True

Examples

JScript Example

    //--------------------------------------------------------------------
    // JScript example to illustrate the uninstalling custom events
    // using XSIApplication.Unadvise.
    //
    // This example 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 ExXSIApplicationUnadviseDemo(filename)
    {
       // install event
       Application.Advise
       (
           "OnSelectionChange",
           filename,
           ""/*not used*/,
           "JScript",
           "ExXSIApplicationUnadviseDemo_SelectionChange", // your event name
           null /*event specific attributes*/,
           "bob" /*custom data*/,
           false /*persists event between session*/
       );

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

       // find event by name uninstall event
       var eventinfo = Application.EventInfos("ExXSIApplicationUnadviseDemo_SelectionChange");

       // force processing event queue
       XSIUIToolkit.MsgBox ( "force processing of queued events" );

       // find event by name uninstall
       Application.Unadvise( eventinfo.token );

       // this line will trigger another the selection event
       // but the event will have been uninstalled
       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( "ExXSIApplicationUnadviseDemo_OnSelectionChange: 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" +
           "";
    }

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

       ExXSIApplicationUnadviseDemo(filename);
    }