Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
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 InitializeCustomItemfunction (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 CustomItemOptionsDlgProcas ordinal 241. The .def file for the DLL should contain the following:

Copy Code 
EXPORTS
InitializeCustomItem @ 240 NONAME
CustomItemOptionsDlgProc @ 241 NONAME

After the window is created, the Home screen sends WM_TODAYCUSTOM_QUERYREFRESHCACHEto 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 TRUEonly 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_PAINTto 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_CLEARCACHEmessage with a wParamof the TODAYLISTITEMstructure for that Home screen plug-in. If your component caches data, generally pointed to by the prgbCachedDatamember 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_CLEARCACHEmessage 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_LBUTTONUPmessage 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 TODAYDRAWWATERMARKINFOstructure 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.

See Also