Class Documentation
FindFiles |
1.0 |
ID_FINDFILES |
Unspecified |
Tool/Command |
May 2001 |
Rocklyte Systems |
Rocklyte Systems (c) 2000-2001. 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="[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. |
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. |
|
|
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.
|
|