Today Screen Plug-in Selection API

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

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.

注册表注册键值
开始接受"选择焦点"通知时,必须在注册表中为插件设置Selectability标志值为2，如下
Copy Code

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

如果Selectability的值是0或者不存在，此时插件将不能被选择，并且不能接受任何通知。

如果Selecttability的值为1，此时"今日屏幕"自动管理条目的选择，并且也不发送任何通知消息到插件。

接受选择焦点

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:

当用户导航"今日屏幕"条目，插件将接受一个WM_TODAYCUSTOM_RECEIVEDSELECTION 消息，不管Selectability的值是什么，该插件都将接受 WM_ERASEBKGND 和 WM_PAINT 消息，以便从画它的内容。

Copy Code

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:

"今日屏幕"插件也能接受选择焦点-例如，当用户发出点击，插件必须发送TODAYM_TOOKSELECTION消息给它的主窗口， "今日屏幕"将回应TODAYM_RECEIVEDSELECTION 消息。

Copy Code

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:

Copy Code

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: 

Copy Code

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.