EventFilter

A helper class for dealing with events that may be raised multiple times in rapid succession.

Introduction

Imagine a Windows Forms program mimicking the GUI of the Windows Explorer, where selecting a folder in the tree view on the left side will update the list of files on the right. A "quick'n dirty" implementation would handle the SelectedNodeChanged event of the TreeView control to update the file list, but a robust implementation that works nicely with slow media like CD/DVD or network drives should use a different approach.

When playing around with an actual instance of Windows Explorer and watching it more closely, you'll quickly notice that the file list is not updated immediately, but after a slight delay. You can use the keyboard in the tree view to move quickly from folder to folder, skipping folders you are not interested in. Only after you stay on a folder for a little while, the file list gets updated.

The approach of "wait until things have settled down a bit and then handle the last occurrence of an event" is pretty common in GUI development. The typical implementation uses a timer that is reset each time a new event is raised within a certain time interval, until the timer is finally allowed to elapse. Only at that time the event will actually be handled.

During development of a small hobby project called RemoteCanvas I got tired of taking care of timers, helper variables and event handlers over and over again, so I finally wrote a helper class acting as a "filter" for events.

How to Use the EventFilter Class

• Declare a member variable to hold an instance of the EventFilter class, with an event argument type matching that of the event to be filtered:
  private EventFilter<EventArgs> _filter
    = new EventFilter<EventArgs>();.
• Hook up the HandleOriginalEvent method to the original event of the control. There's no great design time support for this, so you have to do that manually:
  myControl.SelectedIndexChanged += _filter.HandleOriginalEvent;
• Connect the FilteredEventRaised event to your event handler:
  _filter.FilteredEventRaised += MyHandler;
• That's it!

A Final Note

It is important to be aware when to use the EventFilter class, and when not. Not every event that may be raised multiple times (threatening to clog up the GUI) actually qualifies for the time window approach. In the Windows Explorer example above, ignoring the selection of folders that are skipped the very next moment does not really harm the correctness of what is displayed in the GUI. In other situations, ignoring an event may have serious consequences.

License and Terms of Use

Copyright © 2007 Roland Weigelt (mail@roland-weigelt.de)

The author grants to you a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to use, copy, modify, and distribute this source code, or portions hereof, for any purpose, including commercial applications, subject to the following restrictions:

1. This software is provided 'as-is', without any express or implied warranty. In no event will the author be held liable for any damages arising from the use of this software. If you do not agree with this, or if local laws do not allow such an exclusion of liability, you must not use this software.
2. When publishing this source code or any altered version (including, but not limited to, publication in books or magazines, on web sites, or as part of an open source project):
   • The origin of this source code must not be misrepresented; you must not claim that you wrote this software.
   • Altered versions of the source code must be plainly marked as such and must not be misrepresented as being the original source code.
   • While additional Copyright notices may be added, this Copyright notice must not be removed.
3. When using this software, or portions hereof, without publishing the source code (as part of "closed-source software"), this Copyright notice may be abbreviated to the following text:
   
   Based on code written by Roland Weigelt (mail@roland-weigelt.de).
   Used with permission, acknowledging that the original source code
   was provided "as-is", without any express or implied warranty,
   and under the condition that Roland Weigelt will not be held liable
   for any damages from the use of this software.