Class Documentation
FileDialog |
1.0 |
ID_FILEDIALOG |
Beta |
GUI |
January 2004 |
Rocklyte Systems |
Rocklyte Systems, 2003-2004. All rights reserved. |
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:
MULTISELECT | Enables multi-select mode so that the user may select multiple files and directories. |
STRICTFILTER | Strictly limits the filter combo box so that the user cannot type in custom filters. |
WAIT | Normally 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.
|
|