Windows Forms Documentation Updates : Form and Application Classes

New White Paper: Creating Smart Application Layouts in Windows Forms 2.0

Jay A. Allen — Thu, 20 Jul 2006 00:17:00 GMT

My new Windows Forms white paper is now available on MSDN. It covers using ToolStrip as a navigation alternative to TabControl, and creating collapsible flyout menus a la the Visual Studio Toolbox. Compilable code samples are included.

Enjoy!

Adding Custom My.Application Methods to C# Windows Forms Applications

Jay A. Allen — Tue, 02 May 2006 01:18:00 GMT

In my last entry, I talked about how I loved extending My.Application in VB to create global methods available to my entire application. A reader mentioned that you can get much of the default functionality associated with the My class by using That. But what about adding your own global functionality?

You can easily create your own My.Application in a C# Windows Forms app. This provides a central location for application logging and other common tasks. In the following example, I describe how to do this to expose the DataDirectory property I wrote in a previous post, so that any form or class in your Windows Forms application can discover where the data directory for ClickOnce resides.

Open Program.cs.
Define a static class named My with a single property named Application:

public static class My
{
        private static MyApplication defaultInstance = new CountDownCSharp.MyApplication();

        public static MyApplication Application
        {
            get
            {
                return (defaultInstance);
            }
        }
    }
Define MyApplication to contain all of the global methods and properties you'll need.

    public class MyApplication
    {
        String _DataDirectory = null;

        public MyApplication()
        {
        }

        public string GetDataDirectory()
        {
            string _PathStr;
            if (ApplicationDeployment.IsNetworkDeployed)
            {
                _PathStr = WinForms.Application.UserAppDataPath;
            }
            else
            {
                _PathStr = WinForms.Application.ExecutablePath.Substring(0, WinForms.Application.ExecutablePath.LastIndexOf("\\"));
                if (!(Directory.Exists(_PathStr + "\\images")))
                {
                    _PathStr = _PathStr + "\\..\\..";
                    if (!(Directory.Exists(_PathStr + "\\images")))
                    {
                        throw new DirectoryNotFoundException("Cannot find directory " + _PathStr + "\\images. Fatal error.");
                    }
                }
            }
            return (_PathStr);
        }

        public string DataDirectory
        {
            get
            {
                if ((_DataDirectory == null))
                {
                    _DataDirectory = GetDataDirectory();
                    return (_DataDirectory);
                }
                else
                {
                    return (_DataDirectory);
                }
            }
        }

ClickOnce: How to Dynamically Detect Data Directory Between Debug, Release, and Publish

Jay A. Allen — Wed, 26 Apr 2006 17:05:00 GMT

Dynamically Detecting the Data Directory

My Slideshow control (which I discussed in a previous post) looks in a data directory called images for the images it wishes to display. This adds a curious twist to application development and deployment. When I deploy an application using ClickOnce, I will want to include these files in the data directory for that application. (See Accessing Local and Remote Data in ClickOnce Applications for the 411 on data directories.) Under ClickOnce, the data directory is a long, garbled path, such as C:\Documents and Settings\username\Local Settings\Apps\2.0\Data\DXQV72TZ.3GR\EERQ26OC.Y91\test..tion_9d0ab10300fca701_0001.0000_edbfed2eeae795d5\Data. I can find the value of this path (deliberately obscured to foil easy discovery of my app's data) by calling Application.UserAppDataPath.

However, when I'm debugging my app in Visual Studio, the data directory path is set to C:\Documents and Settings\username\Application Data\Publisher Name\App Name\Version Number. Now, I could manually stuff my data files in here for the purposes of debugging. Indeed, for most of my project, that's what I did. But this makes it difficult to ship the project to other developers and have it work out of the box. Also, it requires that I switch the files around whenever I update the version, or alter the application or publisher name. The chance that data files will become out of sync during development is high.

To get around this mess, I wrote a small snippet of code that detects where the data directory resides for the current instance of the application. If ApplicationDeployment.IsNetworkDeployed is true, I use Application.UserAppDataPath as the data directory. If I'm not running as a ClickOnce application, I first look at Application.ExecutablePath to see if the images directory is in the same directory as the executable. If it isn't, I assume I'm running in debug mode under Visual Studio, and look two directories up for my precious data.

    Private Function GetDataDirectory() As String
        Dim _ExeDir As String
        Dim _PathStr As String

        If (ApplicationDeployment.IsNetworkDeployed) Then
            _PathStr = Application.UserAppDataPath & "\images"
        Else
            ' Check if it's in the exe directory, or in a debug folder dir.
            _ExeDir = Application.ExecutablePath.Substring(0, _
            Application.ExecutablePath.LastIndexOf("\"))
            _PathStr = _ExeDir & "\images"

            If (Not Directory.Exists(_PathStr)) Then
                _PathStr = _ExeDir & "\..\..\images"
                If (Not Directory.Exists(_PathStr)) Then
                    Throw New DirectoryNotFoundException("Cannot find directory " & _PathStr & ". Fatal error.")
                End If
            End If
        End If

GetDataDirectory = _PathStr
End Function

This code not only allows the app to switch between debug testing and ClickOnce deployment. It it also supports good ol' xcopy deployment. So long as the images directory is at the same level as the EXE, I'm good to go.

Populating the Data Directory for ClickOnce Deployment

How do I add the images directory and its files to my ClickOnce deployment? As far as Visual Studio is concerned, this is the easy part!

Right-click your project and select Add->New Folder.... In my example, I name my folder images.
Right-click the folder and select Add Existing Items....
Add all of the items from your folder into the Visual Studio project folder.
Right-click your project again and select Properties. Click the Publish tab, and then click the Application Files... button.
For each of the files you just added, change Publish Status to Data File. Leave Download Group set to (Required).

Adding Glass to a Windows Forms App on Vista

Jay A. Allen — Mon, 24 Apr 2006 21:39:00 GMT

Tim Sneath, Windows Vista tech evangelist extraordinaire, has a good post up on how to add a glass effect to a form in Windows Forms. It's no more complex than a call into dwmapi.dll - although there are some provisos and quid pro quos, natch.

It's cool stuff like this that almost makes being a technical evangelist look appealing.

Almost.

Control.Location is a Pain - or, Why We Need an OffsetLocation() Method

Jay A. Allen — Thu, 20 Apr 2006 20:36:00 GMT

I'm polishing up some code for a Windows Forms white paper on application layouts in Windows Forms 2.0. The paper will cover advanced uses of the ToolStrip control for creating navigational layouts, among other things. One of the samples is a VS Toolbox-style flyout panel. The code to implement this wasn't too gnarly, except that in my first rev, I was new()ing up a whole lotta Point structs in slide-in and slide-out:

currentControl.Location = New Point(currentControl.Location.X + 20, currentControl.Location.Y)

Jim Galasyn, one of my colleagues on the team, asked why I was doing this. To put it simply, I did it this naively because the Location property of Control is lame. Location is of type Point, which is a struct. Structs are passed by value, not by reference, meaning that returning the Location property directly would pass a copy of the type on the stack. On top of that, for some reason, the source code for Control.Location in Windows Forms just goes ahead and new()s up a new Struct every time you access the Location property anyway! (That's a good reason not to call this property extraneously, and to almost never call it in large loops.) So direct calls on Location are for naught.

I worked around this in my own application by caching a Point value, and operating on that using the Offset() method. This eliminated the constant creation of new Point structures on the stack, sped up my app, and make for somewhat cleaner code:

_CachedControlPoint.Offset(-20, 0)
currentControl.Location = _CachedControlPoint

What's frustrating is that, after 2-1/2 years writing Windows Forms documentation, I still get bitten by this. It's so natural to call a property or a method and expect that to reflect on the associated object that exceptions such as these throw me for a loop. Sure, we can document this. We have documented it. But documentation can only do so much to defeat logic.

It would be nice, at the very least, to have an OffsetLocation() method defined on Control that eliminated the need for self-caching of Point objects. I know my product team has bigger fish to fry, but...come on, folks, pretty please? As a favor for l'il ol' me? [insert eyelash-batting here]

Boneheaded .NET Error of the Day

WinFormsUE — Wed, 08 Mar 2006 00:34:00 GMT

[Can I say "boneheaded" on MSDN? If this post disappears in an hour, you'll know I've received an email from HR...]

As a Programmer/Writer for Windows Forms, I develop code examples in both C# and Visual Basic.NET. Today, I was finishing up a code example for a new SDK topic on ClickOnce and localization. (Yes, I'll be publishing this soon!) I named my C# sample project ClickOnce.SatelliteAssemblies. Wrote, published, tested. Worked like a champ.

I named my VB.NET sample project ClickOnce.SatelliteAssemblies.VB. Wrote, published, tested...only to find out that the server was prompting me for credentials when it wasn't before. I'd just changed my password, so I assumed the Web server was defaulting to cached credentials. I restarted the Web server, rebooted the box...all to no avail. I was stumped.

It took an hour and a half for it to dawn on me that my directories ended in the suffix .VB, and that this suffix is, you know, kinda special to a machine with ASP.NET installed on it.

Sigh.

Calling Validate() and ValidateChildren() from Validating and Validated Events

WinFormsUE — Tue, 28 Feb 2006 18:09:00 GMT

Don't do it - it won't work. Both methods will automatically return false, in order to prevent infinite recursion from unskillful implementation of the event handlers. I've added a note about this to the relevant sections of the docs.

Mind you, I'm not entirely clear on why you would want to do this in the first place. I asked my contact at Product Support Services for the scenario, but haven't heard back. If anyone can shed some light on what problem this is attempting to solve, I'm all ears.

Application.ThreadException sample now works!

WinFormsUE — Thu, 09 Feb 2006 01:16:00 GMT

Several customers have pointed out to me that the sample for the ThreadException event doesn't even compile, let alone work. Similarly, the topic containing it never clearly differentiated between exceptions on Windows Forms threads (which are handled by ThreadException) and exceptions on other threads (which are handled by AppDomain.UnhandledException).

Here's the new sample we'll be including:

// Starts the application.
[SecurityPermission(SecurityAction.Demand, Flags = SecurityPermissionFlag.ControlAppDomain)]
public static void Main(string[] args)
{
// Add the event handler for handling UI thread exceptions to the event.
Application.ThreadException += new ThreadExceptionEventHandler(ErrorHandlerForm.Form1_UIThreadException);

    // Set the unhandled exception mode to force all Windows Forms errors to go through
    // our handler.
    Application.SetUnhandledExceptionMode(UnhandledExceptionMode.CatchException);

    // Add the event handler for handling non-UI thread exceptions to the event.
    AppDomain.CurrentDomain.UnhandledException +=
        new UnhandledExceptionEventHandler(CurrentDomain_UnhandledException);

// Runs the application.
Application.Run(new ErrorHandlerForm());
}

// Programs the button to throw an exception when clicked.
private void button1_Click(object sender, System.EventArgs e)
{
throw new ArgumentException("The parameter was invalid");
}

// Start a new thread, separate from Windows Forms, that will throw an exception.
private void button2_Click(object sender, System.EventArgs e)
{
    ThreadStart newThreadStart = new ThreadStart(newThread_Execute);
    newThread = new Thread(newThreadStart);
    newThread.Start();
}

// The thread we start up to demonstrate non-UI exception handling.
void newThread_Execute()
{
throw new Exception("The method or operation is not implemented.");
}

// Handle the UI exceptions by showing a dialog box, and asking the user whether
// or not they wish to abort execution.
private static void Form1_UIThreadException(object sender, ThreadExceptionEventArgs t)
{
    DialogResult result = DialogResult.Cancel;
    try
    {
        result = ShowThreadExceptionDialog("Windows Forms Error", t.Exception);
    }
    catch
    {
        try
        {
            MessageBox.Show("Fatal Windows Forms Error",
                "Fatal Windows Forms Error", MessageBoxButtons.AbortRetryIgnore, MessageBoxIcon.Stop);
        }
        finally
        {
            Application.Exit();
        }
    }

    // Exits the program when the user clicks Abort.
    if (result == DialogResult.Abort)
        Application.Exit();
}

// Handle the UI exceptions by showing a dialog box, and asking the user whether
// or not they wish to abort execution.
// NOTE: This exception cannot be kept from terminating the application - it can only
// log the event, and inform the user about it.
private static void CurrentDomain_UnhandledException(object sender, UnhandledExceptionEventArgs e)
{
    try
    {
        Exception ex = (Exception)e.ExceptionObject;
        string errorMsg = "An application error occurred. Please contact the adminstrator " +
            "with the following information:\n\n";

        // Since we can't prevent the app from terminating, log this to the event log.
        if (!EventLog.SourceExists("ThreadException"))
        {
            EventLog.CreateEventSource("ThreadException", "Application");
        }

        // Create an EventLog instance and assign its source.
        EventLog myLog = new EventLog();
        myLog.Source = "ThreadException";
        myLog.WriteEntry(errorMsg + ex.Message + "\n\nStack Trace:\n" + ex.StackTrace);
    }
    catch (Exception exc)
    {
        try
        {
            MessageBox.Show("Fatal Non-UI Error",
                "Fatal Non-UI Error. Could not write the error to the event log. Reason: "
                + exc.Message, MessageBoxButtons.OK, MessageBoxIcon.Stop);
        }
        finally
        {
            Application.Exit();
        }
    }
}

// Creates the error message and displays it.
private static DialogResult ShowThreadExceptionDialog(string title, Exception e)
{
    string errorMsg = "An application error occurred. Please contact the adminstrator " +
        "with the following information:\n\n";
    errorMsg = errorMsg + e.Message + "\n\nStack Trace:\n" + e.StackTrace;
    return MessageBox.Show(errorMsg, title, MessageBoxButtons.AbortRetryIgnore,
        MessageBoxIcon.Stop);
}

SetCompatibleTextRenderingDefault

WinFormsUE — Wed, 01 Feb 2006 02:24:00 GMT

There were several changes in Windows Forms for .NET Framework 2.0 that came down the pipe too late for us to document in time for RTM. Once of these was the SetCompatibleTextRenderingDefault() method on System.Windows.Forms.Application.

I've since documented it; this new text is currently live on MSDN2. In case you have trouble accessing that, here's what I had to say:

Certain Windows Forms controls can render their text using either the GDI graphics library, or the newer GDI+ library. This change was made because of performance and localization issues with GDI+. By default, existing controls that support the UseCompatibleTextRendering property are set to true for backwards compatibility, but all new controls in environments such as Visual Studio have this property set to false. Use SetCompatibleTextRenderingDefault when you wish to switch the default text rendering for new controls.

You should never call this method if your Windows Forms code is hosted in another application, such as Internet Explorer. Only call this method in stand-alone Windows Forms applications.

No sample code, since the call is very simple. Just stick this in your Main() method before calling Application.Run(), and you're set.