FileDialog Class Reference
[File I/O]

Base class responsible for displaying an OS file browser. More...

Inheritance diagram for FileDialog:

[legend]

Public Member Functions
bool	Execute ()
	Launches the OS file browser.
Public Attributes
bool	changePath
	True/False whether to set the working directory to the directory returned by the dialog.
string	defaultFile
	The default file path when the dialog is shown.
string	defaultPath
	The default directory path when the dialog is shown.
string	fileName
	The default file name when the dialog is shown.
string	filters
	The filter string for limiting the types of files visible in the dialog. It makes use of the pipe symbol '\|' as a delimiter. For example:
string	title
	The title for the dialog.

Detailed Description

Base class responsible for displaying an OS file browser.

FileDialog is a platform agnostic dialog interface for querying the user for file locations. It is designed to be used through the exposed scripting interface.

FileDialog is the base class for Native File Dialog controls in Torque. It provides these basic areas of functionality:

Inherits from SimObject and is exposed to the scripting interface
Provides blocking interface to allow instant return to script execution
Simple object configuration makes practical use easy and effective

FileDialog is *NOT* intended to be used directly in script and is only exposed to script to expose generic file dialog attributes.

This base class is usable in TorqueScript, but is does not specify what functionality is intended (open or save?). Its children, OpenFileDialog and SaveFileDialog, do make use of DialogStyle flags and do make use of specific funcationality. These are the preferred classes to use

However, the FileDialog base class does contain the key properties and important method for file browing. The most important function is Execute(). This is used by both SaveFileDialog and OpenFileDialog to initiate the browser.

Example:

// NOTE: This is not he preferred class to use, but this still works

// Create the file dialog
%baseFileDialog = new FileDialog()
{
   // Allow browsing of all file types
   filters = "*.*";

   // No default file
   defaultFile = ;

   // Set default path relative to project
   defaultPath = "./";

   // Set the title
   title = "Durpa";

   // Allow changing of path you are browsing
   changePath = true;
};

 // Launch the file dialog
 %baseFileDialog.Execute();
 
 // Don't forget to cleanup
 %baseFileDialog.delete();

Note:: FileDialog and its related classes are only availble in a Tools build of Torque.

See also:: OpenFileDialog for a practical example on opening a file; SaveFileDialog for a practical example of saving a file

Member Function Documentation

bool FileDialog::Execute ( )

Launches the OS file browser.

After an Execute() call, the chosen file name and path is available in one of two areas. If only a single file selection is permitted, the results will be stored in the fileName attribute.

If multiple file selection is permitted, the results will be stored in the files array. The total number of files in the array will be stored in the fileCount attribute.

Example:

// NOTE: This is not he preferred class to use, but this still works

// Create the file dialog
%baseFileDialog = new FileDialog()
{
   // Allow browsing of all file types
   filters = "*.*";

   // No default file
   defaultFile = ;

   // Set default path relative to project
   defaultPath = "./";

   // Set the title
   title = "Durpa";

   // Allow changing of path you are browsing
   changePath = true;
};

 // Launch the file dialog
 %baseFileDialog.Execute();
 
 // Don't forget to cleanup
 %baseFileDialog.delete();


 // A better alternative is to use the 
 // derived classes which are specific to file open and save

 // Create a dialog dedicated to opening files
 %openFileDlg = new OpenFileDialog()
 {
    // Look for jpg image files
    // First part is the descriptor|second part is the extension
    Filters = "Jepg Files|*.jpg";
    // Allow browsing through other folders
    ChangePath = true;

    // Only allow opening of one file at a time
    MultipleFiles = false;
 };

 // Launch the open file dialog
 %result = %openFileDlg.Execute();

 // Obtain the chosen file name and path
 if ( %result )
 {
    %seletedFile = %openFileDlg.file;
 }
 else
 {
    %selectedFile = "";
 }
 // Cleanup
 %openFileDlg.delete();


 // Create a dialog dedicated to saving a file
 %saveFileDlg = new SaveFileDialog()
 {
    // Only allow for saving of COLLADA files
    Filters = "COLLADA Files (*.dae)|*.dae|";

    // Default save path to where the WorldEditor last saved
    DefaultPath = $pref::WorldEditor::LastPath;

    // No default file specified
    DefaultFile = "";

    // Do not allow the user to change to a new directory
    ChangePath = false;

    // Prompt the user if they are going to overwrite an existing file
    OverwritePrompt = true;
 };

 // Launch the save file dialog
 %result = %saveFileDlg.Execute();

 // Obtain the file name
 %selectedFile = "";
 if ( %result )
    %selectedFile = %saveFileDlg.file;

 // Cleanup
 %saveFileDlg.delete();