Class Documentation

Name:FileDialog
Version:1.0
ID:ID_FILEDIALOG
Status:Beta
Category:GUI
Date:January 2004
Author:Rocklyte Systems
Copyright:  Rocklyte Systems, 2003-2004. All rights reserved.
Short:  The FileDialog class is used to request file selections from the user.



Description

The FileDialog class provides a standard method for prompting the user with a file requester. The process of initialisation is straight forward and the class is designed both for programs and script usage.

The following example illustrates how you can create a file requester that is appropriate for selecting text files. Notice our use of the Set statement, which will write the user's selected file to an external object.

  <filedialog target="[desktop]" title="Select a Text File"
    filterlist="All Files;*;Text Files;*.txt;DML Files;*.dml"
    location="documents:">
    <set static object="[myobject]" &string="\[owner.location\]"/>
  </filedialog>

The dialog box may be configured in a number of areas, including filter definitions, button text and the window title. Please refer to the documentation for the file dialog fields for more information.

If the dialog box needs to be used multiple times, create it as static and then use the Show action to display the dialog window as required. This is a good way of 'caching' the window so that it does not need to be recreated from scratch each time that the dialog window needs to be displayed.

Any child objects that are initialised to a dialog will be activated in the event that a successful response is given by the user. Failure to respond, or some form of cancellation on the user's part will prevent the activation of the child objects.

If you are programming the file dialog directly and would like to receive notification of success, subscribe to the Activate action.

Actions

The FileDialog class supports the following actions:

Show  Puts the dialog window on display.

Structure

The FileDialog object consists of the following public fields:

ActionScript  Script to be executed when the field dialog is activated.
AutoSave  Simplifies the saving of data from objects to files.
CancelText  Defines the string to use for the cancel button.
Filter  The current filter string in the file dialog.
FilterList  Defines a list of filter options to be displayed in the filter combo box.
Flags  Optional flags may be set here.
Icon  The icon that appears in the window title bar can be defined here.
Location  The starting location of the file view is defined here.
OkayText  Defines the string to use for the okay button.
SelectedFiles  Returns a list of all selected files, assuming a successful open procedure.
Static  Set to TRUE to make the object static.
Target  The target for the dialog box window is specified here.
Title  Defines the window title for the dialog box.
Window  Refers to the ID of the window created by the file dialog object.
Field:ActionScript
Short:Script to be executed when the field dialog is activated.
Type:STRING
Status:Get/Set

When a file dialog box is activated due to the user's confirmed selection of a file, you can elect to run a script that performs a responsive action. The ActionScript string will typically refer to a file location, although the special STRING: assignment followed with script execution text (e.g. DML) can also be useful for optimising execution for simple scripts.


Field:AutoSave
Short:Simplifies the saving of data from objects to files.
Type:OBJECTID
Status:Read/Set

Field:CancelText
Short:Defines the string to use for the cancel button.
Type:STRING
Status:Get/Set

The text that appears in the cancel button of the file dialog may be redefined here. By default, the dialog will displaye the word "Cancel" in the button.


Field:Filter
Short:The current filter string in the file dialog.
Type:STRING
Status:Get/Set

The file filter that is used for the dialog box can be defined by setting this field. By default the Filter is set to the first filter identified from the FilterList field. If that is not available then the filter string will be empty and all files will be shown.

The filter that you set must either be a standard wildcard filter (such as *.txt|*.text), or the name of a predefined filter from the FilterList string.


Field:FilterList
Short:Defines a list of filter options to be displayed in the filter combo box.
Type:STRING
Status:Get/Set

Suitable filters for the filter combo box are defined by setting this field. Filters are listed in a single string, using the format "text;value;text;value;...". The "text" string is the name of the filter as you want to display to the user, and the "value" string is the actual file filter that will be used for filtering the files. The following examples illustrate:

   All Files;*;Text Files;*.txt|*.text;DML Files;*.dml
   PCX Pictures;*.pcx;PNG Pictures;*.png;JPEG Pictures;*.jpeg|*.jpg

The first filter that is defined in the list is used as the default. If you need to set a different default filter, you can do so by setting the Filter field.


Field:Flags
Short:Optional flags may be set here.
Type:LONG
Status:Read/Init

Optional flags that may be set against a dialog object are as follows:

FlagDescription
MULTISELECTEnables multi-select mode so that the user may select multiple files and directories.
STRICTFILTERStrictly limits the filter combo box so that the user cannot type in custom filters.
WAITNormally when a dialog window is displayed, the task's process flow will return immediately to the core program. This can be problematic if you require a response to the dialog box before continuing with your processing. To solve this issue, use the WAIT flag to curb the program flow until the dialog box receives a response from the user.

Field:Icon
Short:The icon that appears in the window title bar can be defined here.
Type:STRING
Status:Get/Set

A file folder icon is set in the dialog window by default, however you may change to a different icon image if you wish. If you are going to refer to a stock icon, use the file format, "icons:category/name".


Field:Location
Short:The starting location of the file view is defined here.
Type:STRING
Status:Get/Set

By default the file-view will display the filesystem's root file structure when it is shown for the first time. You can switch to a different default directory on initialisation by setting the Location field. The file dialog object will automatically strip-out any file references that trail the location string.


Field:OkayText
Short:Defines the string to use for the okay button.
Type:STRING
Status:Get/Set

The text that appears in the okay button of the file dialog may be redefined here. By default, the dialog will display the words "Open File" in the button.


Field:SelectedFiles
Short:Returns a list of all selected files, assuming a successful open procedure.
Type:STRING *
Status:Read

When using multi-select mode (as defined in the Flags field), you will need to use the SelectedFiles field when reading a complete list of the files that the user has selected. This field will return an array of strings, each revealing the complete path to a user-selected file. The array is terminated with a NULL entry.

The array remains valid up until the next time that you read the SelectedFiles field.


Field:Static
Short:Set to TRUE to make the object static.
Type:OBJECTID
Status:Read/Write

By default, the FileDialog object will execute itself and then self-destruct when a closing tag is received. If you would rather that the object stays in the system, set this field to TRUE. If you do this, the only way to get a Dialog object to perform is to call the Show action.


Field:Target
Short:The target for the dialog box window is specified here.
Type:OBJECTID
Status:Init

The window for a dialog box will normally be created on the desktop. On occasion it may be useful to have the window appear in a different area, such as inside another window or screen. To do this, point the Target field to the unique ID of the drawable that you want to open the window on.

The target may not be changed after initialisation.


Field:Title
Short:Defines the window title for the dialog box.
Type:STRING
Status:Get/Set

The window title for the dialog box is specified here as a standard UTF-8 text string.


Field:Window
Short:Refers to the ID of the window created by the file dialog object.
Type:OBJECTID
Status:Read

This readable field references the ID of the dialog box's window. It is only usable on successful initialisation of a dialog box. It is recommended that you avoid tampering with the generated window, but direct access may be useful for actions such as altering the window position.