Scott Hunter's
Really Cool Pocket PC Page

Welcome to my Pocket PC page, blah, blah, blah...

What's New
Today Screen Programming Advice
Cool Links

What's New

Today Screen Programming Advice
First off I'd like to start off and mention a couple of the errors that are listed in the following article:
  1. This sample is wrong in that it creates a window with a vertical size greater then zero. You need to create a window with a vertical size of zero. When you receive the WM_TODAYCUSTOM_QUERYREFRESHCACHE message set the cyp field of the TODAYLISTITEM * to the correct vertical size of your today screen item and return TRUE. Your window will be resized automatically.
  2. Before registering the window class with RegisterClass you should attempt to Unregister the class. If this step is not taken your Today application will disappear if the user does a soft-reset of the device and then customizes the Today screen.
Because of all the trouble I had writing a working Today screen application for my device I have decided to post a working sample with the tips and tricks I discovered. The Microsoft documentation for the Today Screen API is very limited and not very detailed. Plus I encountered some problems that were undocumented and basically had to experiment to get it working.

Things to watch out for, proper steps:
  1. You need to create a window that with ZERO height per the API documentation. Your window will be resized to the correct height after you respond to the WM_TODAYCUSTOM_QUERYREFRESHCACHE with your correct size and return TRUE.
  2. It is VERY IMPORTANT to Unregister the window class before registering it. If it is the first time your DLL is called the Unregister will fail but on every other call it will properly unregister the class. Without this call your Today application will fail to display properly in certain circumstances. In these circumstances the WindowProc never gets called after the window is created. These leaves you with an invisible zero height window. Unregistering first seems to solve this problem.
  3. When a user customizes the Today screen either via Start:Settings|Personal|Today or by clicking on the Today banner on the Today screen your window will be destroyed and InitializeCustomItem will be called to create a new window when the user selects OK. You Today application can detect this because it will receive a WM_TODAYCUSTOM_CLEARCACHE after being created in this case. This message is not sent when the unit is soft-reset and your window is created.
  4. Your application will receive WM_TODAYCUSTOM_QUERYREFRESHCACHE message on a periodic basis. The first time you receive this message you will need to set the cyp field of the TODAYLISTITEM * to the correct vertical size of your today screen item and return TRUE. If your vertical size ever changes again you can reset the size and return TRUE again. In all other cases you should return FALSE from this message. When I first started working on my application I returned TRUE from this message when my display data changed but every time you return TRUE from this message the whole Today screen will flash. So I recommend Invalidating just your client area when your display data has changed.

Working on and Debugging Today screen applications can be a pain because once they are loaded they are difficult to unload. I've found the following sequence works best for me.
  1. Use the remote registry editor to edit the DLL string value for your Today screen application. Change it so it doesn't point to your DLL anymore.
  2. Bring your Today page up on your device and click the logo to configure the Today page.
  3. Click OK to close the configuration dialog and your DLL will be unloaded.
  4. Copy the new version of your DLL to your device and fix the DLL string value in the registry to point to the DLL again.
  5. Bring your Today page up on your device and click the logo to configure the Today page. Click OK and your application will be loaded again.
Because all of these steps it I highly recommend using the Today Screen Emulator by Scott Sigelman which will allow you to debug and test your application without all of these steps.

BatteryLevel - This is a useful application that displays available memory and battery power on the Today screen. It has a complete installation program, and is customizable. - This is an example eMbedded Visual C++ 3.0 project which displays the word "TestToday" on the Today screen.

Software Links: - Scott Seligman's CE Apps (including PocketNav and a Today Screen Emulator) - PHM products (includes free Registry editor)

Developer Links: - Free Microsoft Embedded Visual Tools 3.0 (includes C++, Visual Basic and Emulators) - Scott Ludwig's Home page including a free Win32 installation tools for PocketPC applications  
last updated February 19, 2001.  
site designed by: Alt-X Technologies.