Configuring XMouse Behavior in Windows via VB.Net and the SystemParametersInfo() API

What is XMouse behavior?

"XMouse" behavior is a system whereby windows receive focus when the mouse enters them, as opposed to requiring the user to physically click on them.  Focus is automatically given to a window when the mouse enters it, and stays within for longer than the pre-defined threshold delay.  When the window receives focus, it can also optionally be brought to the top of the z-order, in front of all other windows.

Why would I want to use XMouse?

Using an XMouse setup can reduce the number of clicks and amount of time needed to accomplish a task.  For example, when I reconcile my checkbook, I have my bank statement open in my primary monitor, and MS Money open in my secondary monitor.  Balancing the accounts requires frequent scrolling in both windows to find matches, but clicks are only necessary in the secondary monitor to place a checkmark next to records in MS Money that appear in the bank statement.  Thus the only interaction required in the primary monitor is scrolling that window with the mousewheel on my mouse.  With default mouse operations in Windows, though, one must click the bank statement window before it can be scrolled.  Therefore each and every time I want to scroll the opposite screen, I must first execute a click on it.  More often than I'd like to admit, I actually forget to click on that opposite screen, resulting in the wrong window being scrolled when I use the mousewheel!  With XMouse behavior activated, however, that missed click becomes moot since all I have to do is move my mouse into that window, wait a split second, and then scroll away.  This saves a lot of time and clicking over a long period of time.

Why isn't it XMouse on all the time by default?

XMouse isn't enabled all the time, by default, since some applications and features of Windows itself don't always work well with it.  Some types of windows are displayed as popups that immediately hide when something else gets focus.  In Vista and above, the calendar that gets displayed when single clicking the clock in the tray is one example of this type of popup window.  Thus when attempting to move the mouse to those popups, the space in between gets focus causing the popup to disappear before you can even reach it.  When this occurs, either the activation delay needs to be increased, or Xmouse needs to be turned off completely.  Unfortunately, with a default installation of Windows, the only way to increase the delay is by manually changing the registry.  (*The activation and bring to the front features can also be set via the Registry.)

How do I turn XMouse on or off?

Turning Xmouse activation on and off has actually been available in Windows since Windows 95.  In Win95/98/ME/XP, it could be set via either PowerToys or TweakUI, two free tools provided by Microsoft.  In Vista/Win7/Win8, an external tool isn't required as it's available through the "Activate a window by hovering over it with the mouse" option located in the Control Panel's Ease of Access Center.  Opening up the control panel up isn't very convenient though.  It would be nice to have an icon in the tray that can be clicked to change the XMouse settings.  Thankfully, it is possible to modify these settings from a VB.Net application using the SystemParametersInfo() API.

The SystemParametersInfo() API

The SystemParametersInfo() API can be used to retrieve and set quite a number of system-wide windows settings in the following categories: Accessibility, Desktop, Icon, Input, Menu, Power, Screen Saver, Time-out, UI Effects, and Window parameters.  Full documentation can be found on MSDN here:
The SystemParametersInfo() API: http://msdn.microsoft.com/en-us/library/windows/desktop/ms724947(v=vs.85).aspx

The parameters relevant to XMouse settings fall under the Windows category, and are as follows:

Importing the SystemParametersInfo() API
      
To utilize the SystemParametersInfo() API in our VB.Net application, we first need to import it.  Here is the declaration of SystemParametersInfo() used for setting a value:

Private Declare Function SetSystemParametersInfo Lib "user32" Alias _
    "SystemParametersInfoA" (ByVal uAction As Integer, ByVal uParam As Integer, _
    ByVal lpvParam As Integer, ByVal fuWinIni As Integer) As Integer

Select all Open in new window

The "SetSystemParametersInfo" portion immediately after the word "Function" indicates the name that will be used locally in the application to access the API.  This name can be anything you want, and can even match the name of the API you are importing.  The value of "user32" after the word "Lib" indicates the actual Windows Library DLL that contains the API you want to import.  Note that we don't have to specify a path if its located in the standard windows folders.  The "SystemParametersInfoA" value after the term "Alias" indicates the actual function name we are using inside the previously specified library (user32).

The values listed after the Alias portion indicate the parameters that SystemParametersInfo() expects to be passed in.  The first parameter, "uAction", tells SystemParametersInfo() what particular setting you are accessing, such as SPI_SETACTIVEWINDOWTRACKING.  The second parameter called "uParam" is not used for these settings and will just be passed zero.  The third parameter of "lpvParam" is used to pass in a value when setting something, or to receive a value when retrieving a setting.  The last parameter "fuWinIni" is used to specify if the user profile should be updated with the new setting, and whether a WM_SETTINGCHANGE message should be sent to all top level windows with the SPIF_SENDCHANGE flag.  This last value can be set to zero if the user profile should not be updated and you do not want to notify other windows.

Note that I said the above declaration of SystemParametersInfo() was used for SETTING a value.  When setting a value, the third parameter called "lpvParam" is passed BYVAL.  When you want to retrieve a value such as with SPI_GETACTIVEWINDOWTRACKING, however, the third parameter of "lpvParam" is passed BYREF instead of ByVal so that the local variable in your application can be updated with the desired setting:

Private Declare Function GetSystemParametersInfo Lib "user32" Alias _
    "SystemParametersInfoA" (ByVal uAction As Integer, ByVal uParam As Integer, _
    ByRef lpvParam As Integer, ByVal fuWinIni As Integer) As Integer

Select all Open in new window

This declaration is exactly the same as the previous one, except that "SetSystemParametersInfo" has been changed to "GetSystemParametersInfo", and "ByVal" has been changed to "ByRef" for third parameter "lpvParam".  Thus within the application we will use two different names to access the exact same API.  This is necessary to differentiate if we want the third parameter to be passed ByVal or ByRef.

Using the SystemParametersInfo() API

It's time to start demonstrating some actual code.  Here's a snippet that shows how to retrieve whether XMouse behavior (active window tracking) is currently enabled or not:

Dim tracking As Boolean
GetSystemParametersInfo(SPI_GETACTIVEWINDOWTRACKING, 0, tracking, 0)
MessageBox.Show("tracking = " & tracking)

Select all Open in new window

Changing the current state of XMouse behavior looks pretty similar:

Dim newState As Boolean = True ' True = On, False = Off
SetSystemParametersInfo(SPI_SETACTIVEWINDOWTRACKING, 0, newState, 0)

Select all Open in new window

The SPI_SETACTIVEWNDTRKZORDER option allows you to toggle whether the window that gets active focus is also brought to the front of the z-order.  When this value is set to false, moving the mouse into a window will give it focus, but it will stay in its current z-order and not come to the front.  This may mean that a partially obscured window gets focus while it is still behind another window, which can take quite awhile to get used to!  Conversely, when this value is set to True, the window receiving XMouse focus is also brought to the top of other windows as one would expect it to.  The use of SPI_GETACTIVEWNDTRKZORDER / SPI_SETACTIVEWNDTRKZORDER is exactly the same as the already demonstrated SPI_GETACTIVEWINDOWTRACKING / SPI_SETACTIVEWINDOWTRACKING settings above.

The last setting of SPI_SETACTIVEWNDTRKTIMEOUT allows you to set how long the mouse must be in a window before triggering XMouse behavior.  Again, it works exactly like the other two settings, but instead of passing True/False you'd pass an integer value representing the delay in milliseconds.  Thus setting this value to 500 would mean the mouse would need to be in the window for a 1/2 second before activating it.  Finding the "sweet spot" for this delay is tricky.  If you make it too large then XMouse becomes a hindrance.  Imagine needing to hover for a full two seconds before a window is activated.  This would most likely slow down a process instead of making it more efficient.  At the opposite end of the spectrum, setting the delay to 0 (zero) makes whatever window you are in immediately get focus.  This makes it impossible, though, to interact with certain types of windows that "popup" and go away when something else gets focus, since they disappear before you ever get a chance to interact with them.  Values between 250 and 500 seem to work for most people.  I personally like the delay set at 350:

SetSystemParametersInfo(SPI_SETACTIVEWNDTRKTIMEOUT, 0, 350, 0)

Select all Open in new window

Putting it all together in an XMouse Utility Class

While the SystemParametersInfo() API is indeed easy to use, it would still be nice to neatly wrap all those calls in a utility class.  Here is what I came up with:

Public Class XMouse

    Private Const SPI_GETACTIVEWINDOWTRACKING As Integer = &H1000
    Private Const SPI_SETACTIVEWINDOWTRACKING As Integer = &H1001

    Private Const SPI_GETACTIVEWNDTRKTIMEOUT As Integer = &H2002
    Private Const SPI_SETACTIVEWNDTRKTIMEOUT As Integer = &H2003

    Private Const SPI_GETACTIVEWNDTRKZORDER As Integer = &H100C
    Private Const SPI_SETACTIVEWNDTRKZORDER As Integer = &H100D

    Private Const SPIF_SENDCHANGE As Integer = &H2
    Private Const SPIF_UPDATEINIFILE As Integer = &H1

    ' Used for Retrieving values, note though "ByRef" for lpvParam!
    Private Declare Function GetSystemParametersInfo Lib "user32" Alias _
        "SystemParametersInfoA" (ByVal uAction As Integer, ByVal uParam As Integer, _
        ByRef lpvParam As Integer, ByVal fuWinIni As Integer) As Integer

    ' Used for Setting values, note though "ByVal" for lpvParam!
    Private Declare Function SetSystemParametersInfo Lib "user32" Alias _
        "SystemParametersInfoA" (ByVal uAction As Integer, ByVal uParam As Integer, _
        ByVal lpvParam As Integer, ByVal fuWinIni As Integer) As Integer

    Public Class XSettings

        Public IsTracking As Boolean
        Public DelayInMilliseconds As Integer
        Public BringToFront As Boolean

        Public Sub New()
        End Sub

        Public Sub New(ByVal IsTracking As Boolean, ByVal DelayInMilliseconds As Integer, ByVal BringToFront As Boolean)
            Me.IsTracking = IsTracking
            Me.DelayInMilliseconds = DelayInMilliseconds
            Me.BringToFront = BringToFront
        End Sub

        Public Overrides Function ToString() As String
            Return "IsTracking = " & IsTracking & ", DelayInMilliseconds = " & DelayInMilliseconds & ", BringToFront = " & BringToFront
        End Function

    End Class

    Public Shared Property IsTracking() As Boolean
        Get
            Dim tracking As Boolean
            GetSystemParametersInfo(SPI_GETACTIVEWINDOWTRACKING, 0, tracking, 0)
            Return tracking
        End Get
        Set(value As Boolean)
            SetSystemParametersInfo(SPI_SETACTIVEWINDOWTRACKING, 0, value, SPIF_UPDATEINIFILE Or SPIF_SENDCHANGE)
        End Set
    End Property

    Public Shared Property DelayInMilliseconds() As Integer
        Get
            Dim timeout As Integer
            GetSystemParametersInfo(SPI_GETACTIVEWNDTRKTIMEOUT, 0, timeout, 0)
            Return timeout
        End Get
        Set(value As Integer)
            If value >= 0 AndAlso value <= 2000 Then
                SetSystemParametersInfo(SPI_SETACTIVEWNDTRKTIMEOUT, 0, value, SPIF_UPDATEINIFILE Or SPIF_SENDCHANGE)
            End If
        End Set
    End Property

    Public Shared Property BringToFront() As Boolean
        Get
            Dim raise As Boolean
            GetSystemParametersInfo(SPI_GETACTIVEWNDTRKZORDER, 0, raise, 0)
            Return raise
        End Get
        Set(value As Boolean)
            SetSystemParametersInfo(SPI_SETACTIVEWNDTRKZORDER, 0, value, SPIF_UPDATEINIFILE Or SPIF_SENDCHANGE)
        End Set
    End Property

    Public Shared Property Settings() As XSettings
        Get
            Dim values As New XSettings
            values.IsTracking = XMouse.IsTracking
            values.DelayInMilliseconds = XMouse.DelayInMilliseconds
            values.BringToFront = XMouse.BringToFront
            Return values
        End Get
        Set(value As XSettings)
            XMouse.IsTracking = value.IsTracking
            XMouse.DelayInMilliseconds = value.DelayInMilliseconds
            XMouse.BringToFront = value.BringToFront
        End Set
    End Property

End Class

Select all Open in new window

Now we can turn XMouse on or off using syntax like this:

XMouse.IsTracking = True ' Turn it on
XMouse.IsTracking = False ' Turn it off

Select all Open in new window

Conversely, we can read the setting using simply "Xmouse.IsTracking".  This could be useful for instance in a ContextMenuStrip with a ToolStripMenuItem that has the CheckOnClick option set.  We could set the checkmark of the menu item in the Opening() event of the ContextMenuStrip to make sure it reflects the current status:

Private Sub ContextMenuStrip1_Opening(sender As System.Object, e As System.ComponentModel.CancelEventArgs) Handles ContextMenuStrip1.Opening
    XMouseActiveTrackingToolStripMenuItem.Checked = XMouse.IsTracking
End Sub

Select all Open in new window

Changing the delay now becomes:

XMouse.DelayInMilliseconds = 350

Select all Open in new window

And lastly, we can set the "bring to top" option using:

XMouse.BringToFront = True ' Turn it on
XMouse.BringToFront = False ' Turn it off

Select all Open in new window

I also added in a class called "XSettings" that holds all three values together, which allows us to set or retrieve all three values at the same time.  This could be useful if you want to save particular combinations of settings as a profile to facilitate fast switching between different configurations.  

The SPIF_SENDCHANGE flag and WM_SETTINGCHANGE

I briefly mentioned the SPIF_SENDCHANGE flag when describing the parameters used when setting a value through SetSystemParametersInfo().  When this option is used, a WM_SETTINGCHANGE message is sent to all top level windows.  In a .Net Winforms appliction, this message can be intercepted in the main forms WndProc() method.  If your application displays windows settings, it may be necessary to update them automatically when another application changes them.  If those other applications are well behaved, they will use SendMessageTimeout() with the HWND_BROADCAST flag to notify other applications that a change has been made.  Here is how to trap the WM_SETTINGCHANGE message in WndProc():

Public Class Form1

    Private Const WM_SETTINGCHANGE As Integer = &H1A

    Protected Overrides Sub WndProc(ByRef m As System.Windows.Forms.Message)
        Select Case m.Msg
            Case WM_SETTINGCHANGE
                Me.RefreshSettings()

        End Select

        MyBase.WndProc(m)
    End Sub

    Private Sub RefreshSettings()
        Dim xSettings As XMouse.XSettings = XMouse.Settings
        Me.cbActiveTracking.Checked = xSettings.IsTracking
        Me.nudDelay.Value = xSettings.DelayInMilliseconds
        Me.cbBringToFront.Checked = xSettings.BringToFront
    End Sub

End Class

Select all Open in new window

Hopefully I've given you enough information to fully understand how to use the SetSystemParametersInfo() API to configure XMouse settings, and possibly build your own utility to do just that.  Happy XMousing!