Class Documentation
FileView |
1.0 |
ID_FILEVIEW |
Stable |
FileSystem |
March 2004 |
Rocklyte Systems |
Rocklyte Systems, 2000-2004. 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
useful for creating file dialog boxes and file managers. The class supports
a number of features including the filtering of file names using wildcards
(for example, '*.dml') and you may preset the initial directory location.
The FileView class does not draw its own graphics. In order to
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 View 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" x="5" y="5" xoffset="5" colour="#f0f0f0" yoffset="5">
<scrollbar direction="vertical"/>
<view style="list" x="5" y="4" linespacing="4" highlight="#d0d0e0">
<fileview view="[owner]" location="athene:" filter="*.dml">
<create class="run" execute &src="programs:bin/runscript"
&args="tools:text/editor/main.dml -args location='\[owner.selectionfile\]'"/>
<action static call="free" object="[main]"/>
</fileview>
</text>
</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. |
Focus | Activates keyboard monitoring (by force). |
LostFocus | Deactivates keyboard monitoring (by force). |
Refresh | Refreshes a FileView's directory list. |
Methods
The FileView class implements the following methods:
CopyFiles | Posts all currently selected files to the clipboard as a 'copy' operation. |
CreateDir | Creates a new directory in the current path of the file view. |
CutFiles | Posts all currently selected files to the clipboard as a 'cut' operation. |
DeleteFiles | Deletes all currently selected files, following user confirmation. |
EditFiles | Runs the edit command for all currently selected files. |
ParentDirectory | Jumps to the parent directory of a FileView's current location. |
PasteFiles | Pastes files from the clipboard to the current path of the file view. |
RenameFile | Renames the most recently selected item in the file view. |
ViewFiles | Runs the view command for all currently selected files. |
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. |
Selection | Readable field that indicates the name of the currently selected item. |
SelectionFile | The currently selected file or directory (fully-qualified). |
SelectionPath | The complete file-path of the current selection. |
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. |
|
|
CopyFiles() |
Posts all currently selected files to the clipboard as a 'copy' operation. |
The CutFiles method will post all selected files and directories from
the view to the clipboard. If there are no files selected, the method does
nothing.
|
|
CreateDir() |
Creates a new directory in the current path of the file view. |
This method creates a dialog box that prompts the user for a directory name.
If the user types in a valid directory name then the directory will be created
in the current location of the file view. The user may cancel the process
by closing the dialog window at any time.
|
|
CutFiles() |
Posts all currently selected files to the clipboard as a 'cut' operation. |
The CutFiles method will post all selected files and directories from
the view to the clipboard. If there are no files selected, the method does
nothing.
|
|
DeleteFiles() |
Deletes all currently selected files, following user confirmation. |
This method simplifies the process of deleting selected files for the user. The
method will pop-up a dialog box to ask the user if the selected files should
be deleted. If the user responds positively, the method will proceed to delete
all of the requested files. Error dialogs may pop-up if any problems occur
during the deletion process.
If no files are selected, this method does nothing.
This method will return a failure code if the creation of the initial
dialog box fails.
ERR_Okay | The process executed successfully. |
ERR_CreateObject | Failed to create the dialog box. |
ERR_AccessObject | Failed to access the referenced View object. |
|
|
EditFiles() |
Runs the edit command for all currently selected files. |
This method simplifies the process of editing selected files for the user.
The routine utilises the Run class with the EDIT mode option to launch the files
in their respected editors.
If no files are selected, this method does nothing.
ERR_Okay | The process executed successfully. |
ERR_AccessObject | Failed to access the referenced View 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. |
|
|
PasteFiles() |
Pastes files from the clipboard to the current path of the file view. |
Call the PasteFiles method to copy files from the clipboard into the
current path of the file view. The file view will automatically refresh
itself so that pasted files are immediately displayed.
|
|
RenameFile() |
Renames the most recently selected item in the file view. |
This method simplifies the process of renaming the most recently selected
file for the user. The method will pop-up an input box to ask the user for
the new file name. If the user responds positively, the method will proceed
to rename the file.
If no file is selected, this method does nothing.
ERR_Okay | The process executed successfully. |
ERR_AccessObject | Failed to access the referenced View object. |
|
|
ViewFiles() |
Runs the view command for all currently selected files. |
This method simplifies the process of viewing selected files for the user.
The routine utilises the Run class with the VIEW mode option to launch the files
in their respected viewers.
If no files are selected, this method does nothing.
ERR_Okay | The process executed successfully. |
ERR_AccessObject | Failed to access the referenced View object. |
|
|
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: | Get/Set |
If you want a 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: | Selection |
Short: | Readable field that indicates the name of the currently selected item. |
Type: | STRING |
Status: | Get |
The Selection field provides a method for learning what the currently
selected file or directory is. If no selection is active then this
function will return a value of NULL. The path leading to the file will
not be included in the resulting string. If the current selection is a
directory or assignment, any trailing symbols will be stripped from the end
of the directory name.
|
|
Field: | SelectionFile |
Short: | The currently selected file or directory (fully-qualified). |
Type: | STRING |
Status: | Get |
The SelectionFile field provides a method for learning what the currently
selected file or directory is. If no selection is active then this function
will return a value of NULL. The path leading to the file will not
be included in the resulting string. If the current selection is a
directory or assignment, the correct trailing symbol will be appended to
the end of the string to indicate the file type.
|
|
Field: | SelectionPath |
Short: | The complete file-path of the current selection. |
Type: | STRING |
Status: | Get |
The SelectionPath field provides a method for learning what the currently
selected file or directory is. If no selection is active then this function
will return a value of NULL. The path leading to the file will be included
in the resulting string. The path is fully-qualified, so a trailing slash
or colon will be present in the event that the selection is a directory or
assignment.
The resulting string will remain valid until the fileview object is freed
or the SelectionPath is used a consecutive time.
|
|
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 Text 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.
|
|