David Kline : GUI

Quick Tip: Getting the Collection of Checked ListView Items

DavidKlineMS — Mon, 18 Jun 2007 21:09:00 GMT

Have you ever created a ListView control and wanted to get the collection of items that the user has checked? While I was working on my demo for MEDC, that was one of the things that I needed to be able to do. If I were writing my application for the .NET Framework, I would get the collection of items via the ListView.CheckedItems property. When I looked up ListView in the MSDN documentation, I found that the CheckedItems property is not supported on the .NET Compact Framework. As a result, I was going to need to create the collection myself. Or was I?

Since the application that I was writing was a demonstration of the cool new features of .NET Compact Framework version 3.5, I decided to try my hand a using Language Integrated Query, specifically LINQ to Objects. The resulting code was small, worked well and was quite easy to read. Let's take a look at what I wrote.
public static List<ListViewItem> GetCheckedListViewItems(ListView lv) { List<ListViewItem> checkedItems = (from ListViewItem lvi in lv.Items where (true == lvi.Checked) select lvi).ToList(); return checkedItems; }
The method above is based on my Lunch Launcher demo application, as shown during the What's New in .NET Compact Framework version 3.5 session that I delivered at MEDC 2007 last month. How does it work? First, we specify that we are interested in the ListViewItem objects contained within the ListView.Items property.
from ListViewItem lvi in lv.Items
Next, we define the condition under which we are interested in the item, in our case when the item has been checked by the user.
where (true == lvi.Checked)
Then we select the item.
select lvi
Lastly, we call the ToList method to have the selected items returned to us as a List<ListViewItem>.

Pretty neat and much nicer to read than a foreach loop. If you have installed the beta of .NET Compact Framework version 3.5, give LINQ a try and see how it can make your applications easier to write.

Enjoy!
-- DK

[Edit: fix formatting]

Disclaimers:
This posting is provided "AS IS" with no warranties, and confers no rights.
The information contained within this post is in relation to beta software. Any and all details are subject to change.

Separating Application Logic and Data Presentation layers

DavidKlineMS — Fri, 06 Oct 2006 00:57:00 GMT

I'm a big advocate of separating an application's logic from it's user interface. By keeping the logic separate from the data presentation layer (UI), it becomes easy to swap out either component with minimal impact on the other. In addition to ease of replacing components, keeping the user interface separate from the application logic avoids blocking the UI during expensive operations.

Today, I'm going to revisit the .NET Compact Framework WebCrawler sample from Visual Studio 2005 and show how it uses event handlers to allow the application logic (Crawler class) to communicate with the user interface. The source code for the WebCrawler sample can be downloaded from here.

Simple Status Notification - EventHandler
For simple notifications requiring no data, such as the CrawlFinishedEvent in the WebCrawler sample, an event handler is defined in the application logic class.

public event EventHandler CrawlFinishedEvent;

When the application logic wishes to inform clients that the event has occurred, it checks to see if there are any registered event handlers and, if so, sends the notification.

if (null != CrawlFinishedEvent)
{
    CrawlFinishedEvent(this, EventArgs.Empty);
}

The UI class (MainForm in the WebCrawler) registers for the event.

this.crawler.CrawlFinishedEvent += new EventHandler(HandleCrawlFinishedEvent);

The form implements a method to handle the event.

/// <summary>
/// Process CrawlFinished events
/// </summary>
private void HandleCrawlFinishedEvent(object sender, EventArgs e)
{
    // update the user interface as appropriate
}

Sending Data In The Notification - Creating a Custom EventHandler
If the notification requires some data data, such as the CurrentPageEvent in the WebCrawler sample, a custom event handler delegate will need to be defined.

public delegate void CurrentPageEventHandler(object sender, CurrentPageEventArgs e);
public event CurrentPageEventHandler CurrentPageEvent;

Notice the CurrentPageEventArgs argument -- this is where the custom data is placed. In the WebCrawler sample, the CurerntPageEventArgs is defined as

/// <summary>
/// Class providing the current page address to the CurrentPageEvent handler
/// </summary>
public class CurrentPageEventArgs : EventArgs
{
    private string pageAddressValue;
    /// <summary>
    /// The address of the current page(ex: http://www.microsoft.com)
    /// </summary>
    public string PageAddress
    {
        get
        {
            return this.pageAddressValue;
        }
    }

    /// <summary>
    /// Constructor
    /// </summary>
    /// <param name="page">
    /// The address of the current page
    /// </param>
    public CurrentPageEventArgs(string page)
    {
        this.pageAddressValue = page;
    }
}

As with the above simple status notification example, when the application logic wishes to inform clients that the event occurred, it checks registrations and sends the notification, passing the data in the event arguments.

if (CurrentPageEvent != null)
{
    CurrentPageEvent(this,  new CurrentPageEventArgs(str));
}

Registering for the custom event is similar to the above simple notification example.

this.crawler.CurrentPageEvent += new Crawler.CurrentPageEventHandler(HandleCurrentPageEvent);

The implementation of the event handler method needs to match the custom event handler delegate.

/// <summary>
/// Process CurrentPage events
/// </summary>
private void HandleCurrentPageEvent(object sender, CurrentPageEventArgs e)
{
    // update the user interface as appropriate
}

By building and running the WebCrawler sample under the Visual Studio 2005 debugger, you can watch the event notifications and how the sample handles updating user interface elements in a multi-threaded application.

Enjoy!
-- DK

Disclaimer(s):
This posting is provided "AS IS" with no warranties, and confers no rights.

Programmatically Rotating the Screen using the .NET Compact Framework

DavidKlineMS — Tue, 18 Apr 2006 03:05:00 GMT

Several months back, I wrote about how to determine whether or not a device supported screen rotation. This post prompted the question of how to programmatically rotate the device..

The snippets below check the device's current display orientation. If portrait (Angle0), the orientation is changed to landscape (Angle90). If the device has any orientation other than Angle0, it is changed to portrait.

C#

//--------------------------------------------------------------------- 
//THIS CODE AND INFORMATION ARE PROVIDED AS IS WITHOUT WARRANTY OF ANY 
//KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE 
//IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A 
//PARTICULAR PURPOSE. 
//---------------------------------------------------------------------
using System;
using Microsoft.WindowsCE.Forms;

class Program
{
    static void Main()
    {
        if(SystemSettings.ScreenOrientation == ScreenOrientation.Angle0)
        {
            // if portrait, change to landscape
            SystemSettings.ScreenOrientation = ScreenOrientation.Angle90;
        }
        else
        {
            // change to portrait
            SystemSettings.ScreenOrientation = ScreenOrientation.Angle0;
        }
    }
}

'--------------------------------------------------------------------- 
'THIS CODE AND INFORMATION ARE PROVIDED AS IS WITHOUT WARRANTY OF ANY 
'KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE 
'IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A 
'PARTICULAR PURPOSE. 
'---------------------------------------------------------------------
Imports Microsoft.WindowsCE.Forms
Module Module1 

    Sub Main()
        If (SystemSettings.ScreenOrientation = ScreenOrientation.Angle0) Then 

            ' if portrait, change to landscape
            SystemSettings.ScreenOrientation = ScreenOrientation.Angle90 

        Else 

            ' change to portrait
            SystemSettings.ScreenOrientation = ScreenOrientation.Angle0 

        End If 
    End Sub 

End Module

For more information on this and other cool settings provided by the Microsoft.WindowsCE.Forms namespace, check out the MSDN documentation for SystemSettings.

Enjoy!
--DK

Disclaimer(s):
This posting is provided "AS IS" with no warranties, and confers no rights.

Chris Lorton on alpha blending with the .NET Compact Framework

DavidKlineMS — Sun, 09 Apr 2006 04:19:00 GMT

Ever wonder how to write applications with really cool, alpha blended user interfaces? If so, take a walk over to Chris Lorton's weblog. There, he has examples of using the .NET Compact Framework and Windows Mobile 5.0 to do just that. He covers using the AlphaBlend function and the IImage interface.

Enjoy!
-- DK

Disclaimer(s):
This posting is provided "AS IS" with no warranties, and confers no rights.

Why do I get a NotSupportedException when updating a TextBox?

DavidKlineMS — Fri, 10 Mar 2006 09:58:00 GMT

Have you ever been working on an application and found that when the code tries to update the Text property of a TextBox control that you encounter a NotSupportedException? Have you seen this with a Label, ListBox, Button or another control? If you have, the application is attempting to update the control from a worker thread instead of the thread that created the control (typically the main application thread). Today I would like to examine why this happens.

On version 1 of the .NET Compact Framework, applications which attempted to update their user interface from a worker thread would typically hang. Having an application hang is an unpleasant user experience.

With the release of version 2, the .NET Compact Framework will throw a NotSupportedException in the scenarios that would have previously lead to an application hang. While exceptions are still not the best experience, they are far better than an application hanging. Since the .NET Compact Framework is specifically throwing in this scenario, the application developer will find the issue every time a control is updated from a worker thread and the developer can fix the code.

If your device has had the string resource assemblies installed, the Message property of the NotSupportedException will contain an explanation for why the exception was thrown.

Control.Invoke must be used to interact with controls created on a separate thread.

Examples
Let's take a look at a couple of examples of what I have been talking about.

The first snippet illustrates a simple thread delegate that attempts to update a TextBox control's Text property directly.

private void TestThread() {     // update our status     this.textBox1.Text = "Thread running";     // run until told to stop     while(!this.stopNow)     {         // simulated processing         Thread.Sleep(1000);     }     // update our status     this.textBox1.Text = "Thread stopped"; }

The above example will cause a NotSupportedException to be thrown on the line:

this.textBox1.Text = "Thread running";
Note also that the last line in the method will also cause a NotSupportedException to be thrown. Let's take a look at a fix.

The first step to fix our snippet is to define a delegate that takes a String argument so that we can pass our status message.

private delegate void UpdateStatusDelegate(String message);
Next, we add an implementation of a method that matches our delegate's signature.

private void DoUpdate(String message) {     if(this.InvokeRequired)     {         // we were called on a worker thread         // marshal the call to the user interface thread         this.Invoke(new UpdateStatusDelegate(DoUpdate),                     new object[] { message });         return;     }     // this code can only be reached     // by the user interface thread     this.textBox1.Text = message; }
And, finally, we modify our thread method to call DoUpdate and pass the desired status message.

private void TestThread() {     // update our status     DoUpdate("Thread running");     // run until told to stop     while(!this.stopNow)     {         // simulated processing         Thread.Sleep(1000);     }     // update our status     DoUpdate("Thread stopped"); }
Now, let's take a look at how this works. When the thread method (TestThread) calls DoUpdate, the first thing that happens is that the Form's InvokeRequired method is called. InvokeRequired compares the current thread with the thread which created the Form. Since the threads are different (we called DoUpdate on a worker thread), we enter the if block.

Next, DoUpdate calls the Form's Invoke method and passes itself as a new instance of our UpdateStatusDelegate with the message argument encapsulated in an Object array. Invoke then calls the DoUpdate method on the thread which created the Form. After the call to Invoke completes, DoUpdates returns. This return step is necessary so that the remainder of the method (the TextBox update) does not get called by the worker thread.

When DoUpdate is called by Invoke, it again calls the Form's InvokeRequired method. This time, the call was made on the thread which created the Form, we skip the if block and the TextBox is updated.

Please note that for the above to work on version 1 of the .NET Compact Framework, you will need to write and call your own custom InvokeRequired method. I talk about one implementation for InvokeRequired in my post on the Visual Studio .NET 2003 Web Crawler sample.

Hidden threads
Sometimes, and application can be multi-threaded without realizing it. When using the asynchronous programming model, your application's callback methods are called on a worker thread created and managed by the .NET Compact Framework runtime. It is important to keep this in mind when using asynchronous methods and be sure that your user interface is updated only by the UI thread.

When I'm using an asynchronous callback method, I also write a delegate that I Invoke as appropriate. This ensures that my user interface updates occur in the correct context.

Enjoy!
-- DK

[Edit: update snippet formatting]

Disclaimer(s):
This posting is provided "AS IS" with no warranties, and confers no rights.

Using a UserControl to combine related controls

DavidKlineMS — Thu, 24 Nov 2005 06:42:00 GMT

Have you been writing an application where you needed to relate multiple controls to each other (ex: a Button and a TextBox) where multiple sets of the related controls are required?

The scenario
I have an application where I needed to have multiple Button controls which I needed to perform the same task. This task was to read the value of a specific TextBox's Text property and call a method using that data. My goals were to minimize redundant code and to not be required to create a new Click event handler whenever I added a TextBox / Button control pair to my form.

One of the best things about the Button (and other controls) click event is that your event handler is sent the object that generated the event in the sender argument. I originally planned (and wrote) my click event handler such that it identified the sender (Button) and then examined each of its parent's controls to find the matching TextBox control. After some trial and error, which underscored the fragility of my algorithm, I got the code working. The code wasn't pretty, nor did it perform very well. I could live with the code not being super elegant (heavy commenting helped) but I didn't like the performance characteristics (it didn't scale well) and the reliance upon adhering to specific naming conventions was a major issue.

One solution
Since I was writing my application using version 2 of the .NET Compact Framework, I decided to re-implement my solution as a UserControl. UserControls are a great way to combine multiple UI controls such that the container (an application's form) can treat them as one unit with a unified public interface. In a UserControl, you can specify how the default control properties (ex: Text) behave and define additional properties that make sense for your control.

And best of all, they are very easy to write using Visual Studio 2005.

My main goal in implementing this control was to make the control's click event be synonymous with the child Button's click event. An alternative would be to expose the Button's click event as a new event (ex: ActionButtonClick) that a form could handle -- I have an example of this alternative following this discussion.

First, I added a new UserControl to my project (you can also create a separate project for your control). Next, I used the designer to add the controls that will make up my UserControl. After setting the properties of each child control (ex: Anchor settings), I was ready to add the code. The example below implements a very simple Button / TextBox pair with a Label.

Please note that this is not a complete implementation. I have left out the control designer's generated code (ex: InitializeComponent).

//--------------------------------------------------------------------- 
//THIS CODE AND INFORMATION ARE PROVIDED AS IS WITHOUT WARRANTY OF ANY 
//KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE 
//IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A 
//PARTICULAR PURPOSE. 
//---------------------------------------------------------------------
using System;
using System.ComponentModel;
using System.Drawing;
using System.Windows.Forms;

public partial class LinkedButtonAndTextBox : UserControl
{
    /// <summary>
    /// This variable helps to ensure that the button's click
    /// is the only click we forward to the form
    /// </summary>
    private Boolean myButtonWasClicked;

    /// <summary>
    ///  The value of the Text property of the child Label control
    /// </summary>
    public String Label
    {
        get{ return this.label.Text; }
        set{ this.label.Text = value; }
    }

    /// <summary>
    ///  The value of the Text property of the child TextBox control
    /// </summary>
    public override String Text
    {
        get{ return this.textBox.Text; }
        set{ this.textBox.Text = value; }
    }

    /// <summary>
    ///  The value of the Text property of the child Button control
    /// </summary>
    public override String ButtonText
    {
        get{ return this.button.Text; }
        set{ this.button.Text = value; }
    }

    /// <summary>
    ///  Control constructor
    /// </summary>
    public LinkedButtonAndTextBox()
    {
        // by default, the button has not been clicked
        this.myButtonWasClicked = false;

        // designer generated method to
        //  create and add child controls and to set
        //  properties
        InitializeComponent();
    }

    /// <summary>
    /// Event handler called when our button is clicked.
    ///  This event handler method was registered using the Visual Studio control designer.
    /// </summary>
    /// <param name="sender">The object on which the click occurred</param>
    /// <param name="e">EventArgs describing the event</param>
    private void button_Click(Object sender, EventArgs e)
    {
        // indicate that the click event originated from our button's
        //  click handler
        this.myButtonWasClicked = true;

        // click the control (call LinkedButtonAndTextBox.OnClick)
        this.OnClick(e);
    }

    /// <summary>
    /// Raise the click event 
    /// </summary>
    protected override void OnClick(EventArgs e)
    {
        // did the click originate from our button control?
        if(this.myButtonWasClicked)
        {
            // yes
            
            // reset the button clicked flag
            this.myButtonWasClicked = false;

            // call the our base class's OnClick method (UserControl.OnClick)
            base.OnClick(e);
        }
}

How it works
The key to this solution is the use of the myButtonWasClicked member variable. By setting the value to true in the button_Click method before calling OnClick, the control knows to call any registered click handlers (by calling the base classes implementation of OnClick). If the value is false, the click event is not forwarded to the registered click handlers.

Applications can register interest in your click event by adding a delegate to the event handler chain:

LinkedButtonAndTextBox btnTextBox1 = new LinkedButtonAndTextBox():
btnTextBox1.Click += btnTextBox_Click:

Visual Studio 2005 will add code similar to the above lines when you add the control to a form and double-click on it for the first time. An event handler method will also be generated on your behalf.

Another solution
Earlier I mentioned that an alternative solution would be to not override the control's OnClick method and, instead, to add a specific click event for the button. We'll call this new event ActionButtonClick. Rather than reiterate a good deal of the above example, I am going to show just an implementation for the ActionButtonClick event.

//--------------------------------------------------------------------- 
//THIS CODE AND INFORMATION ARE PROVIDED AS IS WITHOUT WARRANTY OF ANY 
//KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE 
//IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A 
//PARTICULAR PURPOSE. 
//---------------------------------------------------------------------
using System;
using System.ComponentModel;
using System.Drawing;
using System.Windows.Forms;

public partial class LinkedButtonAndTextBox : UserControl
{
    //*** code omitted for size and clarity ***

    /// <summary>
    /// The event handler that forms can register to
    /// receive notification that our button has been
    /// clicked.
    /// </summary>
    public event EventHandler ActionButtonClick;

    /// <summary>
    /// Event handler called when our button is clicked
    ///  This event handler method was registered using the Visual Studio control designer.
    /// </summary>
    /// <param name="sender">The object on which the click occurred</param>
    /// <param name="e">EventArgs describing the event</param>
    protected override void button_Click(Object sender, EventArgs e)
    {
        // raise the event
        this.OnActionButtonClick(e);
    }

    /// <summary>
    /// Raise the ActionButtonClick event
    /// </summary>
    protected virtual void OnActionButtonClick(EventArgs e)
    {
        // check to see if an event handler has been registered
        if(this.ActionButtonClick != null)
        {
            // call the registered event handler(s)
            this.ActionButtonClick(this, e);        
        }
    }
}

The above example allows an application to register to be notified whenever the LinkedButtonAndTextBox's button control has been clicked while still allowing notification of clicks occurring on other areas of the control. Depending on the control you write, this approach may be the one you are looking for.

It is important to check the event handler's (ActionButtonClick) value against null before making the call to avoid possible NullReferenceExceptions.

Which solution you choose to use will depend on the intent of your control. For my current application, the first solution made more sense to me. I would not be surprised if my next application were to use the second approach. :)

Enjoy!
-- DK

[Edit: minor tweak]

Disclaimer(s):
This posting is provided "AS IS" with no warranties, and confers no rights.

Adding a Non-Modal Splash Screen to your .NET Compact Framework Application

DavidKlineMS — Wed, 17 Aug 2005 23:47:00 GMT

A few weeks ago, Anthony Wong posted an excellent entry on adding a modal splash screen to your .NET Compact Framework application. His post started me wondering about how to create a non-modal splash screen. Why a non-modal splash screen? By making the splash screen non-modal, the application's main form can perform initialization work while the splash form is displayed. Once initialization is complete, the main form will close the splash screen form.

The snippets below display the relevant code for a single-threaded application that displays a non-modal splash screen, performs initialization and closes the splash screen when finished. Please note that this example uses version 2 of the .NET Compact Framework.

Main application form


//---------------------------------------------------------------------
//THIS CODE AND INFORMATION ARE PROVIDED AS IS WITHOUT WARRANTY OF ANY 
//KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE 
//IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A 
//PARTICULAR PURPOSE.
//---------------------------------------------------------------------
namespace NonModalSplashSnippet
{
    public partial class MainForm() : Form
    {
        private SplashForm m_Splash;

        public MainForm()
        {
            // create and display the splash screen form
            //  and make the main form it's owner
            this.m_Splash = new SplashForm();
            this.m_Splash.Owner = this;
            this.m_Splash.Show();

            // process the message queue
            //  this is done to allow the splash
            //  screen to be painted
            Application.DoEvents();

            // disable the main form
            //  to avoid the title bar
            //  being drawn over the splash screen
            //  during initialization
            this.Enabled = false;

            InitializeComponent();
        }

        private void MainForm_Load(object sender, EventArgs e)
        {
            // do form load-time work
            //  this sleep simulates the work
            System.Threading.Thread.Sleep(10000);

            // re-enable the form and
            //  tell Windows Forms to 
            //  make our form visible
            //  right now
            this.Enabled = true;
            this.Visible = true;

            // close the splash screen
            this.m_Splash.Close(); 
        }
    }
}

Splash screen form

//---------------------------------------------------------------------
//THIS CODE AND INFORMATION ARE PROVIDED AS IS WITHOUT WARRANTY OF ANY 
//KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE 
//IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A 
//PARTICULAR PURPOSE.
//---------------------------------------------------------------------
namespace NonModalSplashSnippet
{
    public partial class SplashForm() : Form
    {

        public SplashForm()
        {
            // use the form designer to set
            //  ControlBox == false
            //  WindowState == Maximized
            // This results in a full screen splash
            //  form without a title bar
            InitializeComponent();
        }

        protected override OnPaint(PaintEventArgs e)
        {

            // display a message
            StringFormat sf = new StringFormat();
            sf.Alignment = StringAlignment.Center;
            sf.LineAlignment = StringAlignment.Center; 
            e.Graphics.DrawString(".NET Compact Framework", 
                                  this.Font, 
                                  new SolidBrush(Color.Blue), 
                                  Screen.PrimaryScreen.Bounds, 
                                  sf);
        }
    }
}

How it works
Let's walk through the snippets and discuss what is happening.

The first job our application's main form performs is the creation of the splash screen form. Once created, the splash screen's owner is set to the instance of the MainForm class and then it is shown.

    this.m_Splash = new SplashForm();
    this.m_Splash.Owner = this;
    this.m_Splash.Show();

The setting of the splash form's owner is an important step that instructs the operating system, provided your application is the currently active application, to display the application's main form once the splash form is closed.

To ensure that the splash screen form gets painted (and all other pending messages get processed) the static Application.DoEvents method is called.
Application.DoEvents();

To avoid the main form's caption being displayed on top of the splash screen, the MainForm constructor sets the form's enabled property to false and then calls InitializeComponent (created by the Visual Studio 2005 form designer).

    this.Enabled = false;

Since the default value for the Enabled property is true, the designer does not explicitly set the value, which leaves our setting of false preserved.

The MainForm_Load method is where initialization will occur. In my snippet, I sleep for a few seconds to simulate work being performed. Once the initialization is complete, the main form is re-enabled and marked visible.

    this.Enabled = true;
    this.Visible = true;

By explicitly marking the main form visible, the system is being told that it is now time to display the form.

The last thing done in MainForm_Load is to close the splash screen.

    this.m_Splash.Close();

Once the splash screen is closed, the main form is displayed and is ready to be used.

Enjoy!
-- DK

[Edit: update links]
[Edit: fix error]

Disclaimer(s):
This posting is provided "AS IS" with no warranties, and confers no rights.
Some of the information contained within this post may be in relation to beta software. Any and all details are subject to change.

Exploring the NetCF Web Crawler sample (Visual Studio .NET 2003) - Part II: Updating the UI

DavidKlineMS — Mon, 21 Mar 2005 23:45:00 GMT

A couple of weeks ago, I discussed link tracking in the NetCF Web Crawler sample from Visual Studio .NET 2003. Today, I would like to use the Web Crawler sample to discuss updating an application's user interface from a worker thread.

When updating user interface elements, it is very important to perform the tasks while running in the context of the thread that created the controls. One side effect of attempting to modify controls from a different thread are application hangs. This is most often seen when attempting to update a control (ex: modify it's Text property) in a asynchronous method callback. While callback methods typically live in the class that owns the controls, they are most often called by a thread that was created by another piece of code (the NetCF HTTP client class library, for example). When UI updates are attempted from this callback, application hangs may occur.

The way to avoid these side effects is to marshal the callback calls to your user interface's thread context. This can be achived using the Invoke method of the System.Windows.Forms.Control class. The Web Crawler example uses this technique to provide runtime status to the user.

NOTE: The code in this post has been edited for clarity and to reduce size. For full sample code, please consult the files that were installed with Visual Studio .NET 2003 (\Program Files\Microsoft Visual Studio .NET 2003\CompactFrameworkSDK\v1.0.5000\Windows CE\Samples\VC#\Pocket PC\WebCrawler).

Events and event handlers
The Web Crawler's Crawler class supports a number of events for which that clients can register handlers. To keep my example as clear as possible, I am going to focus on a very simple case -- the PageFoundEvent.

The WebCrawler.Crawler object exposes a public EventHandler field for the PageHandledEvent as shown below:

public EventHandler PageFoundEvent;

The client (WebCrawler.MainForm) registers it's event hander:

 // from startButton_Click
this.crawler = new Crawler(startingPage,
                           noProxy);
this.crawler.PageFoundEvent += new EventHandler(this.HandlePageFoundEvent);

The event handler implementation also lives in the client (WebCrawler.MainForm):

 private void HandlePageFoundEvent(object sender, EventArgs e)
{
    if(CustomInvokeRequired())
    {
        this.linkCount.Invoke(new EventHandler(this.HandlePageFoundEvent));
        return;
    }
            
    try
    {
        this.linkCount.Text = string.Format("{0}", Int32.Parse(this.linkCount.Text)+1);
    }
    catch(FormatException)
    { }
}

The HandlePageFoundEvent method first checks to see if the call was made in the context of the user interface thread by calling CustomInvokeRequired() (more on this soon). If not (returns true), it calls the linkCount object's Invoke method to marshal the call to the user interface thread. The HandlePageFoundEvent method is then re-called on the user interface thread. CustomInvokeRequired() is called (returns false) and the method updates the linkCount control's Text property.

Determining if thread marshaling is required
I mentioned earlier that I would go into more detail on the web crawler's CustomInvokeRequired method (WebCrawler.MainForm). At startup, the web crawler's MainForm object stores it's thread in a private member variable:

private readonly System.Threading.Thread FormThread = System.Threading.Thread.CurrentThread;

This member is marked as readonly so that it cannot be modified.

When called, the CustomInvokeRequired method checks to see if the current thread is the same as the FormThread (the thread that owns the user interface):

if(this.FormThread.Equals(System.Threading.Thread.CurrentThread))

If the current thread is the user interface thread (this.FormThread.Equals(Thread.CurrentThread)), there is no marshaling required and CustomInvokeRequired returns false. Otherwise, true is returned indicating that thread marshaling is needed.

Using this technique, the web crawler's worker thread can keep the user informed, and not cause any undesirable side effects.

Until next time,
-- DK

Disclaimer(s):
This posting is provided "AS IS" with no warranties, and confers no rights.