Class Documentation
FileView |
1.0 |
ID_FILEVIEW |
Stable |
FileSystem |
August 2001 |
Rocklyte Systems |
Rocklyte Systems, 2000-2001. All rights reserved. |
The FileView class provides a GUI-based gateway into the file system. |
Description
The FileView class is designed for developing graphical interfaces that
require user interactive file lists. This makes the FileView particularly
good for creating file dialog boxes and file managers. The class supports
a number of features including the filtering of file names using wildcards
(e.g. '*.dml') and you may preset the initial directory location.
The FileView class does not draw its own graphics. In order to actually
display the file list, you need to provide it with a data view object by
setting the View field. Currently we recommend that you
use a TextList object to provide viewing services. The following DML
example shows how to construct an effective file list that loads a text
editor when the user double clicks on a file:
<render name="main{id}" x="5" y="5" xoffset="5" colour="#f0f0f0" yoffset="5">
<scrollbar name="sbv" xoffset="0" y="0" width="16" yoffset="0"
direction="vertical" hide/>
<textlist flags="singleselect|doubleclick" x="5" y="4" vspacing="4"
colour="#000000" face="[gl_fonts.face]" vscroll="[sbv_scroll]"
highlight="#d0d0e0">
<fileview name="fileview{id}" view="[container]" location="athene:"
filter="*.dml">
<create class="run" execute &src="programs:runscript"
&args="$-wait -target desktop -script tools:text/editor/main.dml
-args location='[container.location][[container.view].selection]'$"/>
<action static call="free" object="[main{id}]"/>
</fileview>
</textlist>
</render>
It is possible to create a refined FileView interface by linking buttons
and input boxes directly to the object. For a working example, please refer
to the 'templates:filedialog.dml' file and observe how we created the default
file requester for Athene.
Actions
The FileView class supports the following actions:
Activate | Opens the currently selected file or directory. |
Refresh | Refreshes a FileView's directory list. |
Methods
The FileView class implements the following methods:
ParentDirectory | Jumps to the parent directory of a FileView's current location. |
Structure
The FileView object consists of the following public fields:
Filter | Defines a file filter through the use of wildcards. |
Location | Reflects the directory location that a FileView is analysing. |
View | Must refer to a GUI object that will provide viewing services. |
Activate |
Opens the currently selected file or directory. |
If the user has selected a file or a directory, calling this method will
'open' the selection accordingly. For directories, this means that the
FileView object will go to the selected location and read the directory
contents, consequently updating the FileView. If the selection is a file,
the FileView will send an Activate message to each child that you have
initialised to the FileView object.
If no selection has been made in the View object,
the Activate action will do nothing.
ERR_Okay | The selection was successfully opened. |
ERR_AllocMemory | A call to AllocMemory() failed. |
ERR_ExclusiveDenied | Access to the View object was denied. |
ERR_GetField | The View does not support a Selection field, or no selection has been made by the user. |
ERR_ListChildren | A call to ListChildren() failed. |
|
|
Refresh |
Refreshes a FileView's directory list. |
When the Refresh action is called on a FileView object, the directory
that the FileView is monitoring will be read from scratch, and the list of
directories and files will be subsequently refreshed.
ERR_Okay | The refresh was successful. |
ERR_FieldNotSet | The View field is not set. |
ERR_CreateObject | An error occurred while creating a File object. |
|
|
ParentDirectory() |
Jumps to the parent directory of a FileView's current location. |
When this method is called, the FileView will jump to the parent directory
of the current location. For instance, if the user is currently analysing
the 'athene:system/classes/' directory, then as a result of calling this method
the view will change to the 'athene:system/' directory.
If the current location is already at the root level ':', then this method
will return immediately as there is nothing above root.
ERR_Okay | The method executed successfully, or the location is already set to root level. |
ERR_Memory | The method ran out of memory during normal processing. |
|
|
Field: | Filter |
Short: | Defines a file filter through the use of wildcards. |
Type: | STRING |
Status: | Read/Write |
To define a file filter, set this field using standard wild-card values.
Both the asterisk and question-mark characters are accepted as wild-wards,
while the OR operator is reserved for use in a future update. Here are some
filter examples:
DML files: *.dml
Files with extensions: *.*
DML files with short names: ???.dml
Files where 'b' is a second character: ?b*
Files starting with a, ending in b: a*b
File filters are not case sensitive.
|
|
Field: | Location |
Short: | Reflects the directory location that a FileView is analysing. |
Type: | STRING |
Status: | Read/Write |
If you want the FileView to analyse a specific directory, writing to
this field will force the object to switch to the new location and refresh
the file list.
To change to the root directory, set the Location to a zero length string,
or write the field with a NULL pointer.
|
|
Field: | View |
Short: | Must refer to a GUI object that will provide viewing services. |
Type: | OBJECTID |
Status: | Read/Init |
Because a FileView object does not draw its own graphics, you need to
provide it with a reference to a GUI object that is capable of providing
an interactive viewing service. To do so, you need to create the viewing
object and then refer to it by writing its ID to this field.
Currently we recommend that you use a TextList object to provide viewing
services, but any GUI class can be used so long as it can draw graphics and
provide a functional user interaction service.
|
|