Class Documentation

Name:FileView
Version:1.0
ID:ID_FILEVIEW
Status:Stable
Category:FileSystem
Date:August 2001
Author:Rocklyte Systems
Copyright:  Rocklyte Systems, 2000-2001. 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 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.
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: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.

 

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.