OnBeginFileExport (XSIApplication)

Description

Fired before an XSI file is exported as a result of a command such as ExportModel. This is valid for Model (.emdl), dotXSI (.xsi), mixer (.mixer), IGES (.iges) and material library (.matlib).

This event is installed using the XSIApplication.Advise method and can be removed using the XSIApplication.Unadvise method, please see these methods for a detailed example of installing and uninstalling events.

The event may be temporarily muted via the EventInfo.Mute property. All installed events can be viewed in the plugin manager dialog's event tab.

NOTE: The prefered and alternative method of installing this is event is as a self-installing plugin. See PluginRegistrar.RegisterEvent method for more details.

Scripting Syntax

    XSIApplication.OnBeginFileExport ([CustomData], [Input], [FileName], [FileType])

Parameters

Parameter | Type | Description
CustomData | Variant | Custom data passed to the event handler. This argument is optional; you can specify one when binding an event with XSIApplication.Advise. The data is passed to the event handler whenever the event is fired, an empty value is passed if no custom data is specified.
Input | Object | The object that is being exported. For siFileTypeModel this is the Model being exported. For siFileTypedotXSI and siFileTypeIGES this argument is an XSICollection. For siFileTypeMatLib it is a Library. For siFileTypeMixer it is a Mixer.
FileName | String | The complete path that the user wishes to export to.
FileType | siFileType | The type of file to import. The supported types are: siFileTypeModel, siFileTypedotXSI, siFileTypeMixer, siFileTypeIGES, siFileTypeMatLib

Return Value

Boolean True to abort the operation. PythonScript and PerlScriptdo not define

a Boolean type so pass 1 for True and 0 for False.

Examples

1. JScript Example

    // This jscript example demonstrates how the
    // OnBeingFileExport event can be used to track and
    // control the exporting of various file types.

    // Globals
    var oFSO = new ActiveXObject( "Scripting.FileSystemObject" ) ;
    var slash = "\\" ;
    if ( Application.Platform != "Win32" ) { slash = "/" } ;
    var strEventFile = Application.InstallationPath( siUserPath ) +
              slash + "Data" + slash + "Scripts" + slash + "JScriptBeginFileExportEventImpl.js";

    var strEventName = "OnBeginFileExportDemo" ;

    CreateEvent()
    CreateSampleScene() ;
    DemonstrateEvents() ;
    DeleteEvent( strEventName ) ;
    oFSO.DeleteFile( strEventFile ) ;

    function CreateEvent()
    {
       // For demonstration purposes we will dynamically create the script file
       // where the event callback is implemented

       var oFile = oFSO.CreateTextFile( strEventFile, true ) ;

       // XSI expects that the signature is called XSIApplication::OnBeginFileExport
       // However this syntax confuses Jscript if we try to call toString().
       // So we will use "_" instead of ":" and post-process the code
       var fileContents = XSIApplication__OnBeginFileExport.toString()
                  + FileTypeToStr.toString() ;
       fileContents = fileContents.replace( /__/g, "::" ) ;

       oFile.Write( fileContents ) ;
       oFile.Close() ;

       //
       // Now actually register the event
       //

       DeleteEvent( strEventName ) ; // Remove any existing instance
       Application.Advise( "OnBeginFileExport", strEventFile, "",
              "JScript", strEventName,null,null,false ) ;
    }

    function CreateSampleScene()
    {
       //
       // Create a simple scene :
       // two models containing nulls and a sphere with a phong shader
       //

       NewScene( null, false ) ;
       GetPrim("Null");
       CreateModel("", "MyGorilla" ) ;

       GetPrim("Null");
       CreateModel("", "MyMonkey" ) ;

       var oSphere = ActiveSceneRoot.AddGeometry( "Sphere", "MeshSurface" );

       // Create a simple material
       oSphere.AddMaterial( "Phong" ) ;

       // Store a trivial action so that a mixer is established in the scene
       StoreAction("", "sphere.kine.local.roty", 1,
                  "StoredStaticPose", true, 1, 5, false, false, false, 1);
                     }

    function DemonstrateEvents()
    {
       // Given the scene created by CreateSampleScene,
       // this function will attempt to export various files

       //
       // Export Models
       //

       strModelDir = Application.InstallationPath( siProjectPath) + slash + "Models" + slash ;

       try
       {
           ExportModel("MyGorilla" , strModelDir + "mygorilla.emdl" ) ;
       }
       catch( e )
       {
           Logmessage( "Event intentionally blocked the export model call" ) ;
       }

       // Monkey is ok for export
       ExportModel("MyMonkey" , strModelDir + "mymonkey.emdl" ) ;

       //
       // Demonstrate dotXSI export
       //

       strProjectRoot = Application.InstallationPath( siProjectPath) + slash  ;

       SIExportDotXSIFile( "Sphere", strProjectRoot + "mysphere.xsi" ) ;

       //
       // IGES export
       //

       try
       {
           SIExportIges("Sphere", strProjectRoot + "sphere.iges" );
       }
       catch( e )
       {
           LogMessage( "IGES export was blocked as expected" ) ;
       }

       //
       // Mixer Export
       //

       ExportMixer( ActiveSceneRoot, strProjectRoot + "sphere.xsimixer" ) ;

       //
       // Export of a Material Library
       //

       ExportMaterialLibrary(
           strProjectRoot + "sphere_material.xsi",
           GetValue("Sphere").Material.Library ) ;
    }

    //
    // This function is saved into the event script file
    // and is called each time we try to export a file

    function XSIApplication__OnBeginFileExport
    (
       in_userdata,
       in_exportedobj,
       in_filename,
       in_filetype
    )
    {
       // Print some information about the export event

       LogMessage( "File Export Event Called");

       if ( in_exportedobj.Type == "XSICollection" )
       {
           LogMessage( "ExportedObjects: " + in_exportedobj.GetAsText() +
                     " (Count: " + in_exportedobj.Count + ")") ;
       }
       else
       {
           LogMessage( "ExportedObject: " + in_exportedobj +
                  " (Type: " + in_exportedobj.Type + ")") ;
       }

       LogMessage( "FileName: " + in_filename ) ;
       LogMessage( "FileType: " + FileTypeToStr( in_filetype ) ) ;

       if ( in_filetype == siFileTypeModel )
       {
           // Here is an example of using an event to impose some sort of
           // business logic on the users actions.  In this case certain models cannot
           // be exported.

           if ( -1 != in_exportedobj.Name.search( /gorilla/i) )
           {
              LogMessage( "You aren't allowed to export the Gorilla model!" ) ;
              return 1 ;
           }
       }
       else if ( in_filetype == siFileTypedotXSI )
       {
           // Here some special logic could be implemented for
           // dotXSI files, e.g. a naming convention or force the user
           // to pick a certain output directory
       }
       else if ( in_filetype == siFileTypeIGES )
       {
           LogMessage( "IGES export not permitted" ) ;
           return 1 ;
       }

       // Allow the export to go ahead
       return 0;
    }

    // Helper function for printing elements
    // from the siFileType enum
    function FileTypeToStr( in_fileType )
    {
       if ( in_fileType == siFileTypeModel )
       {
           return "Model" ;
       }
       else if ( in_fileType == siFileTypedotXSI )
       {
           return "dotXSI" ;
       }
       else if ( in_fileType == siFileTypeMixer )
       {
           return "Mixer" ;
       }
       else if ( in_fileType == siFileTypeIGES )
       {
           return "IGES" ;
       }
       else if ( in_fileType == siFileTypeMatLib )
       {
           return "MatLib" ;
       }
       else
       {
           return "siFileType " + in_fileType ;
       }
           }

    // Helper function to remove an event by name
    // rather than id.  It does nothing if the event isn't registered
    function DeleteEvent( in_name )
    {
       var oEventInfo = Application.EventInfos.Item( in_name ) ;

       if ( oEventInfo != null )
       {
           Application.UnAdvise( oEventInfo.Token )
           return true ;
       }

       return false ;
    }

    //The following is the expected output of
    //running this example (the path will differ depending
    //on your current project)

    //INFO : File Export Event Called
    //INFO : ExportedObject: MyGorilla (Type: #model)
    //INFO : FileName: <project_path>\Data\XSI_SAMPLES\Models\mygorilla.emdl
    //INFO : FileType: Model
    //INFO : You aren't allowed to export the Gorilla model!
    //ExportModel(null, null, null);  (Marked in red bacause of failure)
    //INFO : Event intentionally blocked the export model call

    //INFO : File Export Event Called
    //INFO : ExportedObject: MyMonkey (Type: #model)
    //INFO : FileName: <project_path>\Data\XSI_SAMPLES\Models\mymonkey.emdl
    //INFO : FileType: Model
    //ExportModel("MyMonkey", "S:\\Data\\XSI_SAMPLES\\Models\\mymonkey.emdl", null);

    //INFO : File Export Event Called
    //INFO : ExportedObjects: sphere (Count: 1)
    //INFO : FileName: S:\Data\XSI_SAMPLES\mysphere.xsi
    //INFO : FileType: dotXSI
    //INFO : 4004 - Begin: Export .xsi file
    //INFO : 4005 - End: Export .xsi file
    //SIExportDotXSIFile("Sphere", "S:\\Data\\XSI_SAMPLES\\mysphere.xsi");

    //INFO : File Export Event Called
    //INFO : ExportedObjects: sphere (Count: 1)
    //INFO : FileName: S:\Data\XSI_SAMPLES\sphere.iges
    //INFO : FileType: IGES
    //INFO : IGES export not permitted
    //SIExportIges(null, null);  (Marked in red bacause of failure)
    //INFO : IGES export was blocked as expected

    //StoreAction(null, "sphere.kine.local.roty", 1, "StoredStaticPose", true, 1, 5, false, false, false, 1);
    //INFO : File Export Event Called
    //INFO : ExportedObject: Mixer (Type: Mixer)
    //INFO : FileName: S:\Data\XSI_SAMPLES\sphere.xsimixer
    //INFO : FileType: Mixer
    //ExportMixer("Scene_Root", "S:\\Data\\XSI_SAMPLES\\sphere.xsimixer", -1);

    //INFO : File Export Event Called
    //INFO : ExportedObject: Sources.Materials.DefaultLib (Type: library_source)
    //INFO : FileName: S:\Data\XSI_SAMPLES\sphere_material.xsi
    //INFO : FileType: MatLib
    //ExportMaterialLibrary(null, "Sources.Materials.DefaultLib");

2. VBScript Example

    sub XSIApplication_OnBeginFileExport( CustomData, Model, FileName, FileType )
       logmessage "*** VBScript Event - XSIApplication_OnBeginFileExport: ***"
       ' your code here
       ' return consumed status in return code
    end sub

3. JScript Example

    function XSIApplication::OnBeginFileExport( CustomData, Model, FileName, FileType )
    {
       Application.LogMessage( "*** JScript Event - XSIApplication::OnBeginFileExport ***");
       // your code here
       // return consumed status in return code
       return 0;
    }

4. PerlScript Example

    sub XSIApplication_OnBeginFileExport
    {
       my ($CustomData, $Model, $Filename, $FileType) = @_;
       $Application->LogMessage( "*** PerlScript Event - XSIApplication_OnBeginFileExport ***" );
       # your code here
       # return consumed status in return code
       return 0;
    }

5. Python Example

    def XSIApplication_OnBeginFileExport( CustomData, cModel, FileName, FileType):
       # XSI will return a raw PyIDispatch for object model items. This
       # object needs to be wrapped in a dynamic dispatch before use.
       import win32com.client.dynamic
       Model = win32com.client.dynamic.Dispatch(cModel)
       Application.LogMessage( '*** PythonScript Event - XSIApplication_OnBeginFileExport(%s) ***'%(Model.Name,) )
       # your code here
       # return consumed status in return code
       return 0

See Also

XSIApplication.OnEndFileExport | XSIApplication.OnBeginFileImport | XSIApplication.OnEndFileImport | PluginRegistrar.RegisterEvent
XSIApplication.Advise | XSIApplication.Unadvise | XSIApplication.EventInfos | SIExportIges
ExportMixer | ExportMaterialLibrary | SIExportDotXSIFile | ExportModel