<     > 

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

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

 <     >