Today Screen Plug-in Selection API in Windows Mobile 2003 Second Edition Software for Pocket PCs

Microsoft

March 2004

Applies to:
   Windows Mobile™ 2003 Second Edition software for Pocket PCs

Summary: Learn about the new Windows Mobile Second Edition software for Pocket PC feature that allows the user to navigate Today screen items by using the hardware keypad. This new feature allows the Today screen plug-in to receive selection notification messages and to enable navigation within the plug-in from the hardware keypad. (4 printed pages)

Introduction
Registry Values
Receiving the Selection Focus
Taking the Selection Focus
Receiving Keypad Presses
Losing the Selection Focus
Conclusion

The ability to navigate Today screen items using the hardware keypad is a new feature introduced in Windows Mobile™ 2003 Second Edition software for Pocket PCs. This means that the Pocket PC today screen can now be operated single handed, that is without the stylus. Because of this new feature, Today screen items now receive selection notification messages. These messages are analogous to the WM_SETFOCUS and WM_KILLFOCUS messages that Windows sends to child window controls. This article describes how to make Today screen plug-ins aware of these new notifications.

All the messages defined in this document are included in the new todaycmn.h header file contained in the Developer Resources for Windows Mobile 2003 Second Edition package.

To start receiving selection focus notifications, a flag must be set in the registry for the plug-in.

[HKEY_LOCAL_MACHINE\Software\Microsoft\Today\Items\YOURCUSTOMITEMNAME]
   "Selectability"=dword:2

If the value of Selectability is zero or does not exist, then the plug-in cannot be selected, and it never receives any notifications.

If the value of Selectability is equal to one, then the Today screen manages the selection of the item automatically, and does not send any notification messages to the plug-in.

If the value of Selectability is equal to two, as shown above, then the Today screen uses the API described below to track the selection of the current item.

When the user navigates to a Today screen item using the keypad, the plug-in will receive a WM_TODAYCUSTOM_RECEIVEDSELECTION message. Also, regardless of the value of Selectability, it will receive a WM_ERASEBKGND and a WM_PAINT message so that it can redraw its content.

Sending the TODAYM_DRAWWATERMARK message to the parent window will always draw an unselected background — unless the Today screen item is selected and its Selectability value is one, in which case a highlighted background will be drawn. This means that when the value of Selectability is one, no code changes are required to draw the correct background; but if the value is two, the plug-in must draw the background itself. It should use the TODAYCOLOR_HIGHLIGHT color (0x10000022) for its background and the TODAYCOLOR_HIGHLIGHTEDTEXT color (0x10000023) for its foreground — both of which can be found via the TODAYM_GETCOLOR message.

WM_TODAYCUSTOM_RECEIVEDSELECTION is defined as (WM_USER + 244). The parameter wParam will be set to the virtual key code used to navigate to this item (i.e., either VK_DOWN or VK_UP); lParam is not used. If the plug-in accepts the selection change, then it should return TRUE; otherwise, the Today screen will pass the selection along to the next item. For example:

case WM_TODAYCUSTOM_RECEIVEDSELECTION:
   g_bSelected = TRUE;
   return TRUE;

A Today screen plug-in can also request the selection focus – for example, in response to a user tap. To do so, the plug-in must send a TODAYM_TOOKSELECTION message to its parent window. The Today screen will post a TODAYM_RECEIVEDSELECTION message in response, with wParam set to 0, to indicate that the selection change was successful.

TODAYM_TOOKSELECTION is defined as (WM_USER + 102). The parameters wParam and lParam are not used and can be set to zero. For example:

case WM_LBUTTONDOWN:
   PostMessage(GetParent(hwnd), TODAYM_TOOKSELECTION, 0, 0);
   break;

Once the Today screen plug-in has the selection focus, each keypad button press will cause it to receive a WM_TODAYCUSTOM_USERNAVIGATION message. If the plug-in handles the button press internally, it should return TRUE in response to this message. Otherwise, the Today screen will pass the selection on to the next item if either the up or down key was pressed. This could be used to navigate through a series of sub-items.

WM_TODAYCUSTOM_USERNAVIGATION is defined as (WM_USER + 246). The parameter wParam is set to the virtual key code of the keypress (e.g., VK_UP, VK_LEFT, etc); lParam is not used.

The action button is handled differently. If the action button is pressed, the plug-in will receive a WM_TODAYCUSTOM_ACTION message — unless the value of Selectability is equal to one, in which case it will receive a WM_LBUTTONDOWN and a WM_LBUTTONUP message at coordinates (1, 1), simulating a user tap.

WM_TODAYCUSTOM_ACTION is defined as (WM_USER + 247). The parameter wParam is equal to the virtual key code for the action key (i.e., VK_RETURN); lParam is not used. The return value for this message is ignored. For example:

case WM_TODAYCUSTOM_USERNAVIGATION:
   InvalidateRect(hwnd, NULL, FALSE);

   if (wParam == VK_UP)   g_nSelectedItem--;
   if (wParam == VK_DOWN) g_nSelectedItem++;

   if (g_nSelectedItem < 0 || g_nSelectedItem >= MAX_ITEMS)
   {
      return FALSE; // go to the next plug-in
   }
   else
   {
      return TRUE;  // stay in this plug-in
   }

case WM_TODAYCUSTOM_ACTION:
   OnAction();
   break;

When the plug-in loses focus, it will receive a WM_TODAYCUSTOM_LOSTSELECTION message. Also, regardless of the value of the Selectability registry key, it will receive a WM_ERASEBKGND and WM_PAINT message so that it can redraw its content.

WM_TODAYCUSTOM_LOSTSELECTION is defined as (WM_USER + 245). The parameters wParam and lParam are not used, and the return value is ignored. For example:

case WM_TODAYCUSTOM_LOSTSELECTION:
   g_bSelected = FALSE;
   break;

The new Today Screen Selection API allows a developer to enable one handed operation for their today screen plug-in. Although the system will automatically handle the selection of Today screen plug-ins which have not been updated to support this feature, developers who have plug-ins which respond differently depending on where they have been tapped will need to update their plug-ins to support this new feature.