HOWTO: Manipulate Icons in the System Tray with Visual Basic

ID: Q162613

The information in this article applies to:

Microsoft Visual Basic Learning, Professional, and Enterprise Editions for Windows, versions 5.0, 6.0
Microsoft Visual Basic Standard, Professional, and Enterprise Editions, 32-bit only, for Windows, version 4.0

SUMMARY

One of the new features of the Windows 98, Windows 95, and Windows NT 4.0 user interface is the taskbar status area. This article demonstrates how to use Visual Basic to add, modify, and delete status or notification indicators in the taskbar status area.

MORE INFORMATION

The taskbar status area is located to the right of the Start button, and provides you with status or notification indicators about your programs. Icons with ToolTips are typically used as indicators in the taskbar status area. The following are some examples of how to use the taskbar status area:

You can adjust the consumption level of your laptop's batteries by clicking a vertical graph in the taskbar status area and adjusting it in the window that appears. The graph indicates the amount of power left in your laptop computer's batteries.

You can track your favorite stock by creating an icon that changes when your stock changes price. Click the icon to display a chart of the stock.

You can adjust the volume control on a multimedia device by clicking the icon and displaying more controls.

To manipulate an icon in the taskbar status area, use the Windows API function Shell_NotifyIcon in the Shell32.dll file. This function allows you to add, modify, delete, set a ToolTip string, and send a callback message to execute mouse events. Visual Basic versions 4.0 and earlier do not directly accept callback messages or functions. However, there are three ways to work around this limitation:

The Hard Way: Create a control that accepts callbacks. Refer to the Microsoft Systems Journal article cited in the References section of this article for a way to create a control that accepts callbacks. To create this control, you need Visual C++.

The Easy Way: Use a third-party control that intercepts messages, such as the Message Blaster control.

The Simple Way: Use a Visual Basic intrinsic control to serve as a Window that reacts to the callback message. This article contains a sample program that uses this method. With this method, you want to use an event in a control that is rarely used. The event will be exclusively used to process the callback message.

In Visual Basic 5.0 and later, you can use the AddressOf Operator to call callback functions.

The next section explains the Shell_NotifyIcon function and the requirements to use this function.

Shell_NotifyIcon Function

You use the Shell_NotifyIcon function to send a message to a system to add, modify, or delete an icon from the taskbar status area. The function returns True if the message is sent successfully or False if the function is unsuccessful. The arguments of the functions are as follows:


   dwMessage: A message to execute an action. This parameter can be one of
   the following values:

      NIM_ADD: Adds an icon to the status area.
      NIM_DELETE: Deletes an icon from the status area.
      NIM_MODIFY: Modifies an icon in the status area.

   The values of these messages can be found in the header file,
   Shellapi.h.
 
   pnid: A pointer to a NOTIFYICONDATA structure. To pass this argument to
   the function, create a user-defined data type called NOTIFYICONDATA
   (shown later in this section) and pass this data type by value.

The NOTIFYICONDATA structure contains the following elements:


   cbSize: Passes the size of the NOTIFYICONDATA data type.
      Data Type: Long.
      Value: Use the Len function with the variable declared as this data
      type as the argument.

   hWnd: Handle of the window used to receive the notification message.
      Data Type: Long.
      Value: The hWnd property of the control used to receive this message.

   uId: Identifier of the icon in the status area.
      Data Type: Long.
      Value: Any value within the limits of the Long data type. The sample
      program uses vbNull.

   uFlags: Array of flags that indicate which of the other members contain
   valid data.
      Data Type: Long.
      Value: Any combination of the following constants to indicate that
      the member of this structure is valid and will be used:

         NIF_ICON: Passing this flag indicates that the value for the
         hIcon will be the icon that appears in the taskbar status area.

         NIF_MESSAGE: Passing this flag indicates that the uCallBackMessage
         value will be used as the callback message.

         NIF_TIP: Passing this flag indicates that the value of szTip will
         be used as the ToolTip for the icon in the taskbar status area.

   uCallBackMessage: Identifier of the notification message sent to the
   window that is used to receive the messages.
      Data Type: Long.
      Value: The message used to identify that a mouse event has occurred
      within the rectangular boundaries of the icon in the taskbar status
      area.

   hIcon: Handle of the icon that is displayed in the taskbar status area.
      Data Type: Long.
      Value: The image that will be used as an icon in the taskbar status
      area. This can be the icon property of a control, an image from an
      image control, or any icon image.

   szTip: String to be used as the ToolTip text.
      Data Type: Fixed-length string 64 bytes long.
      Value: Any null-terminated string under 64 bytes.

The next section explains how to use this function in a sample program to manipulate icons in the taskbar status area.

The Sample Program

The sample program consists of a form containing two command buttons and the common dialog box control. When you click Add Icon, you set the values of the NOTIFYICONDATA data type. In this data type, you set the following values:


   cbSize: The length of the variable that uses the Len function.

   hWnd: The handle of the window used to receive the callback messages. In
   the sample program, the form is used as the window to receive the
   messages.

   uId: The icon identifier. Although you can use any number, the sample
   program uses the vbNull constants.

   uFlags: Array flags indicate what members of this structure are valid.
   The sample program uses all the flags for maximum versatility.

   uCallBackMessage: The message that is sent when mouse activity occurs on
   the icon in the taskbar status tray. The mouse message that is sent maps
   to a mouse event in the control specified in the hWnd value. You should
   use a mouse message that can handle the messages exclusively. For
   example, the sample program uses the WM_MOUSEMOVE message because this
   message maps to the MouseMove event of the form. Rarely used in its
   intended form, the MouseMove event is a suitable event for this purpose.

   hIcon: The icon that is to be displayed in the taskbar status area. The
   sample program uses the form icon.

   szTip: The ToolTip string. The string must be terminated with a null
   character so the vbNullChar constant is concatenated to the string.

After setting the data, you then call the Shell_NotifyIcon function and pass the NOTIFYICONDATA along with a message to add the icon to the taskbar status area.

When you pass the mouse pointer over the icon in the taskbar status area, the form receives the message WM_MOUSEMOVE. This message maps to the form's MouseMove event. The X argument is the product of one of the mouse constants that indicates the mouse input (such as a left-click, right-click, single-click, or double-click) and the TwipsPerPixelX property of the screen. The mouse input is produced by dividing the X argument with this property. The mouse input is then used in a Select Case statement to execute a series of instructions.

For example, when you double-click the icon, the common dialog box appears and allows you to select a different icon. The hIcon value of the NOTIFYICONDATA data type is changed to the new icon. The Shell_NotifyIcon function is called with the new data type and a message to modify the icon in the taskbar status area.

If you right-click the icon, you execute the InputBox function that changes the ToolTip text. The new string is null terminated with the vbNullChar constant and the szTip value is changed to the new string. The Shell_NotifyIcon function is called with the new NOTIFYICONDATA data and a message to modify the icon.

When you click Delete Icon or exit the application, the Shell_NotifyIcon function is called with a message to delete the icon.

Steps To Create Sample Program

Start Visual Basic. If it is already running, go to the File menu and click New Project.

Place two CommandButtons and a common dialog box control on Form1.

Copy the following code to the Form1 code window:


      'Declare a user-defined variable to pass to the Shell_NotifyIcon
      'function.
      Private Type NOTIFYICONDATA
         cbSize As Long
         hWnd As Long
         uId As Long
         uFlags As Long
         uCallBackMessage As Long
         hIcon As Long
         szTip As String * 64
      End Type

      'Declare the constants for the API function. These constants can be
      'found in the header file Shellapi.h.

      'The following constants are the messages sent to the
      'Shell_NotifyIcon function to add, modify, or delete an icon from the
      'taskbar status area.
      Private Const NIM_ADD = &H0
      Private Const NIM_MODIFY = &H1
      Private Const NIM_DELETE = &H2

      'The following constant is the message sent when a mouse event occurs
      'within the rectangular boundaries of the icon in the taskbar status
      'area.
      Private Const WM_MOUSEMOVE = &H200

      'The following constants are the flags that indicate the valid
      'members of the NOTIFYICONDATA data type.
      Private Const NIF_MESSAGE = &H1
      Private Const NIF_ICON = &H2
      Private Const NIF_TIP = &H4

      'The following constants are used to determine the mouse input on the
      'the icon in the taskbar status area.

      'Left-click constants.
      Private Const WM_LBUTTONDBLCLK = &H203   'Double-click
      Private Const WM_LBUTTONDOWN = &H201     'Button down
      Private Const WM_LBUTTONUP = &H202       'Button up

      'Right-click constants.
      Private Const WM_RBUTTONDBLCLK = &H206   'Double-click
      Private Const WM_RBUTTONDOWN = &H204     'Button down
      Private Const WM_RBUTTONUP = &H205       'Button up

      'Declare the API function call.
      Private Declare Function Shell_NotifyIcon Lib "shell32" _
         Alias "Shell_NotifyIconA" _
         (ByVal dwMessage As Long, pnid As NOTIFYICONDATA) As Boolean

      'Dimension a variable as the user-defined data type.
      Dim nid As NOTIFYICONDATA

      Private Sub Command1_Click()
         'Click this button to add an icon to the taskbar status area.

         'Set the individual values of the NOTIFYICONDATA data type.
         nid.cbSize = Len(nid)
         nid.hWnd = Form1.hWnd
         nid.uId = vbNull
         nid.uFlags = NIF_ICON Or NIF_TIP Or NIF_MESSAGE
         nid.uCallBackMessage = WM_MOUSEMOVE
         nid.hIcon = Form1.Icon
         nid.szTip = "Taskbar Status Area Sample Program" & vbNullChar

         'Call the Shell_NotifyIcon function to add the icon to the taskbar
         'status area.
         Shell_NotifyIcon NIM_ADD, nid
      End Sub

      Private Sub Command2_Click()
         'Click this button to delete the added icon from the taskbar
         'status area by calling the Shell_NotifyIcon function.
         Shell_NotifyIcon NIM_DELETE, nid
      End Sub

      Private Sub Form_Load()
         'Set the captions of the command button when the form loads.
         Command1.Caption = "Add an Icon"
         Command2.Caption = "Delete Icon"
      End Sub

      Private Sub Form_Terminate()
         'Delete the added icon from the taskbar status area when the
         'program ends.
         Shell_NotifyIcon NIM_DELETE, nid
      End Sub

      Private Sub Form_MouseMove _
         (Button As Integer, _
          Shift As Integer, _
          X As Single, _
          Y As Single)
          'Event occurs when the mouse pointer is within the rectangular
          'boundaries of the icon in the taskbar status area.
          Dim msg As Long
          Dim sFilter As String
          msg = X / Screen.TwipsPerPixelX
          Select Case msg
             Case WM_LBUTTONDOWN
             Case WM_LBUTTONUP
             Case WM_LBUTTONDBLCLK
             CommonDialog1.DialogTitle = "Select an Icon"
             sFilter = "Icon Files (*.ico)|*.ico"
             sFilter = sFilter & "|All Files (*.*)|*.*"
             CommonDialog1.Filter = sFilter
             CommonDialog1.ShowOpen
             If CommonDialog1.filename <> "" Then
                Form1.Icon = LoadPicture(CommonDialog1.filename)
                nid.hIcon = Form1.Icon
                Shell_NotifyIcon NIM_MODIFY, nid
             End If
             Case WM_RBUTTONDOWN
                Dim ToolTipString As String
                ToolTipString = InputBox("Enter the new ToolTip:", _
                                  "Change ToolTip")
                If ToolTipString <> "" Then
                   nid.szTip = ToolTipString & vbNullChar
                   Shell_NotifyIcon NIM_MODIFY, nid
                End If
             Case WM_RBUTTONUP
             Case WM_RBUTTONDBLCLK
          End Select
      End Sub

Press the F5 key to run the project or on the Tools menu, click Run Project. Click Add Icon to add an icon to the taskbar status area. Double-click the icon to change the icon. Right-click the icon to change the ToolTip string. Click Delete Icon to remove the icon from the taskbar status area.

REFERENCES

"Hardcore Visual Basic," Bruce McKinney, Microsoft Press, 1995 Microsoft Win32 SDK, Shell_NotifyIcon and NOTIFYICONDATA "Microsoft Systems Journal," February 1996, "The Visual Programmer," page 93, Joshua Trupin "Visual Basic Programmer's Journal," March 1996, "Q & A," page 136, Carl Franklin

Additional query words: kbVBp400 kbVBp500 kbVBp600 kbVBp kbdsd kbDSupport kbWinSDK

Keywords : kbGrpVB
Version : WINDOWS:4.0,5.0,6.0
Platform : WINDOWS
Issue type : kbhowto