Some programmers confuse the Me object and the My namespace. Me is a reference to the object that is currently executing code. If a piece of code is inside a particular class, Me is a reference to the class object that is running.

For example, if the class is a form, then within the form's code, Me returns a reference to the running form. If the form's code must change the form's BackColor property, it can use the Me object to explicitly refer to its own form. It can also omit the keyword to refer to its form implicitly. That means the following two statements are equivalent:

Me.BackColor = SystemColors.Control
BackColor = SystemColors.Control

If you build several instances of a class, the code in each instance gets a different value for Me. Each instance's Me object returns a reference to that instance.

On the other hand, My isn't an object at all. It is a namespace that contains objects, values, routines, and other namespaces that implement common functions. The My namespace is a single unique entity shared by all of the code throughout the application.

It may help if you try not to think of the My namespace as a thing in and of itself. The My namespace doesn't do anything all alone. It needs to be paired with something within the namespace. Think of My.Application, My.User, My.Computer, and so forth. It makes sense to think of My.Computer as representing the computer.

The following table briefly outlines the major sections within the My namespace. Other sections of this chapter and Appendix S, "The My Namespace," describe these sections in greater detail.

Environment variables are normally set on a system-wide basis before the program begins. In older operating systems, batch files such as autoexec.bat set these values. More recent systems provide Control Panel tools to set environment variables.

Newer systems also use an autoexec.nt file to set environment variables that apply only to command-line (console) applications so they don't affect GUI applications. Sometimes you can use this fact to your advantage by giving different kinds of applications different environment settings.

To set environment variables in Windows XP, open the Control Panel, run the System applet, and select the Advanced tab. Alternatively, you can right-click My Computer or Computer in newer versions of Windows and select Properties from the context menu. Click the Environment Variables button to display the Environment Variables dialog box. Use the dialog's Add, Edit, and Delete buttons to add, modify, or remove environment variables.

To set environment variables in Windows Vista, open the Control Panel, open the System and Maintenance applet, and then open its System applet. On the left, click the "Advanced system settings" link. That link requires administrator privileges so Vista displays a UAC privilege elevation dialog. Enter an administrator's password and click OK to get to the System Properties dialog. Select the Advanced tab and click the Environment Variables button to display the Environment Variables dialog box. Use the dialog's Add, Edit, and Delete buttons to add, modify, or remove environment variables.

Be careful to use the variables properly. Use system variables when a value should apply to all processes started by all users, user variables when a value should apply to all processes started by a particular user, and process variables when a value should apply to a process and any processes that it starts.

At runtime, a Visual Basic application can use the Environ function to retrieve environment variable values. If you pass this function a number, it returns a string giving the statement that assigns the corresponding environment variable. For example, Environ(1) might return the following string:

ALLUSERSPROFILE=C:ProgramData

You should pass the function a number between 1 and 255. Environ returns a zero-length string if the number does not correspond to an environment variable. The following code uses this fact to list all the application's environment variables. When it finds a variable that has zero length, it knows it has read all of the variables with values.

For i As Integer = 1 To 255
    If Environ(i).Length = 0 Then Exit For
    Debug.WriteLine(Environ(i))
Next i

                                                  

Example program ListEnviron uses similar code to display all of the environment variables' assignment statements. Example program ListEnvironValues, which is also available for download, uses the String class's Split method to separate the environment variables' names and values and displays them in separate columns in a ListView control.

If you pass the Environ function the name of an environment variable, the function returns the variable's value or Nothing if the variable does not exist. The following code displays the value assigned to the USERNAME variable:

MessageBox.Show(Environ("USERNAME"))

The Environ function is easy to use, but it's not very flexible; it cannot create or modify variable values.

Of course sometimes that lack of flexibility can be an asset. A malicious program cannot use Environ to mess up the system's environment variables so it gives you one less potential problem.

The System.Environment object provides methods for getting and setting process-level environment variables. It also provides properties and methods for working with many other items in the application's environment. The following table describes the Environment object's most useful properties.

Example program SystemEnvironment, which is available for download on the book's web site, displays the values of many of the Environment object's properties.

The following table describes the Environment object's most useful methods.

MessageBox.Show(Environment.ExpandEnvironment
Variables("I am %username%."))

The SetEnvironmentVariable method lets you set environment variables at the system, user, and process level. If you set a variable's value to Nothing, this method deletes the variable. For system and user values, it updates the Registry appropriately to set the values. Example program EnvironmentVariableLevels, which is available for download on the book's web site, uses SetEnvironmentVariable to get and set variable values. For more information on the SetEnvironmentVariable method, see msdn2.microsoft.com/library/96xafkes.aspx.

Visual Basic provides four methods for saving and reading Registry values for a particular application: SaveSetting, GetSetting, GetAllSettings, and DeleteSetting.

The SaveSetting method saves a value into a Registry key. This routine takes as parameters the name of the application, a section name, the setting's name, and the setting's value. For example, the following code saves the value stored in the m_CurrentDirectory variable in the RegistrySettings application's Config section with the name CurrentDirectory:

SaveSetting("RegistrySettings", "Config", "CurrentDirectory",
    m_CurrentDirectory)

SaveSetting automatically creates the application and section areas in the Registry if they don't already exist.

This value is saved at the following Registry location. This is all one name; it just doesn't fit on one line here:

HKEY_CURRENT_USERSoftwareVB and VBA Program Settings
    RegistrySettingsConfigCurrentDirectory

If you use the Visual Basic SaveSetting, GetSetting, GetAllSettings, and DeleteSetting methods, you don't need to worry about the first part of this Registry path. You need only to remember the application name, section name, and setting name.

The GetSetting function retrieves a Registry value. It takes as parameters the application name, section name, and setting name you used to save the value. It can optionally take a default value to return if the setting doesn't exist in the Registry. The following code displays the value saved by the previous call to SaveSetting. If no value is saved in the Registry, it displays the string <none>.

MessageBox.Show(GetSetting("RegistrySettings", "Config", "CurrentDirectory",
 "<none>"))

The GetAllSettings function returns a two-dimensional array of name and value pairs for a Registry section. The following code uses GetAllSettings to fetch the values stored in the RegistrySettings application's Config section. It loops through the results, displaying the setting names and values.

Dim settings As String(,) = GetAllSettings("RegistrySettings", "Config")
For i As Integer = 0 To settings.GetUpperBound(0)
    Debug.WriteLine(settings(i, 0) & " = " & settings(i, 1))
Next i

If an application needs to use all of the settings in a section, GetAllSettings may be faster than using GetSetting repeatedly.

The DeleteSetting method removes a setting, section, or an entire application's setting area from the Registry. The following code shows how to remove each of those kinds of items:

' Remove the RegistrySettingsRegistrySettings/Config/CurrentDirectory setting.
DeleteSetting("RegistrySettings", "Config", "CurrentDirectory")

' Remove the RegistrySettings/Config section.
DeleteSetting("RegistrySettings", "Config")

' Remove all of the RegistrySettings application's settings.
DeleteSetting("RegistrySettings")

Example program RegistrySettings, which is available for download on the book's web site, demonstrates each of Visual Basic's Registry commands.

The My.Computer.Registry namespace provides objects that manipulate the Registry. My.Computer.Registry has seven properties that refer to objects of type RegistryKey. The following table lists these objects and the corresponding Registry subtrees.

The program can use these RegistryKey objects to work with the corresponding Registry subtree. The following table describes the most useful properties and methods provided by the RegistryKey class.

My.Computer.Registry.CurrentUser.DeleteSubKey("Software
VB and VBA Program SettingsRegistrySettingsConfig")

My.Computer.Registry.CurrentUser.DeleteSubKeyTree
("SoftwareVB and VBA Program SettingsRegistrySettings")

The following example opens the HKEY_CURRENT_USERSoftwareVB and VBA Program SettingsRegistrySettingsConfig key. It reads the CurrentDirectory value from that key using the default value "C:" and saves the result in the variable current_directory. It closes the key and then uses the DeleteSubKey method to delete the RegistrySettings application's Config section.

' Open the application's Config subkey.
Dim config_section As Microsoft.Win32.RegistryKey =
    My.Computer.Registry.CurrentUser.OpenSubKey(
        "SoftwareVB and VBA Program SettingsRegistrySettingsConfig")

' Get the CurrentDirectory value.
Dim current_directory As String =
    CType(config_section.GetValue("CurrentDirectory", "C:"), String)

' Close the subkey.
config_section.Close()

' Delete the application's whole Config section.
My.Computer.Registry.CurrentUser. DeleteSubKey DeleteSubKey (
    "SoftwareVB and VBA Program SettingsRegistrySettingsConfig")

The following code shows the equivalent operations using the native Registry methods of Visual Basic:

' Get the CurrentDirectory value.
Dim current_directory As String =
GetSetting("RegistrySettings", "Config", "CurrentDirectory", "C:")

' Delete the application's whole Config section.
DeleteSetting("RegistrySettings", "Config")

It is generally easier to use the native Registry methods of Visual Basic. Those methods work only with values in the HKEY_CURRENT_USERSoftwareVB and VBA Program Settings Registry subtree, however. If you need to access keys and values outside of this subtree, you must use the My.Computer.Registry objects.

Example program MyComputerRegistry, which is available for download on the book's web site, demonstrates many useful My.Computer.Registry operations. It does the same things as program RegistrySettings mentioned in the previous section except it uses My.Computer.Registry instead of Visual Basic's native Registry methods.

To create application resources in Visual Basic, open Solution Explorer, double-click the My Project entry, and select the Resources tab. Use the dropdown on the left to select one of the resource categories: Strings, Images, Icons, Audio, Files, or Other. Figure 35-3 shows the application's Resources tab displaying the application's images.

Figure 35.3. The Resources tab contains image and other resources used by the application.

If you double-click an item, Visual Studio opens an appropriate editor. For example, if you double-click a bitmap resource, Visual Studio opens the image in an integrated bitmap editor.

Click the Add Resource dropdown list and select Add Existing File to add a file from the disk to the program's resources. Use the dropdown's Add New String, Add New Icon, or Add New Text File commands to add new items to the resource file. The dropdown's New Image item opens a cascading submenu that lets you create new PNG, bitmap, GIF, JPEG, and TIFF images.

When you create application resources, Visual Studio automatically generates code that adds strongly typed resource properties to the My.Resources namespace. If you open Solution Explorer and click the Show All Files button, you can see the Resources.Designer.vb file that contains this code. The Solution Explorer path to this file is My Project/Resources.resx/Resources.Designer.vb.

For example, the following code shows the property that Resources.Designer.vb contains to retrieve the Octahedron image resource:

Friend ReadOnly Property Octahedron() As System.Drawing.Bitmap
    Get
        Dim obj As Object =
            ResourceManager.GetObject("Octahedron", resourceCulture)
        Return CType(obj,System.Drawing.Bitmap)
    End Get
End Property

                                                  

The following code shows how a program can use these My.Resources properties. It sets the lblGreeting control's Text property to the string returned by the My.Resources.Greeting property. Then it sets the form's BackgroundImage property to the image resource named Dog.

Private Sub Form1_Load() Handles MyBase.Load
    lblGreeting.Text = My.Resources.Greeting
    Me.BackgroundImage = My.Resources.Dog
End Sub

                                                  

Because these property procedures are strongly typed, IntelliSense can offer support for them. If you type My.Resources, IntelliSense lists the values defined in the application's resource file.

The strongly typed resource properties use a ResourceManager object to fetch the application's resources. The My.Resources namespace exposes that object through its ResourceManager property, so you can use that object directly to retrieve the application's resources. The following code does the same things as the previous version, except it uses the ResourceManager directly. Note that the ResourceManager property's GetObject method returns a generic Object, so the code uses CType to convert the result into an Image before assigning it to the form's BackgroundImage property.

Private Sub Form1_Load() Handles MyBase.Load
    lblGreeting.Text = My.Resources.ResourceManager.GetString("Greeting")
    Me.BackgroundImage = CType(
        My.Resources.ResourceManager.GetObject("Dog"), Image)
End Sub

                                                  

Example program UseResources uses similar code to set a label's text and to display an image. Commented-out code does the same thing by using the strongly typed resource properties.

Generally, you should use the automatically generated resource properties in the My.Resources namespace because they are easier to use and they are strongly typed. The ResourceManager class is much more useful when you use other embedded resource files as described in the following section.

In addition to storing resources in the application's resource file Resources.resx, you can add other resources files to the application. Open the Project menu and select the Add New Item command. Pick the Resources File template, give the file a meaningful name, and click OK.

After you add a resource file to the project, you can double-click it in Solution Explorer to open it in the resource editor. Then you can add resources to the file exactly as you do for the application's resource file.

At runtime, you can use a ResourceManager object to fetch the resources from the embedded file. The following code loads the Dog image from the file Images.resx and the string Greeting from the file Strings.resx.

It starts by declaring a ResourceManager variable. It then initializes the variable, passing its constructor the resource file's path and the assembly containing the file. The file's path consists of the application's root namespace EmbeddedResources followed by the file's name Images.

The program then uses the ResourceManager object's GetObject method to fetch the Dog image, converts the generic Object returned into an Image, and assigns the result to the form's BackgroundImage property.

Next, the code reinitializes the ResourceManager object so it represents the Strings resource file. It calls the manager's GetString method to get the value of the Greeting resource and saves the result in the lblGreeting control's Text property.

Private Sub Form1_Load() Handles MyBase.Load
      Dim resource_manager As ResourceManager

      ' Get the Dog image from Images.resx.
      resource_manager = New ResourceManager(
            "EmbeddedResources.Images",
            Me.GetType.Assembly)
      Me.BackgroundImage = CType(
            resource_manager.GetObject("Dog"), Image)

      ' Get the Greeting from StringResources.resx.
      resource_manager = New ResourceManager(
            "EmbeddedResources.Strings", Me.GetType.Assembly)
      lblGreeting.Text = resource_manager.GetString("Greeting")
End Sub

                                                  

Just as it generates strongly typed properties for application resources, Visual Studio generates similar code for other embedded resource files. You can access these properties by adding the resource file's name after My.Settings and before the resource name. For example, to get the image resource named Dog from the Images resource file, the program would use My.Settings.Images.Dog.

Example program EmbeddedResources, which is available for download on the book's web site, contains code to load embedded resources both with a resource manager and by using the strongly typed resource properties.

Embedded resource files enable you to organize data in central locations. For example, you can keep all the images used by the application in a single resource file, and all of the program's forms can fetch the images from that file.

Rather than embedding a resource file in the application, you can load it at runtime. Then if you must make changes to the resources, you can replace the resource file and the program will load the new resources the next time it runs.

To make switching resources easy, you can place them in a resource-only assembly. This satellite assembly contains data for the application but doesn't contain any program logic.

To make a resource-only satellite assembly, start a new Visual Basic project, selecting the Class Library template. Delete the project's initial class. Then, add resources to the project as you would add them to any other project. You can add resources to the project's application resources or to embedded resource files. When you are finished adding resources, compile the project to build a .dll file.

You can then build an executable Windows application that loads resources from the assembly as shown in the following code:

Private Sub Form1_Load() Handles MyBase.Load
      ' Get the resource Assembly.
      Dim satellite_assembly As Assembly
      satellite_assembly = Assembly.LoadFrom("SatelliteResourcesDll.dll")

      ' Create a ResourceManager for the satellite's
      ' main resource file.
      Dim resource_manager As ResourceManager
      resource_manager = New ResourceManager(
            "SatelliteResourcesDll.Resources", satellite_assembly)
      ' Get the string resource from the satellite's
      ' main resource file.
      lblGreeting.Text = resource_manager.GetString("Greeting")

      ' Create a ResourceManager for the satellite's
      ' Images resource file.
      resource_manager = New ResourceManager(
            "SatelliteResourcesDll.Images", satellite_assembly)

      ' Get the form's background image from the satellite's
      ' Images resource file.
      Me.BackgroundImage = CType(resource_manager.GetObject("Dog"), Image)
End Sub

                                                  

The program declares an Assembly object and uses the shared Assembly.LoadForm method to load information about the resource-only assembly SatelliteResourcesDll.dll. In this example, the file was copied into the executable program's startup directory so the program does not need to pass a complete path to the LoadFrom method.

Next, the program uses the Assembly object to create a ResourceManager. For the resource file's name, it passes the ResourceManager object's constructor to the assembly's root namespace SatelliteResourcesDll, followed by the name of the resource file within the satellite project. In this case, the first resource is stored in the project's resources, so the file is MyResources.resx. Now the program uses the ResourceManager object's GetString method to fetch the Greeting resource.

The program then creates a new ResourceManager using the same Assembly object, this time using the resource file named ImageResources.resx. It uses the GetObject method to fetch the image named Dog, converts the result into an Image, and saves the result in the form's BackgroundImage property.

Later, if you must change the value of the Greeting string or the Dog image, you can update the satellite project, build a new DLL file, and copy the DLL file into the executable program's startup directory. The next time you run the program, it will load the new resources.

Example projects SatelliteResourcesDll and SatelliteMain, which are both available for download on the book's web site, contain the satellite resource DLL and an executable program that uses it, respectively.

One of the most important reasons for inventing resource files was to allow localization: supporting different text, images, and other items for different languages and cultures. In Visual Studio .NET, localization is easy.

First, create a form using whatever language you typically use from day to day. For me, that's English as spoken in the United States. Open the form in the form designer and give it whatever controls you need. Set the form's and controls' properties as usual.

Next, set the form's Localizable property to True. Then set the form's Language property to the first language you want to support other than the default language that you have been working with so far. Modify the controls' properties for the new language.

As you modify a form, Visual Studio saves the changes you make to a new resource file attached to the form. If you open Solution Explorer and click the Show All Files button, you can see these resource files below the form's file.

Example program Localized, which is available for download on the book's web site, uses default settings for United States English. It also includes localizations for generic German (as opposed to German as spoken in Switzerland, Germany, Liechtenstein, or some other country). If you expand the form's entry in Solution Explorer, you'll find the files Form1.resx holding the default settings and Form1.de.resx holding the German settings.

At runtime, the application automatically checks the user's computer and selects the best resource file based on the system's regional settings.

Normally, you should let the application pick the appropriate resource file automatically, but you can explicitly select a resource file for testing purposes. To do that, open the Solution Explorer and click the Show All Files button. Find the form's design file (for example, Form1.Designer.vb) and open it.

Give the form an empty constructor that sets the current thread's CurrentCulture and CurrentUICulture properties to the culture that you want to use. See the online help for the CultureInfo class to get a list of possible cultures such as en-US (United States English) or de-DE (German in Germany, as opposed to in Austria, Switzerland, or some other locale). The result should look something like the following code:

Imports System.Threading
Imports System.Globalization

Public Class Form1
      Public Sub New()
            MyBase.New()

            ' Set the culture and UI culture to German.
            Thread.CurrentThread.CurrentCulture = New CultureInfo("de-DE")
            Thread.CurrentThread.CurrentUICulture = New CultureInfo("de-DE")

            'This call is required by the Windows Forms Designer.
            InitializeComponent()
      End Sub
End Class

                                                  

The rest is automatic. When the form's InitializeComponent method executes, it loads the resources it needs for the culture you selected.

Example program LocalizedUseGerman, which is available for download on the book's web site, uses this code to open the form localized for German even if your system would not normally select that version.

Like the ResourceManager class, the ComponentResourceManager class provides GetString and GetObject methods for loading resources from a resource file one at a time.

ComponentResourceManager also provides the ApplyResources method, which makes applying resources to an object easier. ApplyResources searches a resource file for items with a particular object name. It then applies any resources it finds to an object's properties.

For example, you could use ApplyResources to search for resources with the object name ExitButton and apply them to the btnExit control. If the resource file contained an item named ExitButton.Text, ApplyResources would apply it to the btnExit control's Text property. If the method found other resources (such as ExitButton.Location and ExitButton.Size), it would apply those properties to the control, too.

When you localize a form, Visual Studio automatically creates entries in the appropriate resource files for the form's controls. If you set the form's Language to German and set the btnYes button's Text property to Ja, Visual Studio adds a string entry named btnYes.Text with value Ja to the form's German resource file.

Visual Studio uses the special name $this to represent the form's properties. For example, if you set the form's Text property, the IDE adds a string resource named $this.Text to the appropriate resource file.

Example program LocalizedPickLanguage uses ComponentResourceManager objects in the following code to load different localized resources while it is running:

' Select English.
Private Sub radEnglish_CheckedChanged() Handles radEnglish.CheckedChanged
      If Not radEnglish.Checked Then Exit Sub
      LoadAllResources(New CultureInfo("en-US"))
End Sub

' Select German.
Private Sub radGerman_CheckedChanged() Handles radGerman.CheckedChanged
      If Not radGerman.Checked Then Exit Sub
      LoadAllResources(New CultureInfo("de-DE"))
End Sub

' Load resources for the form and all controls.
Private Sub LoadAllResources(ByVal culture_info As CultureInfo)
      ' Make a ComponentResourceManager.
      Dim component_resource_manager As New ComponentResourceManager(Me.GetType)

      ' Load the form's resources.
      LoadResources(Me, "$this", component_resource_manager, culture_info)
End Sub

 ' Load appropriate resources for an object and its contained controls.
Private Sub LoadResources(ByVal parent As Control,
 ByVal parent_name As String,
 ByVal component_resource_manager As ComponentResourceManager,
 ByVal culture_info As CultureInfo)
      ' Load the parent's resources.
      component_resource_manager.ApplyResources(
            parent, parent_name, culture_info)

ToolTip1.SetToolTip(parent, component_resource_manager.GetString(
            parent_name & ".ToolTip", culture_info))

      ' Load each contained control's resources.
      For Each ctl As Control In parent.Controls
            LoadResources(ctl, ctl.Name, component_resource_manager, culture_info)
      Next ctl
End Sub

                                                  

When the user clicks the radEnglish radio button, the code calls subroutine LoadAllResources, passing it a new CultureInfo object representing United States English. Similarly, when the user clicks the radGerman radio button, the code calls LoadAllResources passing it a CultureInfo object representing German.

Subroutine LoadAllResources creates a ComponentResourceManager for the form's type and calls subroutine LoadResources, passing it the form, the special form resource named $this, the component resource manager, and the CultureInfo object.

Subroutine LoadResources loads the resources for an object and all of the controls it contains. First, it uses the component resource manager's ApplyResources to load the object's resources.

Next, it sets the object's tooltip if it has one. Recall that a control's tooltip is actually not a property of the control. Instead it is an extender provider property provided by a ToolTip control. To load the form's tooltip, the code explicitly calls the Tooltip1 control's SetToolTip method, passing to it the object being loaded and the object's name with ".ToolTip" appended.

Finally, the code loops through the object's contained controls and performs calls LoadResources for each. This makes the code recursively call subroutine LoadResources for every control in the application.

Example program LocalizedPickLanguage2 uses the following slightly modified code to accomplish the same tasks. Instead of passing a CultureInfo object into the ApplyResources method, the program sets the current thread's CurrentCulture and CurrentUICulture properties. It then lets the calls to ApplyResources figure out which resource file to use.

' Load resources for the form and all controls.
Private Sub LoadAllResources(ByVal culture_info As CultureInfo)
      ' Set the current culture and UI culture.
      Thread.CurrentThread.CurrentCulture = culture_info
      Thread.CurrentThread.CurrentUICulture = culture_info

      ' Make a ComponentResourceManager.
      Dim component_resource_manager As New ComponentResourceManager(Me.GetType)

      ' Load the form's resources.
      LoadResources(Me, "$this", component_resource_manager)
End Sub

' Load appropriate resources for an object and its contained controls.

Private Sub LoadResources(ByVal parent As Control,
 ByVal parent_name As String,
 ByVal component_resource_manager As ComponentResourceManager)
      ' Load the parent's resources.
      component_resource_manager.ApplyResources(parent, parent_name)
      ToolTip1.SetToolTip(parent,
            component_resource_manager.GetString(parent_name & ".ToolTip"))

      ' Load each contained control's resources.
      For Each ctl As Control In parent.Controls
            LoadResources(ctl, ctl.Name, component_resource_manager)
      Next ctl
End Sub

                                                  

The program can later check the CurrentCulture and CurrentUICulture properties if it needs to remember which culture it is currently using.

The following table describes the Application object's most useful properties.

Example program ListForms, which is available for download on the book's web site, uses the Application.OpenForms collection to list its running forms.

To set the CompanyName, ProductName, and ProductVersion, open Solution Explorer, double-click the My Project entry, and select the Application tab. Then click the Assembly Information button and enter the values on the Assembly Information dialog box. Example program ShowProductInfo displays these three values.

The following table describes the Application object's most useful methods.

Example program FilterMessages uses the following code to filter messages and ignore left mouse button down messages:

Public Class Form1
      ' Filter out left mouse button down messages.
      Private Class NoLeftDownMessageFilter
            Implements IMessageFilter

            Public Function PreFilterMessage(
             ByRef m As System.Windows.Forms.Message) _
             As Boolean Implements IMessageFilter.PreFilterMessage
                  ' If the message is left mouse down, return True
                  ' to indicate that the message should be ignored.
                  Const WM_LBUTTONDOWN As Long = & H201
                  Return (m.Msg = WM_LBUTTONDOWN)
            End Function
      End Class

      ' Install the message filter.
      Private Sub Form1_Load() Handles MyBase.Load
            Dim no_left_down_message_filter As New NoLeftDownMessageFilter
            Application.AddMessageFilter(no_left_down_message_filter)
      End Sub

      ' Toggle the wait cursor.
      Private Sub Form1_Click() Handles Me.Click
            Application.UseWaitCursor = Not Application.UseWaitCursor
      End Sub
End Class

                                                  

The NoLeftDownMessageFilter class implements the IMessageFilter interface, which specifies the PreFilterMessage function. That function examines a message and returns True if it wants to filter the message out of the form's message queue. In this example, the function returns True if the message is WM_LBUTTONDOWN, indicating that the left button has been pressed.

The form's Load event handler creates a new instance of the filter class and uses the Application object's AddMessageFilter method to install the filter.

The form's Click event handler toggles the state of the Application object's UseWaitCursor property. This displays or hides the wait cursor.

When you left-click the form, the message filter intercepts the left button down message, so the Click event doesn't occur. If you right-click the form, the filter allows all messages through so the Click event occurs and the form displays or hides the wait cursor.

The Application object provides a few events that give you information about the application's state. The following table describes these events.

When you end an application by unloading its form, the program receives the events FormClosing, FormClosed, ThreadExit, and ApplicationExit, in that order.

If you end the application by calling the Application object's Exit method, the program only receives the ThreadExit and ApplicationExit events. If more than one thread is running, they each receive ThreadExit events, and then they each receive ApplicationExit events.

Example program CatchThreadException uses the following code to catch all exceptions thrown by the application:

Imports System.IO

Public Class Form1
      ' Install the ThreadException event handler.
      Private Sub Form1_Load() Handles Me.Load
            AddHandler Application.ThreadException,AddressOf Me.app_ThreadException
      End Sub

      ' Catch a ThreadException event.
      Private Sub app_ThreadException(ByVal sender As Object,
       ByVal e As System.Threading.ThreadExceptionEventArgs)
            MessageBox.Show("Caught unhandled exception:" &
                  vbCrLf & vbCrLf & e.Exception.Message)
      End Sub

      ' Throw an InvalidDataException.
      Private Sub btnThrow_Click() Handles btnThrow.Click
            Throw New InvalidDataException("Bad data! Bad!")
      End Sub

      ' Call the OnThreadException method.
      Private Sub btnOnThreadException_Click() Handles btnOnThreadException.Click
            Application.OnThreadException(New InvalidDataException("Bad data! Bad!"))
      End Sub
End Class

                                                  

When it starts, the form's Load event handler uses the Application object's AddHandler method to add the app_ThreadException subroutine as a handler for the Application's ThreadException event.

The app_ThreadException subroutine simply displays an error message describing the exception that it caught. A real application would take different actions such as logging the error and a stack trace, restarting the application, and so forth.

When the user clicks the Throw button, the program throws an exception. If you are running the program in the development environment, Visual Studio halts at the Throw statement and tells you that it encountered an unhandled exception. If you run the compiled executable outside of the development environment, the application's ThreadException event occurs.The app_ThreadException routine catches the event and displays its message.

When the user clicks the OnThreadException button, the program calls the Application object's OnThreadException method, passing it an exception object. Whether you are running in the development environment or running the compiled executable, the application's ThreadException event occurs and the app_ThreadException routine catches it. You can use OnThreadException to throw the exception without the IDE's interference, so you can catch it and debug the exception handling code.