Notifications and the Notification Area

Notifications and the Notification Area

The notification area is a portion of the taskbar that provides a temporary source for notifications and status. It can also be used to display icons for system and program features that have no presence on the desktop, such as battery level, volume control, and network status. The notification area has been known historically as the system tray or status area.通知区域是任务栏的一部分，使用一个临时资源来做通知或者状态提醒。它也可以用来显示一些图标，来表示未曾在桌面上显示的系统或者程序的一些特性，例如电池电量、音量控制、网络状态。通知区域以前也被称为系统驻留图标或者状态区域。

This topic contains the following sections:这个主题包含了下面几个章节：

• Notification and Notification Area Guidelines 通知和通知区域规范
  
• Creating and Displaying a Notification 创建和显示通知区域
  • Add a Notification Icon 添加通知图标
  • Define the NOTIFYICONDATA Version 定义通知数据的版本
  • Define the Notification Look and Contents 定义通知的外观和内容
  • Check the User Status 检查用户状态
  • Display the Notification 显示通知
  • Removing an Icon 移除图标
• SDK Sample SDK示例
• Related topics 相关主题
  

Notification and Notification Area Guidelines 通知和通知区域规范

See the Notifications and Notification Area sections of the Windows User Experience Interaction Guidelines for best practices in the use of notifications and the notification area. The goal is to provide user benefit through appropriate use of notifications, without being annoying or distracting.（你可以参考 Windows 用户体验交互设计规范）

The notification area is not for critical information that must be acted on immediately. It is also not intended for quick program or command access. As of Windows 7, much of that functionality is best accomplished through an application's taskbar button.（这玩意不适合立即显示信息也不适合快速操作以及命令访问，对于Win7来说大多数的功能最好通过程序的任务栏按钮完成。）

Windows 7 allows a user to suppress all notifications from an application if they choose, so thoughtful notification design and use will incline the user to allow your application to continue to display them. Notifications are an interruption; ensure that they are worth it.（不知道在说什么 _(:з」∠)_ ）

Windows 7 introduces the concept of "quiet time". Quiet time is defined as the first hour after a new user logs into his or her account either for the first time or for the first time after an operating system upgrade or clean installation. This time is set aside to allow the user to explore and familiarize themselves with the new environment without the distraction of notifications. During this time, most notifications should not be sent or shown. Exceptions include feedback that the user would expect to see in response to a user action, such as when he or she plugs in a USB device or prints a document. API specifics of regarding quiet time are discussed later in this topic.（Win7 引入了安静时间，这一段就是解释。_(:з」∠)_ ）

Creating and Displaying a Notification

The remaining sections in this topic outline the basic procedure to follow to display a notification from your application to the user.本主题剩下的章节概述了使用通知区域显示通知给用户的大致过程。

1. Add a Notification Icon 添加通知区域
2. Define the NOTIFYICONDATA Version 定义通知数据的版本
   
3. Define the Notification Look and Contents 定义通知的外观和内容
   
4. Check the User Status 检查用户状态
   
5. Display the Notification 显示通知
   
6. Removing an Icon 移除图标
   

Add a Notification Icon

To display a notification, you must have an icon in the notification area. In certain cases, such as Microsoft Communicator or battery level, that icon will already be present. In many other cases, however, you will add an icon to the notification area only as long as is needed to show the notification. In either case, this is accomplished using theShell_NotifyIcon function. Shell_NotifyIcon allows you to add, modify, or delete an icon in the notification area.要显示一个通知，你必须有一个图标在通知区域。在某些情况下，例如微软Communicator和电池电量，它们的图标早已显示了。然而在其他大多数情况，如果你要显示通知，你就必须向通知区域添加图标。不管哪种情况，都必须使用Shell_NotifyIcon函数。Shell_NotifyIcon函数允许在通知区域里添加修改删除图标。

When an icon is added to the notification area on Windows 7, it is added to the overflow section of the notification area by default. This area contains notification area icons that are active, but not visible in the notification area. Only the user can promote an icon from the overflow to the notification area, although in certain circumstances the system can temporarily promote an icon into the notification area as a short preview (under one minute).当图标添加到Win7的通知区域时，默认会被添加到通知区域的末尾。这个区域包含了活动的但是没有显示的通知区域图标。只有用户才能更改图标在通知区域的显示位置，虽然在某种情况下系统也会临时的改变这些图标的位置，但这只是暂时的。

Note  The user should have the final say on which icons they want to see in their notification area. Before installing a non-transient icon in the notification area, the user should be asked for permission. They should also be given the option (normally though its shortcut menu) to remove the icon from the notification area.用户应该可以决定选择他们想在通知区域看到的图标。在向通知区域安装图标时，应该得到用户的允许。也应该提供移除通知区域图标的方法（通常是快捷键）。（扯淡呢这段！）

The NOTIFYICONDATA structure sent in the call to Shell_NotifyIcon contains information that specifies both the notification area icon and the notification itself. The following are those items specific to the notification area icon itself that can be set through NOTIFYICONDATA.Shell_NotifyIcon中使用到的NOTIFYICONDATA结构体包含了通知图标和有关通知的信息。下面就是通过NOTIFYICONDATA可以对通知区域做的设置。

• The resource from which the icon is taken. 哪一个图标资源。
• A unique identifier for the icon. 唯一的图标ID。
• The style of the icon's tooltip. 图标提示风格。
  
• The icon's state (hidden, shared, or both) in the notification area. 通知区域中图标的状态。
• The handle of an application window associated with the icon. 关联到图标的应用程序窗口句柄。
• A callback message identifier that allows the icon to communicate events that occur within the icon's bounding rectangle and balloon notification with the associated application window. The icon's bounding rectangle can be retrieved throughShell_NotifyIconGetRect. 回调信息的ID，允许图标把发生在其矩形边界内的事件关联到应用程序窗口。可以通过Shell_NotifyIconGetRect来获得图标的边界矩形。
  

Each icon in the notification area can be identified in two ways:每一个在通知区域的图标可以通过线面两种方式标识：

• The GUID with which the icon is declared in the registry. This is the preferred method on Windows 7 and later.使用注册的GUID，Win7及其之后系统支持。
• The handle of a window associated with the notification area icon, plus an application-defined icon identifier. This method is used on Windows Vista and earlier.与区域图标关联的窗口句柄以及在程序中定义的图标ID。

Icons in the notification area can have a tooltip. The tooltip can be either a standard tooltip (preferred) or an application-drawn, pop-up UI. While a tooltip is not required, it is recommended.通知区域中的图标可以有一个提示信息。提示信息可以是一个标准的提示文本（推荐），也可以是应用程序绘制的弹出式界面。提示信息并不是必要的，我们只是推荐使用。

Notification area icons should be high-DPI aware. An application should provide both a 16x16 pixel icon and a 32x32 icon in its resource file, and then useLoadIconMetric to ensure that the correct icon is loaded and scaled appropriately.通知区域图标应该使用高DPI。应该用程序应该同时提供16×16和32×32的资源，并且使用LoadIconMetric函数来确保加载正确的图标并且适当的缩放。

The application responsible for the notification area icon should handle a mouse click for that icon. When a user right-clicks the icon, it should bring up a normal shortcut menu. However, the result of a single click with the left mouse button will vary with the function of the icon. It should display what the user would expect to see in the form best suited to that content—a popup window, a dialog box or the program window itself. For instance, it could show status text for a status icon, or a slider for the volume control.应用程序应该处理对通知区域图标的进行鼠标单击的情况。当用户右击图标时，应该弹出一个右键快捷菜单。然而，鼠标单击的结果应该因不同的图标而不同。程序一个该显示用户在这种情况下最想看见的内容——弹出的窗口，对话框或者程序自身。例如，应该为状态图标显示状态文本，或者为音量控制显示滑动条。

The placement of a popup window or dialog box that results from the click should be placed near the coordinate of the click in the notification area. Use theCalculatePopupWindowPosition to determine its location.通过点击图标而弹出的窗口或者对话框的位置，应该在通知区域的点击位置附近。使用CalculatePopupWindowPosition来决定位置。

The icon can be added to the notification area without displaying a notification by defining only the icon-specific members of NOTIFYICONDATA (discussed above) and calling Shell_NotifyIcon as shown here:可以只向通知区域添加图标而不显示通知——只要仅提供NOTIFYICONDATA和调用Shell_NotifyIcon就可以了。

NOTIFYICONDATA nid = {};
// Do NOT set the NIF_INFO flag.
...                    
Shell_NotifyIcon(NIM_ADD, &nid);

You can also add the icon to the notification area and display a notification all in one call toShell_NotifyIcon. To do so, continue with the instructions in this topic.当然你也可以在一次调用Shell_NotifyIcon中添加图标并且显示通知。欲知详情，看下文分解。

Define the NOTIFYICONDATA Version 定义通知图标的版本

As Windows has progressed, the NOTIFYICONDATA structure has expanded to include more members to define more functionality. Constants are used to declare which version ofNOTIFYICONDATA to use with your notification area icon, to allow for backward compatibility.Unless there is a compelling reason to do otherwise, it is strongly recommended that you use the NOTIFYICON_VERSION_4 version, introduced in Windows Vista. This version provides the full available functionality, including the preferred ability to identify the notification area icon though a registered GUID, a superior callback mechanism, and better accessibility.随着Windows已取得进展，这notifyicondata结构已扩大到包括更多的成员定义更多的功能。随着Windows不断的发展，notifyicondata结构已扩大到包括更多的成员定义更多的功能。常量用来声明通知区域中用到的NOTIFYICONDATA版本，允许向后兼容。如果不是必须考虑兼容性，强烈建议使用从Vista开始引进的NOTIFYICON_VERSION_4版本。这个版本提供了所有可用的功能，包括推荐的GUID来标识通知图标，更好的回调机制和更好的访问性。

Set the version through the following calls:使用下列代码：

NOTIFYICONDATA nid = {};
... 
nid.uVersion = NOTIFYICON_VERSION_4;
// Add the icon
Shell_NotifyIcon(NIM_ADD, &nid);
// Set the version
Shell_NotifyIcon(NIM_SETVERSION, &nid);

Note that this call to Shell_NotifyIcon does not display a notification.调用版本的代码不会显示图标。

Define the Notification Look and Contents 定义通知外观和内容

A notification is a special type of balloon tooltip control. It contains a title, body text, and an icon. Like a window, it has a Close button in its upper right corner. It also contains aOptions button that opens the Notification Area Icons item in the Control Panel, which allows the user to show or hide the icon or show only notifications without an icon.通知是特殊的气泡通知控件。它包括标题、主文本以及图标。跟窗口类似，在它的右上角也有关闭按钮。它还有一个选项按钮用来打开控制面板的通知区域图标项，以允许用户显示或者隐藏图标或者仅显示通知而不显示图标。

The NOTIFYICONDATA structure sent in the call to Shell_NotifyIcon contains information that specifies both the notification area icon and the notification balloon itself. The following are those items specific to the notification that can be set throughNOTIFYICONDATA.调用Shell_NotifyIcon时用到的结构体NOTIFYICONDATA指定了通知区域图标和通知气泡。下面的项目可以通过NOTIFYICONDATA来设置：

• An icon to display in the notification balloon, which is specified by the notification type. The size of the icon can be specified, as well as custom icons.通知气泡中的图标，通过通知类型来设置。大小和平常用的图标一样。
• A notification title. This title should be a maximum of 48 characters long in English (to accommodate localization). The title is the first line of the notification, and set apart through the use of font size, color, and weight.通知标题。最多48个英文字符长度。标题是气泡的第一行，可以通过字体、文字颜色、文字大小来与主文本区分。
• Text for use in the body of the notification. This text should be a maximum of 200 characters in English (to accommodate localization).通知文本。最多200个英文字符。
• Whether the notification should be discarded if it cannot be displayed immediately.当通知不能立即显示时是否取消。
• A timeout for the notification. This setting is ignored in Windows Vista and later systems in favor of a system-wide accessibility timeout setting.通知超时时间。
• Whether the notification should respect quiet time, set through the NIIF_RESPECT_QUIET_TIME flag.通过NIIF_RESPECT_QUIET_TIME标志来决定通知是否遵循通知时间。

Note  The IUserNotification and IUserNotification2 interfaces are Component Object Model (COM) wrappers forShell_NotifyIcon. However, at this time, they do not provide the full NOTIFYICON_VERSION_4 functionality available throughShell_NotifyIcon directly, including the use of a GUID to identify the notification area icon.IUserNotification和IUserNotification2接口采用COM方式封装了Shell_NotifyIcon。但是并没有直接提供Shell_NotifyIcon的NOTIFYICON_VERSION_4功能，也没有提供GUID标识通知区域的功能。

Check the User Status 检查用户状态

The system uses the SHQueryUserNotificationState function is used to check whether the user is in quiet time, away from the computer, or in an uninterruptable state such as Presentation mode. Whether the system displays your notification depends on this state.系统使用SHQueryUserNotificationSata函数来检查用户是否处于安静时间、暂离，或者处于不可中断的状态——例如演示模式。系统能否显示通知都取决于这些状态。

Note  If your application is using a custom notification method that does not useShell_NotifyIcon,IUserNotification, or IUserNotification2, it should always explicitly call SHQueryUserNotificationState to determine whether it should display notification UI at that time.（扯淡）

Notifications sent when the user is away are queued for display, but because you cannot know when the user will return or whether the notification will still be valid at that time, you might consider resending the notification later.用户暂离时发送的通知会进入显示队列，但是由于不能预测用户什么时候回来也不能确定用户回来时通知是可用的，所以最好是再次发送通知。

Notifications sent during quiet time are discarded unshown. Design guidelines ask that all notifications be ignorable. They should not require immediate user action. Therefore, no notification is so important that it should override quiet time.在安静时间发送的通知是不会显示的。设计规范要求忽略这种通知。忽略时不需要用户操作。因此安静时间内没有通知是很重要的。（？？？）

Display the Notification 显示通知

Once you have set the NOTIFYICONDATA version and defined the notification in a NOTIFYICONDATA structure, call Shell_NotifyIcon to display the icon.设置了版本和定义了结构体之后，调用Shell_NotifyIcon来显示图标。

• If the notification area icon is not present, call Shell_NotifyIcon to add the icon. Do this for both transient and non-transient icons.如果当前没有通知区域图标，使用下面的代码添加。可添加临时和非临时图标。
  NOTIFYICONDATA nid = {};
  ...                    
  Shell_NotifyIcon(NIM_ADD, &nid);
  
  

• If the notification area icon is already present, call Shell_NotifyIcon to modify the icon.如果已有通知区域图标，通过下面的代码来修改图标。
  NOTIFYICONDATA nid = {};
  ...                    
  Shell_NotifyIcon(NIM_MODIFY, &nid);
  
  

The following code shows an example of setting NOTIFYICONDATA data and sending it through Shell_NotifyIcon. Note that this example identifies the notification icon through a GUID (preferred in Windows 7).下面的代码是Win7下通过GUID来设置通知区域图标的一些代码。

// Declare NOTIFYICONDATA details. 
    // Error handling is omitted here for brevity. Do not omit it in your code.
    
    NOTIFYICONDATA nid = {};
    nid.cbSize = sizeof(nid);//设置大小
    nid.hWnd = hWnd;
    nid.uFlags = NIF_ICON | NIF_TIP | NIF_GUID;//采用GUID
    
    // Note: This is an example GUID only and should not be used.
    // Normally, you should use a GUID-generating tool to provide the value to
    // assign to guidItem.
    static const GUID myGUID = 
    {0x23977b55, 0x10e0, 0x4041, {0xb8, 0x62, 0xb1, 0x95, 0x41, 0x96, 0x36, 0x69}};
    nid.guidItem = myGUID;
    
    nid.guidItem = guid;//？？？？不应该有这行，微软秀逗了？？
    
    // This text will be shown as the icon's tooltip.
    StringCchCopy(nid.szTip, ARRAYSIZE(nid.szTip), L"Test application");//按字符计数
    
    // Load the icon for high DPI.
    LoadIconMetric(hInst, MAKEINTRESOURCE(IDI_SMALL), LIM_SMALL, &(nid.hIcon));
    
    // Show the notification.
    Shell_NotifyIcon(NIM_ADD, &nid) ? S_OK : E_FAIL;//复制代码都不认真，真是无节操。

Removing an Icon 移除图标

To remove an icon—for instance, when you have only added the icon temporarily to broadcast a notification—callShell_NotifyIconas shown here. Only a minimal NOTIFYICONDATA structure that identifies the icon is needed in this call.想要移除图标——例如当你仅是添加一个图标来临时显示一个通知，调用Shell_NotifyIcon就可以。只需要在调用中提供一个NOTIFYICONDATA结构体。

NOTIFYICONDATA nid = {};
...                    
Shell_NotifyIcon(NIM_DELETE, &nid);

Note  When an application is uninstalled, its notification area icon can still appear to the user as an option in the Notification Area Icons page in the Control Panel for up to seven days. However, any changes made there will have no effect.当程序卸载时，通知区域图标仍旧会在控制面板的通知区域图标页面显示7天。放弃吧少年，它赖在那里，由着它去吧。

SDK Sample

See the NotificationIcon Sample sample in the Windows Software Development Kit (SDK) for a full example of the use ofShell_NotifyIcon.

Related topics

Shell_NotifyIcon Shell_NotifyIconGetRect NOTIFYICONDATA SHQueryUserNotificationState IUserNotification IUserNotification2 The Taskbar Taskbar Extensions