FileReference

Object Hierarchy | Related C++ Class: FileReference

Inheritance

    SIObject
       FileReference

Introduced

5.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 | IsEqualTo

Properties

Application | Categories | FileType | FullName
GUID | Help | Name | NestedObjects
NumberOfFilesInSequence | Origin | OriginPath | Owners
Parent | Path | ResolvedPath | Type
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

Autodesk Softimage v7.5