Windows mobile Today Screen 基础

  原文为：MSDN的 Today Screen 

 前引 

在Windows Mobile 6 Professional 和 Windows Mobile 6 Classic，今日屏幕是用户可以启动他们大多数程序的地方。今日屏幕提供以下优势：

• 用户自己定制开始点
• 对今日插件的一致访问
• 移动运营商可以提供其品牌信息 

今日屏幕给用户提供一个集中的地方来方便的查看Windows Mobile 6 Professional 和 Windows Mobile 6 Classic设备中的主要信息和高优先级信息。开发人员可以为他们的程序创建一个定制的今日屏幕插件来提供关键信息。例如，一个销售自动化程序能够给销售人员提供当天将要拜访的顾客的重要信息。设备也可以自动超时并在一个用户配置的终止时间段后返回到今日屏幕，默认时间为4小时。(也就是如果屏幕在4小时内没有任何事件响应，将自动进入今日屏幕)。

注意：

默认，Windows Mobile 6 Professional 和 Windows Mobile 6 Classic包含Messaging, Calendar, Tasks, 和Owner Information等今日屏幕程序。用户可以选择在今日屏幕中是否显示或按照什么顺序显示这些程序。

 

 编写今日插件项 (Writing a Custom Today Screen Item)

一个定制的今日屏幕插件简单的说就是个DLL，它实现指定的接口然后以今日屏幕能够查找的方式注册。每个DLL必须按照指定序号导出一个要求的函数和一个可选函数。InitializeCustomItem(序号为240)创建子窗口来显示数据，这是所有今日屏幕插件必须要求的函数。如果今日屏幕插件支持选择对话框来允许用户做出改变，比如显示什么内容或怎么显示，那么该DLL必须导出CustomItemOptionsDlgProc(序号为241)。为该DLL指定.def文件，内容如下：

EXPORTS
InitializeCustomItem @ 240 NONAME
CustomItemOptionsDlgProc @ 241
NONAME

窗口创建后，今日屏幕每2秒钟发送一次WM_TODAYCUSTOM_QUERYREFRESHCACHE消息给子窗口来检查显示数据是否发生改变并需要重绘。要想最少次数的重绘今日屏幕，每个插件必须仅在数据需要重绘时才返回TRUE，这也是唯一需要更新窗口高度的时候。如果窗口高度设置为0，今日屏幕不再发送WM_PAINT到子窗口。当今日屏幕程序必须强制所有组件刷新他们的数据时，将发送WM_TODAYCUSTOM_CLEARCACHE消息和TODAYLISTITEM结构类型的wParam参数到今日插件。如果你的组件缓存了数据（由TODAYLISTITEM结构的prgbCachedData成员指向），那么应该在收到该消息时释放内存。对于没有缓存任何数据的今日插件项，WM_TODAYCUSTOM_CLEARCACHE消息句柄可以返回0。

用户可以和今日屏幕插件进行交互，一般通过切换到其他程序，然后在该程序中显示呈现在今日屏幕插件项中的数据。用户随后可以编辑或操作这些数据。为了更方便进行这些交互，今日屏幕程序应该检查WM_LBUTTONUP消息并做出相应的动作。

在Pocket PC 2002 软件，随后是主题，都是图像和颜色选择的组合，他们都可以应用到今日屏幕，因此今日屏幕程序应该包括是背景显示透明的代码。你可以使用TODAYDRAWWATERMARKINFO结构来完成这个效果。

备注：

Windows Mobile 6 Professional SDK有一个叫做“Memory Watcher”的代码例子。它描述了怎样创建一个今日屏幕插件。默认，一般在 C:\Program Files\Windows Mobile 6 SDK\Samples\PocketPC\CPP\win32\memwatcher\memwatcher.sln 位置下可以找到。

 怎样装载和注册一个定制的今日屏幕插件 (How to: Install and Register a Custom Today Screen Item)

要装载一个定制的今日插件，需要为今日组件拷贝该DLL然后注册该组件。

要注册一个在Sample.dll中实现的“My Today Item”组件：

1.  在HKEY_LOCAL_MACHINE\Software\Microsoft\Today\Items 下创建一个叫做 “My Today Item”的新键。
2.  在HKEY_LOCAL_MACHINE\Software\Microsoft\Today\Items\My Today Item 下添加在下表中显示的值。

值名	类型	数据	说明：
Type	DWORD	4	所有定制的插件都为4
Enabled	DWORD	1	0或1。标识该插件是否在今日屏幕中显示。如果Enabled=0，用户可以在Setting页面今日程序中的Items标签列表下选中单选框来显示该插件。
Options	DWORD	1	0或1。标识插件是否有Options对话框
DLL	String	"\Windows\Sample.DLL"	DLL的全路径或名称
Selectability	DWORD	1	0，1或2。0代表不支持可选；1代表插件支持可选，shell将会处理Up/Down消息；2代表插件支持可选，并且自己处理Up/Down消息。

你最有可能使用CabWiz 创建一个.cab文件来装载今日插件，下面的例子显示了.inf文件中将会显示的注册信息。

[Reg.All]
HKLM,Software\\cf3 Microsoft\\cf3 Today\\cf3 Items\\cf3 My Today Item,Type,0x00010001,4
HKLM,Software\\cf3 Microsoft\\cf3 Today\\cf3 Items\\cf3 My Today Item,Enabled,0x00010001,1
HKLM,Software\\cf3 Microsoft\\cf3 Today\\cf3 Items\\cf3 My Today Item,Options,0x00010001,1
HKLM,Software\\cf3 Microsoft\\cf3 Today\\cf3 Items\\cf3 My Today Item,Selectability,0x00010001,2
HKLM,Software\\cf3 Microsoft\\cf3 Today\\cf3 Items\\cf3 My Today Item,DLL,0x00000000,"\Windows\Sample.DLL" 

附：

如果DLL值指向的位置不在Windows 目录，插件那么将不会运行。

对于DLL值，有如下几点发现：

1.  不一定需要完全路径。如果没完全路径，默认为 "\Windows" 目录
2.  如果指定了路径，它只能是 "\Windows\..."。将路径设置到其他目录(比如"\Program Files\MyAppDir\...") 将导致不能正常加载和显示你的今日插件项。
   
   

 导航今日屏幕插件中的Icons (Navigating Icons in Today Screen Plug-in)

今日屏幕插件中的icons支持硬件导航。可以使用导航键、键盘或光笔来导航icons。一旦接收聚焦，最左边的icon将高亮显示。

  使用导航键导航icons下表显示用来导航icons的导航键

键	动作
Left	移动焦点至左侧icon。如果当前icon已经是最左边，释放焦点至前一个插件。
Right	移动焦点至右侧icon。如果当前icon已经是最右边，释放焦点至下一个插件。
Down	释放焦点至下一个插件
Up	释放焦点至上一个插件
Action	该键就象是点击屏幕上的icon一样，可以模拟成发送一个点击消息(位于icon的中心)到拥有该icon的程序。
[Other]	什么也不做.

 
  使用键盘导航icons

下表显示用来导航icons的键盘键

键	动作
Left	和导航键一样
Right	和导航键一样
Down	和导航键一样
Up	和导航键一样
Enter	和导航键一样
[Other]	什么也不做.

  使用光笔导航icons

用户点击icon来触发相应事件。

  异常

  如果用户在选择icon时旋转设备屏幕，选择将被取消

  如果icon被选择并且拥有icon的进程已经从今日屏幕中移除，选择将被取消

 选择今日屏幕插件(Today Screen Plug-in Selection)

The Windows Mobile 6 Professional and Windows Mobile 6 Classic 今日屏幕可以不使用光笔单手操作。正因为该特点，今日屏幕所有项接收选择通知消息。这些消息和WM_SETFOCUS和WM_KILLFOCUS消息类似，都是由Windows Mobile软件发送到子窗体控件。该部分描述怎样通知今日屏幕插件消息通知。

Windows Mobile软件自动处理还没有更新的今日屏幕插件的选择来支持选择焦点通知。如果插件的响应依赖屏幕点击，则必须更新插件以支持选择焦点通知。

注意：

该部分定义的所有消息都在todaycmn.h 头文件中包含。

 
该部分包含：

• Receiving the Selection Focus：描述WM_TODAYCUSTOM_RECEIVEDSELECTION 和 TODAYM_DRAWWATERMARK消息。
• Taking the Selection Focus：描述TODAYM_TOOKSELECTION消息。
• Receiving Keypad Presses：描述action和导航消息。
• Losing the Selection Focus：描述WM_TODAYCUSTOM_LOSTSELECTION消息。
• Drawing the Today Screen Watermark：描述TODAYM_DRAWWATERMARK消息。
  
  

  接收选择焦点(Receiving the Selection Focus)

当用户使用键盘导航今日屏幕项时，插件接收一个WM_TODAYCUSTOM_RECEIVEDSELECTION消息。而且，不管Selectability的值为多少，它都接收一个WM_ERASEBKGND消息和一个WM_PAINT消息以便重画它的内容。

给父窗口发送TODAYM_DRAWWATERMARK消息将总是绘制一个未选的背景(除非今日屏幕项背选中并且Selectability值为1，此时高亮背景被绘制)。当Selectability值为1，并不需要修改代码来绘制正确的背景，但是如果值为2，插件必须绘制它自己的背景。应该使用TODAYCOLOR_HIGHLIGHT(0x10000022)色作为他的背景色，TODAYCOLOR_HIGHLIGHTEDTEXT(0x10000023)色作为它的前景色——全部可以通过TODAYM_GETCOLOR消息得到。

WM_TODAYCUSTOM_RECEIVEDSELECTION定义为 (WM_USER + 244)，wParam 参数将设置为虚键码来导航该项(比如，VK_DOWN 或 VK_UP)；lParam 参数不被设置。如果插件接受选择改变，它应该返回TRUE，否则，今日屏幕将选择传递到下一项。下面的代码例子显示了今日屏幕将选择传递到下一项。

case  WM_TODAYCUSTOM_RECEIVEDSELECTION:
     g_bSelected =  TRUE;
     return  TRUE;

  处理选择焦点(Taking the Selection Focus)

今日屏幕插件也能请求选择焦点，比如响应一个用户点击。要做到这点，插件必须发送TODAYM_TOOKSELECTION消息到它的父窗口。

TODAYM_TOOKSELECTION定义为(WM_USER + 102)。wParam 参数为插件窗口句柄。lParam 参数不被使用，可以设置为0。

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

  接收键盘按下(Receiving Keypad Presses)

一旦今日屏幕插件有选择焦点，每次键盘按钮按下都会使其接收一个WM_TODAYCUSTOM_USERNAVIGATION 消息。如果插件在内部处理键盘按下，它应该返回TRUE来响应该消息。 另外，如果上下键被按下，今日屏幕传递选择到下一项，可以使用此来导航一系列子项。

WM_TODAYCUSTOM_USERNAVIGATION 定义为(WM_USER + 246)。wParam 参数设置为虚键码（比如VK_UP, VK_LEFT等）；不使用lParam参数。

action 按键使用不同的方式处理。如果action 按键被按下，插件接收一个WM_TODAYCUSTOM_ACTION 消息，除非Selectability 值为1，此时它在(1,1)坐标接收一个WM_LBUTTONDOWN消息和一个WM_LBUTTONUP消息来模拟用户点击。

WM_TODAYCUSTOM_ACTION 定义为(WM_USER + 247)。wParam 参数等于action键的虚键值(比如，VK_RETURN)；不使用lParam 参数。取消消息的返回值。看下面的例子：

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;

 

  失去选择焦点(Losing the Selection Focus)

当插件时区焦点，它会收到一个WM_TODAYCUSTOM_LOSTSELECTION消息。不管Selectability 注册值为多少，插件都会接收WM_ERASEBKGND 和 WM_PAINT 消息以便能够重绘它的内容。

 

注意：

当插件接收到 WM_TODAYCUSTOM_LOSTSELECTION 消息后必须调用 InvalidateRect来确保当滚动时被正确的刷新。

 
WM_TODAYCUSTOM_LOSTSELECTION定义为(WM_USER + 245)。wParam 和 lParam都不使用，返回值也取消。如下例：

 

case WM_TODAYCUSTOM_LOSTSELECTION:
    g_bSelected = FALSE;
    break;

  绘制今日屏幕水印图案(Drawing the Today Screen Watermark)

当今日屏幕插件发送TODAYM_DRAWWATERMARK消息到它的父窗口(今日屏幕)时，今日屏幕将绘制相应的水印。消息的lParam 参数是一个指向TODAYDRAWWATERMARKINFO 结构的指针，该结构在todaycmn.h头文件中可以找到。

在插件中，该消息可以在WndProc 中通过一个消息来处理：

case WM_ERASEBKGND:
    {
        TODAYDRAWWATERMARKINFO twm;
        twm.hdc = (HDC)wParam;
        twm.hwnd = hWnd;

        GetClientRect(hWnd, &(twm.rc));
        SendMessage(GetParent(hWnd), TODAYM_DRAWWATERMARK, 0, (LPARAM)&twm);
    }
    break;

 

 今日屏幕插件注册设置(Today Screen Plug-in Registry Settings)

HKEY_LOCAL_MACHINE\Software\Microsoft\Today\Items 注册键控制今日屏幕插件的特性。下表显了HKEY_LOCAL_MACHINE\Software\Microsoft\Today\Items 注册键下的命名值：

值：类型	描述
Enabled : DWORD	该值控制用户是否在今日屏幕中开启或禁用插件项。 如果Enabled=0，插件不会在今日屏幕中显示，用户可以在今日控制面板中开启。 如果Enabled=1，显示插件，同样可以今日控制面板中禁用它。
Order : DWORD	该值控制插件在今日屏幕中的次序。如果Order=0，插件将在最上端显示。
Selectability : DWORD	该值开启选择焦点通知(enables the selection focus notifications)。 如果该值为0或不存在，插件不可选并且不会接受任何通知。 如果值为1，今日屏幕自动管理插件项的选择，并且不会给插件发送任何通知消息。 如果值为2，今日屏幕使用今日屏幕选择APIs(Today Screen selection APIs)来跟踪当前的选择项。
Type : DWORD	该值标识插件类型。 如果值为0，标识一个保留的插件被添加到今日屏幕，该插件显示设备机主信息。 如果值为1，标识一个保留的插件被添加到今日屏幕，该插件显示Appointments信息。 如果值为2，标识一个保留的插件被添加到今日屏幕，该插件显示Mail信息。 如果值为3，标识一个保留的插件被添加到今日屏幕，该插件显示Tasks信息。 如果该值为4，一个定制的插件被添加到今日屏幕。
Options : DWORD	标识插件是否有Options对话框，在今日屏幕控制面板中点击选中"Options"按钮会显示该对话框。 如果值为0，禁用"Options"按钮；如果值为1，开启"Options"按钮

下面的代码例子显示了今日屏幕中的一个插件的注册入口：

[HKEY_LOCAL_MACHINE\\cf3 Software\\cf3 Microsoft\\cf3 Today\\cf3 Items\<Your Custom Item Name>]
"Enabled"=dword:1
"Order"=dword:3
"Selectability"=dword:2
"Type"=dword:1
"Options"=dword:0