Really Cool Pocket PC Page
Welcome to my Pocket PC page, blah, blah, blah...
Today Screen Programming Advice
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: http://www.microsoft.com/mobile/pocketpc/stepbystep/todayapi.asp
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.
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.
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.
Things to watch out for, proper steps:
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.
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.
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.
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.
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.
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.
Bring your Today page up on your device and click the logo to configure the Today page.
Click OK to close the configuration dialog and your DLL will be unloaded.
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.
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.
- 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.
- Scott Seligman's CE Apps (including PocketNav and a Today Screen Emulator)
- PHM products (includes free Registry editor)
- 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