Class Documentation

Name:FileView
Version:1.0
ID:ID_FILEVIEW
Status:Stable
Category:FileSystem
Date:March 2004
Author:Rocklyte Systems
Copyright:  Rocklyte Systems, 2000-2004. All rights reserved.
Short:  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.
Action:Activate
Short: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.

Result
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.

Action:Refresh
Short: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.

Result
ERR_Okay  The refresh was successful.
ERR_FieldNotSet  The View field is not set.
ERR_CreateObject  An error occurred while creating a File object.

Method:CopyFiles()
Short: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.


Method:CreateDir()
Short: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.


Method:CutFiles()
Short: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.


Method:DeleteFiles()
Short: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.

Result
ERR_Okay  The process executed successfully.
ERR_CreateObject  Failed to create the dialog box.
ERR_AccessObject  Failed to access the referenced View object.

Method:EditFiles()
Short: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.

Result
ERR_Okay  The process executed successfully.
ERR_AccessObject  Failed to access the referenced View object.

Method:ParentDirectory()
Short: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.

Result
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.

Method:PasteFiles()
Short: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.


Method:RenameFile()
Short: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.

Result
ERR_Okay  The process executed successfully.
ERR_AccessObject  Failed to access the referenced View object.

Method:ViewFiles()
Short: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.

Result
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.