Shell_NotifyIcon Function

Declare Function Shell_NotifyIcon Lib "shell32.dll" Alias "Shell_NotifyIconA" (ByVal dwMessage As Long, pnid As NOTIFYICONDATA) As Long

Platforms

Windows 95: Supported.
Windows 98: Supported.
Windows NT: Requires Windows NT 4.0 or later.
Windows 2000: Supported.
Windows CE: Requires Windows CE 1.0 or later.

Description & Usage

Shell_NotifyIcon manipulates an icon located in the taskbar's status area, commonly referred to as the "system tray." This function adds a new icon, removes an existing icon, or changes an existing icon owned by the calling program. Programs typically use tray icons when they run in the background without a window; the icon gives the user a way to access the running program.

All of a tray icon's messages are sent to its owner window for processing. See the page for the NOTIFYICONDATA structure for more details on how this is done. The standard behavior of Shell_NotifyIcon used the following messages: WM_MOUSEMOVE, WM_LBUTTONDOWN, WM_LBUTTONUP, WM_RBUTTONDOWN, WM_RBUTTONUP, etc.

Return Value

The function returns 0 if an error occured, or a non-zero value if successful.

Visual Basic-Specific Issues

None.

Parameters

dwMessage

One of the following flags specifying the action to take:

NIM_ADD: Add the icon described by pnid to the system tray.
NIM_DELETE: Remove the icon described by pnid from the system tray.
NIM_MODIFY: Modify the icon described by pnid.
NIM_SETFOCUS: Windows 2000: Return the focus to the system tray. This should be done after completing the user interface operations associated with the icon.
NIM_SETVERSION: Windows 2000: Use the uVersion member of the structure passed as pnid to determine which taskbar behavior to use. The two options are the Windows 2000-specific behavior and the behavior found on other Windows platforms. Note that this guide does not explain how to use the behavior introduced by Windows 2000.

pnid

Provides identifying information and settings for the tray icon, as needed by the value passed as dwMessage.

Constant Definitions

Const NIM_ADD = &H0
Const NIM_DELETE = &H2
Const NIM_MODIFY = &H1
Const NIM_SETFOCUS = &H4
Const NIM_SETVERSION = &H8

Example

Note: To use this example, you must first use the Menu Editor utility to create a small menu on Form1. Create a menu called mnuTrayIconPopup with its Visible check box cleared. Then, create two menu items under it: mnuAbout and mnuExit. You can give those items whatever captions you which; those are what will be displayed in the menu. If you do this properly, you will not see a menu bar in Form1 but the example code will function properly.

' This code is licensed according to the terms and conditions listed here.

' Place an icon in the system tray when window Form1 opens.  When right-
' clicked, a small pop-up menu appears.  The icon is deleted when Form1 closes.
' Notice how the window procedure for Form1 is extended in order to process the
' messages for the icon.  Also, note the application-defined message used for tray
' icons.

' *** Place the following code in a module. ***
' Public variable definitions.
Public pOldProc As Long  ' pointer to Form1's previous window procedure
Public Const PK_TRAYICON = &H401  ' program-defined message for tray icon action

' This function acts as the new window procedure for Form1.  It handles the program-
' defined PK_TRAYICON message, used whenever a user event occurs with the
' tray icon.
Public Function WindowProc(ByVal hWnd As Long, ByVal uMsg As Long, ByVal wParam As Long, ByVal lParam As Long) As Long
  Select Case uMsg
  Case PK_TRAYICON
    ' If the user released the right mouse button over the icon, display the
    ' mnuTrayIconPopup menu at the mouse cursor's position.  Make
    ' mnuAbout the default selection in the menu.
    If lParam = WM_RBUTTONUP Then
      Form1.PopupMenu mnuTrayIconPopup, , , , mnuAbout
    End If
    WindowProc = 1  ' this return value doesn't really matter
  Case Else
    ' Pass the message to the procedure Visual Basic provided.
    WindowProc = CallWindowProc(pOldProc, hWnd, Msg, wParam, lParam)
  End Select
End Function

' *** Place the following code in Form1. ***
' This function creates the tray icon and hooks up the window procedure
' when Form1 first opens.
Private Sub Form1_Open()
  Dim nid As NOTIFYICONDATA  ' icon information
  Dim retval As Long  ' return value

  ' Put the icon settings into the structure.
  With nid
    .cbSize = Len(nid)  ' size of structure
    .hWnd = Form1.hWnd  ' owner of the icon and processor of its messages
    .uID = 1  ' unique identifier for the window's tray icons
    .uFlags = NIF_ICON Or NIF_MESSAGE Or NIF_TIP  ' provide icon, message, and tool tip text
    .uCallbackMessage = PK_TRAYICON  ' message to use for icon events
    .hIcon = Form1.Icon  ' handle to the icon to actually display in the tray
    .szTip = "Sample Tray Icon" & vbNullChar  ' tool tip text for icon
  End With

  ' Add the icon to the system tray.
  retval = Shell_NotifyIcon(NIM_ADD, nid)
  ' Set the new window procedure for window Form1.
  pOldProc = SetWindowLong(Form1.hWnd, GWL_WNDPROC, AddressOf WindowProc)
End Sub

' This function removes the tray icon and returns the old window procedure to use.
Private Sub Form1_Unload(Cancel As Integer)
  Dim nid As NOTIFYICONDATA  ' icon information
  Dim retval As Long  ' return value

  ' Load the structure with just the identifying information.
  With nid
    .cbSize = Len(nid)  ' size of structure
    .hWnd = Form1.hWnd  ' handle of owning window
    .uId = 1  ' unique identifier
  End With
  ' Remove the icon from the system tray.
  retval = Shell_NotifyIcon(NIM_DELETE, nid)

  ' Make the old window procedure the current window procedure.
  retval = SetWindowLong(Form1.hWnd, GWL_WNDPROC, pOldProc)
End Sub