Copyright© Kambiz R. Khojasteh. All rights reserved.
Get future component updates from http://www.delphiarea.com.

DESCRIPTION

TFindFile is a non-visual component, which can be used for locating files or folders in the file system and directory tree with an extensive set of criteria. TFindFile locates files or folders by name, location, size, creation date and time, last modification date and time, last access date and time, or content of the file. In addition, the search process can use a separate thread.

PROPERTIES

• Criteria: TSearchCriteria
  Contains the search criteria.
  
  
  • Files: TFileCriteria
    Contains file and folder criteria.
    
    
    • Filename: String
      Specifies the target filename masks separated by semicolon.
      
      
    • Location: String
      Determines the target folders separated by semicolon.
      
      
    • Included: TStringList
      Contains list of target file paths, which filename part of the paths can contain wildcards. You may use this property alternative to or besides Filename and Location properties.
      
      
    • Excluded: TStringList
      Contains list of files that should be excluded from the search result. You can use wildcards for Drive and filename.
      
      Example:
      
      

      *.txt		Ignores all text files in any folder and drive
      C:\*.txt		Ignores all text files in root of drive C:
      ?:\*.txt		Ignores all text files in root of any drive
      C:lib\*.txt		Ignores all text files in lib subfolder of any folder of drive C:
      lib\*.txt		Ignores all text files in lib subfolder of any folder of any drive
      C:\lib\*.txt		Ignores all text files in lib subfolder of root of drive C:
      *:\lib\*.txt		Ignores all text files in lib subfolder of root of any drive

      
      
• Subfolders: Boolean
  If set to true, subfolders of the target folders specified in Location and Included properties will be included in the search. Alternatively, you may use < (less than) and > (greater than) symbols in the beginning of a folder to bypass this property. When the name of a folder begins with < (less than) character, regardless of the value of Subfolders property, the component never search in the subfolders of the folder. Vice versa, if the name of a folder begins with > (greater than) character, subfolders of the folder always will be included in the search.
  
  
• MinLevel: Word
  Determines the minimum directory level from the base folder for the target files. Set this property to zero if you do not need this limit.
  
  
• MaxLevel: Word
  Determines the maximum directory level from the base folder for the target files. Set this property to zero if you do not need this limit.
  
  
• Attribute: TAttributeCriteria
  Contains file attributes criteria.
  
  
• Attributes: TFileAttributes
  TFileAttributes = set of (ffArchive, ffReadonly, ffHidden, ffSystem, ffDirectory)
  Determines the desired attributes for the target file(s). Alternatively, you may use Flags property.
  To search for file(s) with only normal attribute, set Attributes property to empty set.
  
  

ffArchive		Archive files are acceptable
ffReadonly		Read-only files are acceptable
ffHidden		Hidden files are acceptable
ffSystem		System files are acceptable
ffDirectory		Directories are acceptable



• Flags: Integer
  Determines the desired attributes for the target file(s) as bitwise. Alternatively, you can use Attributes property.
  
  
• ExactMatch: Boolean
  If set to true, file will be accepted if its attributes are exactly same as the attributes specified in Attributes or Flags properties. When this property is set to false, the target file should have one of specified attributes to be accepted.
  
  Example:
  
  

  Attributes := [ffReadonly, ffHidden];
  ExactMatch := False;	{ TFindFile locates for files by Read-only OR Hidden attribute bit set. }
  ExactMatch := True;	{ TFindFile locates for files by Read-only AND Hidden attribute bit set. }

  
  
• Size: TSizeCriteria
  Contains file size criteria.
  
  
• Min: DWORD
  Determines the lower range of the file size. Set this property to zero if you do not need this limit.
  
  
• Max: DWORD
  Determines the upper range of the file size. Set this property to zero if you do not need this limit.
  
  
• TimeStamp: TDateTimeCriteria
  Contains file date and time criteria.
  
  
• CreatedAfter: TDateTime
  Determines the lower range of the file creation date and time. To ignore lower date limit, set date part to zero and to ignore lower time limit, set time part to zero.
  
  
• CreatedBefore: TDateTime
  Determines the upper range of the file creation date and time. To ignore upper date limit, set date part to zero and to ignore upper time limit, set time part to zero.
  
  
• ModifiedAfter: TDateTime
  Determines the lower range of the file last modified date and time. To ignore lower date limit, set date part to zero and to ignore lower time limit, set time part to zero.
  
  
• ModifiedBefore: TDateTime
  Determines the upper range of the file last modified date and time. To ignore upper date limit, set date part to zero and to ignore upper time limit, set time part to zero.
  
  
• AccessedAfter: TDateTime
  Determines the lower range of the file last accessed date and time. To ignore lower date limit, set date part to zero and to ignore lower time limit, set time part to zero.
  
  
• AccessedBefore: TDateTime
  Determines the upper range of the file last accessed date and time. To ignore upper date limit, set date part to zero and to ignore upper time limit, set time part to zero.
  
  
• Content: TContentCriteria
  Contains criteria about the file(s) content.
  
  
• Phrase: String
  Specifies the text that should be located in the content of the file(s). Set this property to empty if you do not need this option.
  
  
• IgnoreCase: Boolean
  If set to true, the component performs a case insensitive search to locate the phrase inside the file.
  
  
• WholeWord: Boolean
  If set to true, the component searches for whole words only.
  
  
• Aborted: Boolean (Read-only)
  When is true, indicates that the last search has been aborted.
  
  
• Busy: Boolean (Read-only)
  When is true a search is running and it is not finished yet.
  
  
• CurrentLevel: Word (Read-only)
  Determines on which directory level search is running now.
  
  
• Threaded: Boolean
  If set to true, the component a separated thread for its process.
  
  
• ThreadPriority: TThreadPriority
  Determines priority of the thread when component is in threaded mode.

METHODS

• procedure Execute
  Starts the search process.
  
  
• procedure Abort
  Aborts the search and sets the aborted property to true. Calling Abort method does not mean that it halts the search immediately. You have to use OnSearchFinish event to know exactly when the search is stopped.

EVENTS

• OnFileMatch: TFileMatchEvent
  TFileMatchEvent = procedure (Sender: TObject; const Folder: String; const FileInfo: TSearchRec) of object
  NOTE: In threaded mode, the event handler calls by the search thread, not the main VCL thread.
  This event will be triggered when a file matches with the search criteria. "Folder" specifies the location of the file and "FileInfo" contains the file information details (Name, Size, Time, Attr, and...).
  
  
• OnFolderChange: TFolderChangeEvent
  TFolderChangeEvent = procedure (Sender: TObject; const Folder: String; var IgnoreFolder: TFolderIgnore) of object
  TFolderIgnore = (fiNone, fiJustThis, fiJustSubfolders, fiThisAndSubfolders)
  NOTE: In threaded mode, the event handler calls by the search thread, not the main VCL thread.
  This event helps you to monitor the current search location and will be triggered when component begins to search in a new folder. To bypass a folder of its subfoders, user "IgnoreFolder" parameter as follow:
  
  

  fiNone (Default)		Search continues into Folder and its subfolders
  fiJustThis		Folder will be ignored but search continies into its subfolders
  fiJustSubfolders		Folder will be searched but its subfolders will be ignored
  fiThisAndSubfolders		Folder and its subfolders will not be searched

  
  
• OnSearchBegin: TNotifyEvent
  Actually, when Execute method is called, the component prepares the search criteria and after that begins the search. This event is just triggered when the search process is about to begin.
  
  
• OnSearchFinish: TNotifyEvent
  This event is triggered when search is finished. Search can be finished because of either completion or calling Abort method..
  
  
• OnSearchAbort: TNotifyEvent
  This event is just triggered after calling Abort method. Usually, there is a short delay between calling Abort and stopping the process, especially when component is working in threaded mode.
  

HISTORY

• 3.50 (July 26, 2005)
  - The ANSI string matching problem fixed.
  
  
• 3.40 (May 20, 2004)
  - The new property WholeWord added to the content criteria.
  - The file content search algorithm speeded up.
  - Now, in threaded mode, the code for both OnFileMatch and OnFolderChange event handlers run inside the search thread.
  - Some minor tweaks and bug fixes.
  
  
• 3.32 (May 7, 2004)
  - Bug in the file content search algorithm fixed.
  - Some minor tweaks.
  
  
• 3.31 (April 23, 2004)
  - Bug in comparing file's attributes fixed (Thanks to Sohnel-Software - SUPPORT).
  
  
• 3.30 (April 10, 2004)
  - UNC path support added (Thanks to Roman Olexa).
  - Bug in comparing file's attributes fixed (Thanks to Sohnel-Software - SUPPORT).
  
  
• 3.22 (March 21, 2003)
  - Bug related to Min/Max folder level criteria fixed (Thanks to Maurizio Mutti).
  
  
• 3.21 (January 13, 2003)
  - Bug at finding index of a folder in the list of target folders fixed (Thanks to Fritz).
  
  
• 3.20 (November 24, 2002)
  - New read-only property CurrentLevel added.
  - Parameter definition of OnFolderChange event changed.
  
  
• 3.10 (November 17, 2002)
  - New properties MinLevel and MaxLevel added to file criteria (Thanks to Nitin Chandra).
  
  
• 3.02 (August 25, 2002)
  - Some minor changes in interface of classes.
  
  
• 3.01 (August 1, 2002)
  - The code of text lookup function changed.
  - The bug in file attribute comparison fixed.
  
  
• 3.00 (May 4, 2002)
  - The new version does not support 16bit Delphi.
  - This version is not compatible with the older versions. The name and structure of properties and events has changed.
  - The search process is faster, particularly when criteria contains multiple file masks or component is searching for a text inside files.
  - Now, included file list accepts wildcards.
  
  
• 2.30 (March 7, 2002)
  - The bug on look up for folders that their names begin with a dot fixed (Thanks to Frederik Decoster).
  - Now, the FileName property can accept multiple files.
  
  
• 2.22 (December 26, 2001)
  - A bug on 16bit version fixed.
  
  
• 2.21 (April 16, 2000)
  - A minor bug fixed.
  
  
• 2.20 (April 15, 2000)
  - All reported bugs fixed.
  
  
• 2.11 (March 20, 2000)
  - In the previous version of the component, TFindFile ignores the files with normal attribute. In the current version the bug is fixed.
  
  
• 2.10 (March 18, 2000)
  - Two new properties IncludeFiles and ExcludeFiles added to the component.
  
  
• 2.00 (February 25, 2000)
  - ffNormal was a meaningless attribute and removed. When no any attribute is selected, it means Normal.
  - Files can be found by specifying the range of size, creation date and time, last modified date and time, last accessed date and time, and containing text.
  - Component improved to accept all or any of the selected attributes for the file.
  - Now, search location can contain multiple folders.
  
  
• 1.10 (February 1, 2000)
  - Now the search process can be done in a separated thread (32bit Only).
  - Threaded, ThreadPriority, and Busy properties and OnComplete event added.
  
  
• 1.00 (January 14, 2000)
  - Initial release.
  

LICENSE

TFindFile component is freeware. You may copy component's files AS LONG AS YOU COPY ALL OF THEM. If you want to change the source code in order to improve the component's features, performance, etc. please send me the new source code so that I can have a look at it. The changed source code should contain descriptions what you have changed, and of course your name. The only thing you MAY NOT CHANGE is the ORIGINAL COPYRIGHT INFORMATION.

DISCLAIMER

TFindFile is provided "AS IS" without any warranty of any kind, either express or implied. The entire risk as to the quality and performance of the software is with you. The author is NOT liable for any DAMAGES resulting from the use and misuse of the component, especially he is NOT liable for DAMAGES that were caused BY ANY VERSION WHICH HAS NOT BEEN PROGRAMMED BY THE AUTHOR HIMSELF.