Class Documentation

Name:FindFiles
Version:1.0
ID:ID_FINDFILES
Status:Unspecified
Category:Tool/Command
Date:May 2001
Author:Rocklyte Systems
Copyright:  Rocklyte Systems (c) 2000-2001. All rights reserved.
Short:  Used to find files and directories for the user.



Description

The FindFiles class can be used either as a command to find and print file lists, or can be integrated into an interface as a Find Files application. Support is provided for setting wild-marked filters and content searching. All you need to provide is a reference to an object capable of receiving text output, so that the user can read the results of the search. This DML based example uses a FindFiles object to search for text files in the 'documents:' directory, which include the word 'Athene':

  <findfiles output="[textlist]" location="documents:" filter="*.txt"
    filecontent="Athene"/>

When searching files for content, it is recommended that a filter is used so that only a limited number of files are opened for searching. If filtering is not used then a content search can take a considerable amount of time to complete, so try to avoid it.

To see a working Find Files application, refer to the tools:filesystem/findfiles/ directory, which will show you how to link user input boxes to a FindFiles object.

Actions

The FindFiles class supports the following actions:

Activate  Executes the search process.
ClosingTag  If the object is non-static, this action will perform the file search and then the object will self-destruct.

Structure

The FindFiles object consists of the following public fields:

FileContent  If the contents of each file should be searched, apply the search string to this field.
Filter  A file filter string can be applied by writing to this field.
Location  The directory location to be search must be specified here.
Output  This field must be set to an object that can receive text output.
Static  Set to TRUE to make the object static.
Action:Activate
Short:Executes the search process.

Activating a FindFiles object causes it to start searching for files. At a minimum you must have set up the Output and Location fields before calling this action, or it will fail. The results of the search will be sent to the object referred to by the Output field.

This action does not return until it has completed the search process.

Result
ERR_Okay  The search executed successfully.
ERR_FieldNotSet  The Output or Location fields were not set.
ERR_NewObject  A File object could not be created.
ERR_Init  A File object could not be initialised.
ERR_AllocMemory  A memory allocation failed.
ERR_ExclusiveDenied  Access to the output object was denied.

 

Field:FileContent
Short:If the contents of each file should be searched, apply the search string to this field.
Type:STRING
Status:Read/Write

If the content of each file is to be searched, set this field to the string that you want to use when searching the file content. Files that contain the string will be listed in the FindFiles output (on the condition that they also passed the filter test).

Note that searching the content of each file increases the amount of time required to do the search by a considerable level. For this reason it is important to use the content searching feature in conjunction with file filtering.

 

Field:Filter
Short:A file filter string can be applied by writing to this field.
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. If you do not use wild-cards then the FindFiles object will look for exact matches to the string you specify.

 

Field:Location
Short:The directory location to be search must be specified here.
Type:STRING
Status:Write

The directory that is to be searched for files must be specified here. Note that searching is recursive, so everything within the directory you specify is also searched. Searching from certain root directories (such as "athene:" can result in long, processor intensive searching. For this reason it is always best to pin-point the location rather than to search from a root directory if possible.

 

Field:Output
Short:This field must be set to an object that can receive text output.
Type:OBJECTID
Status:Read/Write

The Output field must be set so that a FindFiles object has a place to send the results of a search to. The Output object that you specify must accept text-based information via data channels in order for the data to be interpreted correctly. If the Output object does not support text based information, the FindFiles object will still perform the search but the user will not receive any text based output.

It is recommended that this field points to an object that is a member of the TextList class.

 

Field:Static
Short:Set to TRUE to make the object static.
Type:OBJECTID
Status:Read/Write

By default, a FindFiles 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 FindFiles object to perform is to call the Activate() action.