Class Documentation

Name:FindFiles
Version:1.0
ID:ID_FINDFILES
Status:Unspecified
Category:Tool/Command
Date:June 2004
Author:Rocklyte Systems
Copyright:  Rocklyte Systems (c) 2000-2004. 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, such as a Find Files application. Support is provided for setting wildcard 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="[text]" 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.

This class can also be used to scan for specific files and perform an action on each file as it is found. To do this, initialise the objects you want to call inside the findfiles object. It is important that you use the File field dynamically so that you can read the most recently found file-path for each discovery cycle. Here is an example that uses this feature to delete all object files (*.o) from a directory tree.

  <findfiles location="athene:sdk/classes/" filter="*.o">
    <script static src="commands:delete" &src="\[owner.file\]"/>
  </findfiles>

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.
Deactivate  Immediaetly stops the find-file process if it is active.

Methods

The FindFiles class implements the following methods:

AddLocation  Adds a new directory or file to the list of locations to scan.

Structure

The FindFiles object consists of the following public fields:

ConfirmScript  Refers to a confirmation script to be used when performing special operations.
Dest  Specifies a directory destination; required when using special operations.
ErrorScript  Refers to an error script that can be used for reporting errors to the user.
File  Refers to the most recently found file (used for callback purposes).
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 searched 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.

Method:AddLocation()
Short:Adds a new directory or file to the list of locations to scan.
Arguments:
STRING Location  Refers to the directory or file that you want to add.

The FindFiles class supports the scanning of multiple files and directories if you need to scan more than one location. To do this, call the AddLocation method for each location that you need to add. The path must be fully qualified so that the difference between files and directories is clear.

Note that if you set the Location field of the FindFiles object, any multiple locations that you have added with this method will be lost.

Result
ERR_Okay  The location was added to the list.
ERR_Args  Invalid arguments were specified.

Field:ConfirmScript
Short:Refers to a confirmation script to be used when performing special operations.
Type:STRING
Status:Get/Set

When using the move, copy or delete operation with a FindFiles object, you should set a confirmation script so that special instances can be handled, such as overwriting a file. The script in question will be expected to open a window and present a dialog box to the user. After opening the window, the script waits for the user to respond before returning to the FindFiles object (otherwise it will assume that the user has cancelled the operation). You can do this by using a Wait object.

The script can confirm the user response with the FindFiles object by writing to the Response field. Acceptable responses are YES, YESALL, NO and CANCEL, depending on the operation in use. Refer to the Response field for more information.


Field:Dest
Short:Specifies a directory destination; required when using special operations.
Type:STRING
Status:Get/Set

When using certain special operations such as the copy or move modes with a FindFiles object, you also need to set a destination path. The path must be fully qualified (ending with a trailing slash or colon as appropriate). If the destination path does not exist, then it may be automatically created by the system when you activate the find-file process.


Field:ErrorScript
Short:Refers to an error script that can be used for reporting errors to the user.
Type:STRING
Status:Get/Set

Field:File
Short:Refers to the most recently found file (used for callback purposes).
Type:STRING
Status:Get

The File field can be read during the find-file process if the callback feature is being used. Note that this field can refer to directories as well as files (directories can always be detected by checking for a slash or colon character at the end of the string).


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 wildcard values. Both the asterisk and question-mark characters are accepted as wildcards, 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 wildcards then the FindFiles object will scan for exact matches to the string you specify.


Field:Location
Short:The directory location to be searched 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 Text 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.