FileReference

Object Hierarchy | Related C++ Class: FileReference

Inheritance

SIObject

FileReference

Introduced

v5.0

Description

This object represents a reference to a file on disk. When you specify a file location in a property page (for example, when you specify the image file for a texture map), the file path string is represented by a FileReference object.

The FileReference object uses two levels of path: the user path and the resolved path. You can access the user path using the FileReference.Path property, which can contain environment variables (using either the Windows syntax, %MY_VAR% or the Linux syntax, $MY_VAR) and can be relative to a project.

You can access the resolved path using the read-only FileReference.ResolvedPath property or the FileReference.UNCPath property, which represents the actual full path (as a local or a UNC path).

You can get FileReference objects from the FileReferenceCollection returned by Model.ExternalFiles and Scene.ExternalFiles.

Methods

FileExists GetFileInSequence IsClassOf operator IsEqualTo operator

Properties

Application Categories FileType FullName operator
GUID Help Name operator NestedObjects
NumberOfFilesInSequence Origin OriginPath Owners
Parent Path ResolvedPath Type operator
UNCPath      
       

Examples

JScript Example

/* 
	This example shows how to get the resolved path
	on each member of the external files list and how to 
	change the path on the fly.
	Note: To see the UNC path in action, change the location 
	of the NewFile variable to a valid UNC path 
	(for example, "\\\\mymachine\\toto\\Man_Face.emdl") that is 
	mapped to a drive letter (such as Q:) and rerun the example.
*/
NewScene( null, false );
// ---------------------------------------------------------------------------
// 	Setup
//
// First import a model so we have some external files to find
var FPath = XSIUtils.BuildPath(
	Application.InstallationPath( siFactoryPath ),
	"Data", "XSI_SAMPLES", "Models", "Man_Face.emdl"
);
var oISIVTColl = ImportModel( FPath, null, true );
// Now copy the reference-model file to a local directory
var NewFile = "C:\\temp\\Man_Face.emdl";
var fso = new ActiveXObject( "Scripting.FileSystemObject" );
fso.CopyFile( FPath, NewFile, true );
// ---------------------------------------------------------------------------
// 	Using the FileReference Object
//
// Get the collection of all external files on the scene
var oModel = oISIVTColl.Value("Value");
var l_extFileList = oModel.ExternalFiles;
// Loop through the list and change only the 
// referenced model file to point to the one we put in c:\temp
for ( var i=0; i<l_extFileList.Count; i++ ) {
	// Get the FileReference object and print the path
	printFileInfo( l_extFileList(i) );
	// Change the path to point to the temp directory
	if ( l_extFileList(i).FileType == "Models" ) {
		// Make sure the original path exists, change it to 
		// the new one, and print the new path for confirmation
		if ( l_extFileList(i).FileExists() ) {
			var OldPath = l_extFileList(i).Path;
			Application.LogMessage( "ORIGINAL PATH: " + OldPath );
			l_extFileList(i).Path = NewFile;
			Application.LogMessage( "MODIFIED PATH: " + l_extFileList(i).Path );
			// Restore original name
			l_extFileList(i).Path = OldPath;
		}
	}
}
// ---------------------------------------------------------------------------
// 	Convenience function
//
function printFileInfo( in_file ) {
	try {
		Application.LogMessage( Application.ClassName(in_file) );
	} catch(e) {
		if ( typeof(in_file).toLowerCase() == "object" ) {
			Application.LogMessage( in_file.FileType );
		} else {
			Application.LogMessage( typeof(in_file) );
		}
	}
	if ( in_file.FileExists() ) {
		// Get the original path 
		var o_path = in_file;
		// Get the resolved path
		var r_path = o_path.ResolvedPath;
		// Get the UNC path
		var u_path = o_path.UNCPath;
		// Print all three results
		Application.LogMessage( "ORIGINAL: " + o_path );
		Application.LogMessage( "RESOLVED: " + r_path ); 
		Application.LogMessage( "UNC     : " + u_path );
	} else {
		Application.LogMessage( "Skipping non-existent file" );
	}
}
// ---------------------------------------------------------------------------
// 	OUTPUT
//
// INFO : FileReference
// INFO : ORIGINAL: <factory_path>\Data\XSI_SAMPLES\Models\Man_Face.emdl
// INFO : RESOLVED: <factory_path>\Data\XSI_SAMPLES\Models\Man_Face.emdl
// INFO : UNC     : <factory_path>\Data\XSI_SAMPLES\Models\Man_Face.emdl
// INFO : ORIGINAL PATH: <factory_path>\Data\XSI_SAMPLES\Models\Man_Face.emdl
// INFO : MODIFIED PATH: C:\temp\Man_Face.emdl
// INFO : FileReference
// INFO : Skipping non-existent file