FxFile

This module contains functions needed to work with managed files, which are proprietary files that are managed by Foxel's file manager. Each managed file has a FileID and a FileType. If a function of this module doesn't need a FileID, then the open file of the given FileType is used. For each file type there can be only one open file at a time. FileIDs are unique only within a file type, not across file types, so both FileType and FileID are required to identify closed files. To learn more about the various managed files and their properties, refer to the File Reference.

Load

FxFile = require "FxFile";

Functions

Function	Description
Close (FileType)	Closes a file.
Create (FileType)	Creates a new file.
Delete (FileType, FileID)	Deletes a file.
Duplicate (FileType, FileID)	Duplicates a file.
Export (FileType, FileID, TargetFilename, ExportProfileID)	Exports a file.
Get1b (FileType, FileProperty) Get1c (FileType, FileProperty) Get1f (FileType, FileProperty) Get1i (FileType, FileProperty) Get1s (FileType, FileProperty) Get2f (FileType, FileProperty) Get2i (FileType, FileProperty) Get3f (FileType, FileProperty) Get3i (FileType, FileProperty)	Return file property values.
Import (FileType, SourceFilename, ImportProfileID)	Imports external files.
Open (FileType, FileID)	Opens a file.
Rename (FileType, FileID, NewFileID)	Renames a file.
Save (FileType)	Saves changes to a file.
SaveAs (FileType, NewFileID)	Saves the open file state to a new file.
Select (FileType, FileID, Value)	Selects and deselects files.
SelectEx (FileType, FileID)	Exclusively selects files.
Set1b (FileType, FileProperty, Value) Set1c (FileType, FileProperty, Value) Set1f (FileType, FileProperty, Value) Set1i (FileType, FileProperty, Value) Set1s (FileType, FileProperty, Value) Set2f (FileType, FileProperty, X, Y) Set2i (FileType, FileProperty, X, Y) Set3f (FileType, FileProperty, X, Y, Z) Set3i (FileType, FileProperty, X, Y, Z)	Set file property values.

Close (FileType)

This function closes the open file of the given FileType. Only one file of each type can be open at a time.

Parameters

• FileType: FileType of the open file to close

Errors

Possible errors include FX_REQUIRED_FILE_UNAVAILABLE, FX_TYPE_INVALID

Since

Version 1.0

Example

-- close open asset file
FxFile.Close(111);

Create (FileType)

This function creates a new file of the given FileType and returns its FileID.

Parameters

• FileType: New FileType of the new file

Returns

The FileID of the new managed file

Errors

Possible errors include FX_TYPE_INVALID, FX_FILE_OPERATION_FAILED

Since

Version 1.0

Example

-- create a new model asset
val = FxFile.Create(112);

Delete (FileType, FileID)

This function deletes the specified files.

Parameters

• FileType: FileType of the files to delete
• FileID: The FileID to identify the files to be deleted

Errors

Possible errors include FX_FILE_NOT_FOUND, FX_TYPE_INVALID, FX_FILE_OPERATION_FAILED

Since

Version 1.0

Example

-- Delete asset model1
FxFile.Delete(111, "model1");
--- Delete all bitmap assets
FxFile.Delete(115, "*");

Duplicate (FileType, FileID)

This function duplicates the specified files and returns the new FileIDs.

Parameters

• FileType: FileType of the files to duplicate
• FileID: The FileID to identify the files to be duplicated

Returns

FileID of duplicated files

Errors

Possible errors include FX_FILE_NOT_FOUND, FX_TYPE_INVALID, FX_FILE_OPERATION_FAILED

Since

Version 1.0

Example

-- Duplicate asset model1
double = FxFile.Duplicate(111, "model1");

Export (FileType, FileID, TargetFilename, ExportProfileID)

This function exports the specified file. The used exporter is automatically determined by the extension of the destination file name. If no exporter is available for the given file type and format, then the export will fail. The export profile is optional.

Parameters

• FileType: The FileType of the files to export
• FileID: The FileID to identify the files to be exported
• TargetFilename: The absolute filename to save the export file as
• ExportProfileID: The optional FileID of an Export Profile that contains the export settings to be used. If no FileID is specified, the project profile is used.

Errors

Possible errors include FX_FILE_NOT_FOUND, FX_TYPE_INVALID, FX_FILE_FORMAT_UNSUPPORTED, FX_FILE_OPERATION_FAILED

Since

Version 1.0

Example

-- Export color palette colorpalette1 as .png file
val = FxFile.Export(11, "colorpalette1", "c:\\mywork\\colorpalette1.png", "");

Get1b (FileType, FileProperty)
Get1c (FileType, FileProperty)
Get1f (FileType, FileProperty)
Get1i (FileType, FileProperty)
Get1s (FileType, FileProperty)
Get2i (FileType, FileProperty)
Get2f (FileType, FileProperty)
Get3f (FileType, FileProperty)
Get3i (FileType, FileProperty)

These functions return the value of a file property of the specified open file. The value type of the property must match the selected Get function; for example, if the property is of type int, use Get1i.

Parameters

• FileType: The FileType of the file
• FileProperty: The FileProperty to query

Returns

Get1b returns 1 value
Get1c returns 1 Color value
Get1s returns 1 value
Getxi returns x values
Getxf returns x values

Errors

Possible errors include FX_REQUIRED_FILE_UNAVAILABLE, FX_TYPE_INVALID, FX_PROPERTY_INVALID

Since

Version 1.0

Example

x y z = FxFile.Get3i(111, "scanBoxSize");

Import (FileType, SourceFilename, ImportProfileID)

This function imports a file, converts it to the given file type and returns its ID. The importer used is determined by the extension of the source file name. If there is no importer is available for the given file type and format then the import will fail. The import profile is optional.

Parameters

• FileType: The FileType to import the file as
• SourceFilename: Absolute filename of the file to import
• ImportProfileID: The optional FileID of an Import Profile that contains the import settings to be used. If no FileID is specified, the project profile is used.

Returns

FileID of the new file

Errors

Possible errors include FX_FILE_NOT_FOUND, FX_TYPE_INVALID, FX_FILE_FORMAT_UNSUPPORTED, FX_FILE_OPERATION_FAILED

Since

Version 1.0

Example

-- import hdr file as cubemap using project import settings
val = FxFile.Import(222, "c:\\mywok\\studio.hdr", "");

Open (FileType, FileID)

This function opens the specified file. A previously opened file of the given FileType will be closed, any unsaved changes will be lost. Only one file of each type can be opened at a time.

Parameters

• FileType: The FileType of the file to be opened
• FileID: The FileID of the file to be opened

Errors

Possible errors include FX_FILE_NOT_FOUND, FX_TYPE_INVALID, FX_FILE_OPERATION_FAILED

Since

Version 1.0

Example

-- open asset model1
FxFile.Open(111, "model1");
-- open asset model2, automatically closes model1
FxFile.Open(111, "model2");

Rename (FileType, FileID, NewFileID)

This function changes the ID of a file and returns the new ID. The new ID may be different from the requested one if that ID has already been taken. If the requested ID contains invalid characters or is empty, the corresponding default ID is used.

Parameters

• FileType: The FileType of the files to be renamed
• FileID: The FileID to identify the files to be renamed
• NewFileID: The new FileID, can't be a wildcard, filter, or list

Returns

Actual new FileID

Errors

Possible errors include FX_FILE_NOT_FOUND, FX_TYPE_INVALID, FX_FILE_OPERATION_FAILED

Since

Version 1.0

Example

-- rename model1 to fox
val = FxFile.Rename(111, "model1", "fox");
-- rename model2, model3, model4 as list
val = FxFile.Rename(111, "<model2,model3,model4", "hen1"); -- returns "<hen1,hen2,hen3>"

Save (FileType)

This function saves the opened file of the given FileType.

Parameters

• FileType: The FileType of the open file to be saved

Errors

Possible errors include FX_TYPE_INVALID, FX_REQUIRED_FILE_UNAVAILABLE, FX_FILE_OPERATION_FAILED

Since

Version 1.0

Example

-- save open asset
FxFile.Save(0);

SaveAs (FileType, NewFileID)

This function saves the current state of the specified open file to another file, opens it, and returns its FileID. The old file will be closed without saving. The new ID may be different from the requested one if that ID was already taken. If the requested ID contains invalid characters or is empty, the corresponding default ID is used.

Parameters

• FileType: The FileType of the open file to be saved to another file
• NewFileID: The FileID of the new file, can't be a wildcard, list or filter

Returns

Actual FileID of new file

Errors

Possible errors include FX_TYPE_INVALID, FX_REQUIRED_FILE_UNAVAILABLE, FX_FILE_OPERATION_FAILED

Since

Version 1.0

Example

-- save open asset as model2
nodeid = FxFile.SaveAs(111, "model2");

Select (FileType, FileID)

This function sets the selection state of files.

Parameters

• FileType: The FileType of the files
• FileID: The FileID to identify the files

Errors

Possible errors include FX_TYPE_INVALID, FX_FILE_NOT_FOUND

Since

Version 1.0

Example

-- deselect all assets
FxFile.Select(111, "*", false);
-- select asset model1
FxFile.Select(111, "model1", true);

SelectEx (FileType, FileID)

This function exclusively selects files. All other files of given FilyType are deselected.

Parameters

• FileType: The FileType of the files to be selected exclusively
• FileID: The FileID to identify the files to be selected exclusively

Errors

Possible errors include FX_TYPE_INVALID, FX_FILE_NOT_FOUND

Since

Version 1.0

Example

-- exclusively select model1
FxFile.SelectEx(0, "model1");
-- same as:
FxFile.Select(0, "*", false);
FxFile.Select(0, "model1", true);

Set1b (FileType, FileProperty, Value)
Set1c (FileType, FileProperty, Value)
Set1f (FileType, FileProperty, Value)
Set1i (FileType, FileProperty, Value)
Set1s (FileType, FileProperty, Value)
Set2i (FileType, FileProperty, X, Y)
Set2f (FileType, FileProperty, X, Y)
Set3f (FileType, FileProperty, X, Y, Z)
Set3i (FileType, FileProperty, X, Y, Z)

These functions set the values of properties of the specified open file. The value type of the property must match the selected set function. For example if the property is of the type int, use Set1i.

Parameters

• FileType: The FileType of the files
• FileProperty: The FileProperty to change
• Value, X, Y, Z: Value(s) to set, type depends on function called

Errors

Possible errors include FX_REQUIRED_FILE_UNAVAILABLE, FX_TYPE_INVALID, FX_PROPERTY_INVALID, FX_VALUE_INVALID

Since

Version 1.0

Example

FxFile.Set1i(111, "category", 32);
FxFile.Set3i(111, "scanBoxOrigin", 2, 3, 10);