Writing a Custom Windows Classic Home Screen Plug-in
4/8/2010
A custom Windows Classic Home screen plug-in is a DLL that implements a specific interface and is registered in such a way that the Windows Classic Home screen can find it. Each DLL must export one required and one optional function at specific ordinals. The InitializeCustomItem function (ordinal 240), which creates the child window to display the data, is required for all Windows Classic Home screen plug-ins. If the Windows Classic Home screen plug-in supports an options dialog box to allow the user to make changes in what content is shown or how it appears, the DLL must also export CustomItemOptionsDlgProc as ordinal 241. The .def file for the DLL should contain the following:
EXPORTS
InitializeCustomItem @ 240 NONAME
CustomItemOptionsDlgProc @ 241 NONAME
After the window is created, the Home screen sends WM_TODAYCUSTOM_QUERYREFRESHCACHE to the child window every two seconds to determine whether the displaying data has changed and must be repainted. To minimize repainting of the Home screen, each item should respond TRUE only if the data must be repainted. This is the only time you can update the height of your window. The Home screen no longer sends WM_PAINT to the child window if you set the window height to zero.When the Home screen application must force all components to refresh their data, it sends the WM_TODAYCUSTOM_CLEARCACHE message with a wParam of the TODAYLISTITEM structure for that Home screen plug-in. If your component caches data, generally pointed to by the prgbCachedData member of the structure, it should free this memory upon receipt of this message. For Home screen plug-ins that do not cache any data, the WM_TODAYCUSTOM_CLEARCACHE message handler can return 0.
Users can interact with Windows Classic Home screen plug-ins, generally by switching to another application and displaying the data that was presented in the Home screen plug-in in that application. The user can then edit or otherwise act upon the data. To facilitate this interaction, Windows Classic Home screen applications should check for the WM_LBUTTONUP message and act accordingly.
In Pocket PC 2002 software and later, themes, which are combinations of images and color selections, can be applied to the Windows Classic Home screen, so Windows Classic Home screen applications should include code to make their backgrounds appear transparent. You can use the TODAYDRAWWATERMARKINFO structure to do this.
Remarks
The Windows Mobile Professional SDK ships with a code sample named Memory Watcher. It demonstrates how to create a custom Windows Classic Home screen plug-in. By default, it is installed into the following folder: C:\Program Files\Windows Mobile 6.5.3 DTK\Samples\PocketPC\CPP\win32\memwatcher\memwatcher.sln.