Class Documentation
FindFiles |
1.0 |
ID_FINDFILES |
Unspecified |
Tool/Command |
November 2003 |
Rocklyte Systems |
Rocklyte Systems (c) 2000-2003. All rights reserved. |
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="[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. |
Activate |
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.
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. |
|
|
AddLocation() |
Adds a new directory or file to the list of locations to scan. |
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.
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 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 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.
|
|