Writing a Windows Mobile Today Screen Plugin

Today Screen is a place to display critical information in Windows Mobile. Windows Mobile by default displays appointments, tasks, messages, calendar, owner information etc… We can create plugin to display our own information. A sample Today Screen looks like:

Sample Today Screen

Today screen plugins are DLL which exports the one required function and one optional function. InitializeCustomItem is the required function and CustomItemOptionsDlgProc is the optional one. The DLL should export the InitializeCustomItem as ordinal 240. This function is called by the Shell process when the Today Screen item is initialized. In this function we can create window to be displayed and initialize whatever variables we are using. This is the only function in which we can set the height of the today item’s window. If the Plugin supports the options dialog, then it should export the CustomItemOptionsDlgProc also. In this function we can create options dialog and present the user whatever options are available. The .def file of the DLL should contain the following EXPORTS section
EXPORTS
InitializeCustomItem @ 240 NONAME
CustomItemOptionsDlgProc @ 241 NONAME
After creating the Today item’s window, the system will send the WM_TODAYCUSTOM_REFRESHCACHE message to the window. The WPARAM parameter will contains a pointer to the TODAYLISTITEM structure. This structure and all Today Screen related structures are defined in todaycmn.h header file. The TODAYLISTITEM structure is defined as:
struct _TODAYLISTITEM
{
CHAR szName[MAX_ITEMNAME];
TODAYLISTITEMTYPE tlit;
WORD dwOrder;
DWORD cyp;
OOL fEnabled;
BOOL fOptions;
WORD grfFlags;
TCHAR szDLLPath[MAX_PATH];
INSTANCE hinstDLL;
HWND hwndCustom;
OOL fSizeOnDraw;
BYTE * prgbCachedData;
WORD cbCachedData;
};
The fEnabled member of the structure will be TRUE if the Today item is enabled, otherwise it will be FALSE. The cyp member should contain the height of the windows, if this member is set to 0, the system will not send the WM_TODAYCUSTOM_REFRESHCACHE message.
The syntax of the InitializeCustomItem is:
HWND APIENTRY InitializeCustomItem(TODAYLISTITEM *pItem,HWND hWndParent);
The hWndParent parameter will be the handle of the Today Item’s parent window. If the Today item is not enabled we should immediately return NULL.
The system sends WM_TODAYCUSTOM_CLEARCACHE message to the Today item’s window when it is about to be unloaded. The WPARAM parameter contains a pointer to the TODAYLISTITEM structure. Upon receiving this message we can clear and cached data or any allocated memory we are using and return.
Whenever the Options button is clicked the system will call the CustomItemOptionsDlgProc function. One more requirement is that you should provide the resource for the dialog to be displayed and its resource id should be 500.
In our simple example we just display the battery status and internal memory status. If the battery is charging it will display the string “Charging…” otherwise displays the battery percentage. We will also display percentage of how much memory is used.
The today screen looks like this.

Our Today Screen

Many modifications can be done to this sample. One simple modification is to avoid flickering. To do this we can use double buffering or something else. I left this to your imagination.
In this example, to get the battery and memory status we use GetSystemPowerStatusEx and GlobalMemoryStatus functions.
The plugin has to be registered in the registry for the Today Screen to find and locate the custom items. The Registry key is [HKEY_LOCAL_MACHINE]SoftwareMicrosoftTodayItems]. Each Today Screen items should create a subkey with its name under this key. It should contain the following values:
• Name Containing the name of the item.
• DLL Contains the full path name of the DLL implementing the item.
• Flags User-defined DWORD value returned in the grfFlags field of TODAYLISTITEM.
• Options DWORD value set to 1 if the item supports an Options dialog box.
• Enabled DWORD value set to 1 if the item is enabled.
• Type Custom items must set this DWORD value to 4.
We can use Windows CE Remote Registry Editor to edit the key or we can use the CabWiz.exe file to create installation CAB file and specify these key in the .INF file.
Hope this article will give you an introduction to the Today Screen plugins. There are many resources available on the Internet. Just search for the Today Screen API and you will find many examples.
The example is only tested on I-Mate K-JAM, but may work in any other platforms.