Programming Microsoft Windows Ce Net 3Rd [Electronic resources] نسخه متنی

Chapter 11. The Pocket PC notifications can display an icon on the navigation bar at the top of the screen, optionally display an information bubble with HTML text, and even beep the user as necessary. The user can respond by tapping on hyperlinks or buttons within the bubble. These responses are then sent back to the originating application. Unlike the standard Windows CE notifications, the Pocket PC notifications require the application be running and manually set the notification as needed. Once the notification is set, the application can stay running and receive feedback from the notification via window messages or terminate and specify that a COM in-proc server receives the feedback. Figure 17-3 shows a Pocket PC desktop with a notification bubble being displayed.

Figure 17-3: A notification bubble

The bubble is anchored to the application-defined icon on the navigation bar. Notification bubbles have a title and a text body. The bubble window is automatically sized to fit the text.

Adding a Notification

To display a notification, the SHNotificationAdd function is used. Its rather simple prototype is

LRESULT SHNotificationAdd (SHNOTIFICATIONDATA * pndAdd);

The single parameter is a pointer to a not-so-simple SHNOTIFICATIONDATA structure defined as

typedef struct _SHNOTIFICATIONDATA {
DWORD cbStruct;
DWORD dwID;
SHNP npPriority;
DWORD csDuration;
HICON hicon;
DWORD grfFlags;
CLSID clsid;
HWND hwndSink;
LPCTSTR pszHTML;
LPCTSTR pszTitle;
LPARAM lParam;
} SHNOTIFICATIONDATA;

The initial field, cbStruct, is the obligatory size field that must be initialized to the size of the structure. The dwID field will be the ID value for the notification. The ID value will be used to identify any user responses to the notification. The npPriority field is set to either SHNP_ICONIC to have the notification simply display an icon on the navigation bar or to SHNP_INFORM if the notification is to display the bubble text immediately. In the case of SHNP_ICONIC, if the user taps the icon, the bubble text is then displayed. The csDuration field specifies how long the notification should be displayed before the system automatically removes the icon and bubble. Unlike almost every other time parameter in Windows, this csDuration is measured in seconds, not milliseconds. The hIcon field should be set to a 16-by-16 icon that will be used in the navigation bar to display the notification.

The grfFlags flags field can be set with a series of flags that configure the notification. The SHNF_CRITICAL flag changes the color of the title and border of the bubble. The SHNF_FORCEMESSAGE flag displays the bubble even if the registry settings of the device are configured to not display notification bubbles. The SHNF_DISPLAYON flag turns on the display if it's off when the notification is displayed.

The clsid field has two uses. First, it's an identifier for the notification. It should be set to a GUID defined by the application. The second use is to identify a COM in-proc server. The in-proc server is one way the shell can provide feedback to the application. The hwndSink field can also be used in the feedback mechanism. If the hwndSink field is set to a valid window handle, the shell will provide feedback via WM_NOTIFY messages to that window. Feedback is sent when the text bubble is displayed, when it is closed, and when the user taps on any hyperlinks in the HTML text in the bubble. If the clsid field is set to the CLSID of a COM in-proc server that exposes an IShellNotificationCallback interface, the feedback is delivered using calls to the interface's OnShow, OnDismiss, OnCommandSelected, and OnLinkSelected methods. The difference between OnCommandSelected and OnLinkSelected will be explained momentarily.

The pszHTML field can be NULL, in the case of an icon-only notification or either unformatted Unicode text or HTML Unicode text. The HTML text allows for surprisingly elaborate formatting of the text in the bubble. Paragraph breaks, links, and even simple controls can be displayed in the bubble. The following HTML was used to display the bubble shown in Figure 17-4:

<html><body><p>This is a list</p>
<ul>
<li>Item 1</li>
<li>Item 2</li>
<li>Item 3</li>
</ul>
<input type="button" value="Yes" name="cmd:200">
<input type="button" value="No" name="cmd:201">
<input type="button" value="Cancel" name="cmd:202"></p>
<p>&nbsp;</p>
<p>Click <a href="http://www.msnbc.com">here</a> to follow a link.</p>
</body></html>"; </html>

Figure 17-4: Complex HTML displayed in a notification bubble

The pszTitle field should point to a text string that will be the title of the bubble. The final field, lParam, is an application-defined value that will be passed back in the feedback WM_NOTIFY messages or in the callback to the in-proc server.

The feedback received by the application depends on how the user responds to the notification. When the user clicks on the notification icon, the system sends a WM_NOTIFY to the window specified in the hwndSink field. If the application returns a zero, the text bubble will be displayed. If the application returns a nonzero value, the bubble will not be displayed. In this case, the application needs to provide whatever feedback it deems necessary to the user.

The HTML text can contain two types of feedback elements. The first is the standard hyperlink, as shown at the top of the next page.

Click <a href="http://www.msnbc.com">here</a> to go to MSNBC

If the user clicks on a hyperlink, the notification system sends a WM_NOTIFY message to the window with a notification code of SHNN_LINKSEL. The notification structure provides the text of the URL as well as the data defined in the lParam field of SHNOTIFICATIONDATA. If the HREF is in the format CMD:n, as in

Click <a href="cmd:205">here</a> to go to MSNBC

the system sends a WM_COMMAND message instead of a WM_NOTIFY to the window. In this case, the value n is the ID value of the message, and the ID of the notification is returned in lParam. For the in-proc server, clicking the standard hyperlink results in a call to the interface's OnLinkSelected method while clicking on links with the CMD:n format results in the OnCommandSelected method being called. The CMD value 0 is reserved, a value of 1 sends a notification but does not dismiss the bubble, and a command value of 2 does not dismiss the bubble nor does it result in a WM_COMMAND message being sent. Applications should generally use CMD values greater than 2.

When the user dismisses the bubble either by clicking a hyperlink or by clicking on the bubble itself, a final notification that the bubble is being dismissed is sent either by message or to the in-proc server.

Modifying a Notification

Configuration data can be queried from a notification by calling the SHNotificationGetData function. Its prototype is shown here:

LRESULT SHNotificationGetData (const CLSID * pclsid, 
DWORD dwID, SHNOTIFICATIONDATA * pndBuffer);

The first two parameters are pclsid, which points to the CLSID of the notification, and dwID, which specifies the ID of the notification. The function fills in the SHNOTIFICATIONDATA structure pointed to by the third parameter, pndBuffer.

The notification can then be modified by changing the relevant data in the SHNOTIFICATIONDATA structure and calling SHNotificationUpdate, prototyped as

LRESULT SHNotificationUpdate (DWORD grnumUpdateMask, 
SHNOTIFICATIONDATA *pndNew);

The grnumUpdateMask parameter is a set of flags that indicate which of the fields in the SHNOTIFICATIONDATA structure pointed to by pndNew should be used to update the notification. The flags are SHNUM_PRIORITY to change the priority of the notification, SHNUM_DURATION to change the duration, SHNUM_ICON to change the icon, SHNUM_HTML to change the bubble text, and SHNUM_TITLE to change the bubble title text.

Removing a Notification

If the notification is simply an icon, it will be automatically removed when the notification times out. However, if the notification displays a bubble, the timeout value of the notification is used to automatically dismiss the bubble, not the icon. If the bubble text doesn't have a link or command, the user can dismiss the text bubble, but the icon remains. In this case and in the case where the timeout is set to infinite, there needs to be a way for the application to remove the notification. Removing the notification is accomplished with the aptly named SHNotificationRemove function, defined as

LRESULT SHNotificationRemove (const CLSID * pclsid, DWORD dwID);

The two parameters are the CLSID and ID value of the notification.