Writing a Custom Today Screen Item
A custom Today screen item is simply a DLL that implements a specific interface and is registered in such a way that the Today 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 Today screen items. If the Today screen item 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 Today 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 Today 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 Today screen no longer sends WM_PAINT to the child window if you set the window height to zero.When the Today 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 Today item. 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 Today items that do not cache any data, the WM_TODAYCUSTOM_CLEARCACHE message handler can return 0.
Users can interact with Today screen items, generally by switching to another application and displaying the data that was presented in the Today screen item in that application. The user can then edit or otherwise act upon the data. To facilitate this interaction, Today screen applets should check for the WM_LBUTTONUP message and act accordingly.
In Windows Mobile 2002 software and later, themes, which are combinations of images and color selections, can be applied to the Today screen, so Today screen applets should include code to make their backgrounds appear transparent. You can use the TODAYDRAWWATERMARKINFO structure to do this.
The MemWatcher sample code illustrates how to create a custom Today screen item. If the default installation directories were used to install the Pocket PC SDK, the sample is located in C:\Program Files\Windows CE Tools\wce420\POCKET PC 2003\Samples\Win32\Memwatcher\.
See Also
How to: Install and Register a Custom Today Screen Item
Send feedback on this topic to the authors.
© 2005 Microsoft Corporation. All rights reserved.