xDir Library - Event Diagrams

xDir implements a lot of useful callback procedures that work like events. These events allow you to control and customize file/folder search with xDir. The figures on this page explain how xDir raises its events.

Scheme of file and folder enumeration in xDir component

xDir starts file and folder enumeration from the folder specified in the RootFolder property when you call the ProcessFolder method. The component raises the IXDFoundItem_Proc event for each item that matches the specified search criteria. The ItemTypes property defines what kinds of file system items will be searched: only files, only folders, or both.

xDir checks every enumerated item using the following schema:

Filtering files and folders while enumerating with xDir

The component raises the IXDCancelEnum_Proc event before it checks the current item to provide you with the ability to cancel the search process. If you set the event's CancelEnum parameter passed by reference to True, xDir stops the enumeration immediately.

Then it raises the IXDItemCheck_Proc event you can use to implement your own search criteria and/or to notify the user about the currently checked item. The SkipItem parameter of the event allows you to ignore the further item testing.

If you have specified file or folder search criteria, xDir checks them for the current item. If the item matches the criteria, xDir raises the IXDFoundItem_Proc event for the item. If you have not specified any search criteria and simply use xDir to enumerate files or folders in all subfolders of the root folder, xDir raises this event for each found item.

xDir also periodically fires the IXDCancelEnum_Proc event while it is checking file contents in the case you perform context search. This event allows you to interrupt search without any noticeable delay for the user even while checking the contents of huge files.

The IXDItemCheck_Proc and IXDFoundItem_Proc events have extended versions with the "Ex" suffix. These events provide you with details about each checked item (file/folder attributes, creation date, file size, etc). Use these events if you need to check file/folder properties, but note that these events slow down application execution a little bit because xDir must retrieve and pass additional data to your app.

In the Pro version, xDir raises the special IXDPEnumCompleted_Proc event when the enumeration has completed. This event lets you know when the enumeration in a background process is finished.

Customizing xDir »