Contents

  1. Getting Started
    1. Installing
  2. Usage
    1. API
    2. Classes
    3. Guidelines
    4. Demonstration

Getting Started

ThreadSafeControls is incredibly easy to add to any software project. To start, simply download the latest stable DLL or the source code.

Installing

All you need to do to start using ThreadSafeControls is add a reference to the downloaded DLL to your Visual Studio (or SharpDevelop, or MonoDevelop, etc.) project. Alternately, if you downloaded the source code, you can add the ThreadSafeControls.csproj file to your solution.

Usage

Using ThreadSafeControls couldn't be much easier. In any code in which you want to access some Windows Forms controls in a thread-safe manner, all you need to do is:
  1. Add using ThreadSafeControls; to the top of your code file.
  2. Access any GUI control you like by wrapping it in a thread-safe instance, as follows:

var threadSafeTextBox = myTextBox.AsThreadSafe();

Note that the AsThreadSafe extension method is available on all controls implemented in the project so far (see Classes). This does not include all Windows Forms controls (yet). However, you can wrap any control in a thread-safe wrapper using the AsThreadSafeControl extension method:

var threadSafeControl = myControl.AsThreadSafeControl();

The difference between the return values of these two functions is that AsThreadSafe provides a more specialized instance, offering fuller functionality, e.g., ThreadSafeTextBox (which has most of the same members as TextBox), ThreadSafeListView (which has most of the same members as ListView), etc. The return value of AsThreadSafeControl offers limited functionality that is applicable to all classes deriving from System.Windows.Forms.Control, such as Size, ForeColor, and so on.

API

Calling AsThreadSafe or AsThreadSafeControl on any Windows Forms control will return an instance of a class offering much the same functionality as the underlying control. For instance, a ThreadSafeListView includes an Items property which in turn provides access to ThreadSafeListViewItem objects, which can manipulate the underlying ListView's items; a Columns property which provides access to ThreadSafeColumnHeader objects, capable of manipulating the underlying ListView's columns; and so on.

Because of the way the classes in ThreadSafeControls have been designed--as wrappers directly accessing the functionality of the underlying controls--they provide predictable and intuitive behavior totally consistent with what someone with experience in Windows Forms development would expect.

Here is a somewhat more in-depth example:

// we're going to split these words up into columns
var words = new string[] {"dog", "cat", "mouse", "crocodile"};

// need to know how many columns we'll need
int maxWordLength = words.Select(w => w.Length).Max();

// get an instance of a ThreadSafeListView
// we'll use this to access myListView from here on out
var threadSafeListView = myListView.AsThreadSafe();

// ensure we're starting from 0
threadSafeListView.Columns.Clear();

// create enough columns to display each letter of each word
while (threadSafeListView.Columns.Count < maxWordLength)
    threadSafeListView.Columns.Add("column" + threadSafeListView.Columns.Count.ToString());

// the last column will display the length of the word
int lastColumnIndex = threadSafeListView.Columns.Add("Length").Index;

// create a ListViewItem for each word and add this
foreach (var word in words) {
    var threadSafeItem = threadSafeListView.Items.Add(new ListViewItem(word[0].ToString()));
    
    for (int i = 1; i < word.Length; ++i)
        threadSafeItem.SubItems.Add(word[i].ToString());

    // the word is finished; now we add blank subitems until
    // arriving at the Length column at the end
    while (threadSafeItem.SubItems.Count < lastColumnIndex)
        threadSafeItem.SubItems.Add(string.Empty);

    threadSafeItem.SubItems.Add(word.Length.ToString());
}

Classes

At present, the following Windows Forms controls have thread-safe wrappers available in ThreadSafeControls via the AsThreadSafe extension method. Remember that all other controls not listed below may still be accessed with thread-safe wrappers via the AsThreadSafeControl extension method.
  • ThreadSafeButton
  • ThreadSafeCheckBox
  • ThreadSafeCheckedListBox
  • ThreadSafeComboBox
  • ThreadSafeDateTimePicker
  • ThreadSafeListBox
  • ThreadSafeListView
    • ThreadSafeColumnHeader
    • ThreadSafeListViewItem
      • ThreadSafeListViewItem.ListViewSubItem
  • ThreadSafeNumericUpDown
  • ThreadSafeProgressBar
  • ThreadSafeRadioButton
  • ThreadSafeTextBox
  • ThreadSafeTreeView
    • ThreadSafeTreeNode

Guidelines

It's important to be aware that there are limitations to what Windows Forms applications are capable of doing. Accessing the GUI from a background thread is one thing; if you find that you are doing so from many threads at once, you may find that you are stressing the capabilities of the GUI itself and are likely to encounter issues with the UI rendering properly.

In addition, manipulating collections in a thread-safe manner (e.g., reading to/writing from a collection safely from multiple threads) is a different beast altogether. ThreadSafeControls provides a rudimentary API for doing this in simple scenarios: SynchronizedObjectCollection. Most of the collections in ThreadSafeControls, such as ThreadSafeListBox.ObjectCollection, ThreadSafeListView.ListViewItemCollection, etc. provide a method that returns a SynchronizedObjectCollection wrapper, called Synchronized:

var threadSafeListBox = myListBox.AsThreadSafe();
var items = threadSafeListBox.Items.Synchronized();

This class is provided for convenience only; I recommend you use it only in moderation.


A demonstration of ThreadSafeControls is available in the form of a Windows Forms application called ThreadSafeControlsTest in the Visual Studio 2008 solution provided with the source code.

To simply download the binary and run it, visit the Downloads page.

Last edited May 4, 2010 at 2:10 AM by danieltao, version 8

Comments

No comments yet.