Using the SearchFolders Collection
Microsoft® Office XP
Summary: Describes how to programmatically search for files by using the SearchFolders collection, a member of the Microsoft Office 10.0 object library. (4 printed pages)
The FileSearch object in the Microsoft® Office 9.0 type library allows you to programmatically search for files matching criteria such as an author’s name, the type of file, the date that the file was last modified, and so on. Additionally, you can narrow the search criteria to known folders, and optionally, any of their subfolders. However, there is no method to search for folders if you don’t know their paths.
The addition of the SearchFolders collection to the FileSearch object in the Office 10.0 type library now allows you to programmatically search for files in multiple folders, even if you don’t know their paths. This article explores the new SearchFolders collection and provides an example of how to use this new collection by using Visual Basic® for Applications (VBA) code in Office XP.
To better understand how to programmatically build search criteria, Figure 1 below shows the various collections and objects that can be used, and Table 1 below describes the purpose of the SearchFolders collection and its child objects.
Figure 1. The FileSearch object model
Table 1. The SearchFolders collection and its child objects
|SearchFolders||Represents a collection of folders to be searched by using the FileSearch object. There is only one SearchFolders collection per application. You add one or more ScopeFolder objects to this single SearchFolders collection.|
|ScopeFolder||Represents a folder or subfolder that you want to add to the search. Each ScopeFolder object may contain zero or more ScopeFolders objects (which are collections of subfolders). If a ScopeFolder object does not have an accompanying ScopeFolders collection of child ScopeFolder objects, this means that the folder has no subfolders (however, the folder may contain files).|
|ScopeFolders||Represents a collection of one or more subfolders that belong to a parent ScopeFolder object.|
Other Search Objects
Some of the other collections and objects in the FileSearch object model (from Figure 1 above) that deserve brief mention are:
- FileTypes collection (new in Office XP)
Application.FileSearch.NewSearch). This is equivalent to the choices presented in the Results should be box in the Basic Search task pane (accessed by clicking Search on the File menu in all Office applications, except Microsoft Outlook®).
- FoundFiles collection
- PropertyTests collection
- SearchScopes collection (new in Office XP)
For more information about the methods and properties of the above collections, see Microsoft Office XP VBA Help.
The example that accompanies this article, available for download, demonstrates how the SearchFolders collection works. In the example, when the user selects some text within a Microsoft Word document and provides a folder name through a custom UserForm, the code searches the user’s local computer for any files that contain the selected text in any of the folders that match the folder name provided by the user. The code then uses the custom UserForm to report the list of matching files to the user.
Before your code searches for any files, it should clear any previous search criteria. The custom
ClearPreviousSearchFolders subroutine does this by removing any remaining SearchFolder objects from the single SearchFolders collection in the application. In addition, this subroutine sets the LookIn property to a blank string and calls the NewSearch method to reset all of the remaining search criteria to their default settings.
To search through all of the folders on a user’s computer, the custom, recursive
SearchForSubFolders subroutine is used. Without this subroutine, the search criteria would be limited to only the first level of folders on the user’s computer. The
SearchForSubFolders subroutine calls itself as many times as needed to traverse through the computer’s entire directory structure. Each time the subroutine finds a folder name that matches the folder name provided by the user, it calls the AddToSearchFolders method to add that folder to the single SearchFolders collection for the application.
After the entire directory structure of the user’s computer has been traversed, the code then is ready to search through the SearchFolders collection for any files containing the user’s selected text. The Execute method of the FileSearch object, in conjunction with the LookIn property and the Add method of the PropertyTests collection, returns a FoundFiles collection that contains the matching files, which are reported to the user by calling the custom
ReportResultsToUser subroutine to update and display the custom UserForm.
The SearchFolders collection allows you to programmatically search for files in multiple folders, even if you don’t know their paths beforehand. And because the SearchFolders collection is part of the FileSearch object, you can easily incorporate additional search criteria into your programmatic searching solutions.