Creating Custom Today Screen Items

WEBINAR:On-Demand

What is the Today Plug-In?

You obviously know what the Today screen is. You see it every time with the Microsoft logo (or whatever picture you've put beneath). And, you definitely won't be surprised to know that the Today custom component is just a DLL. The only additional fact you should know about it is that such a DLL should export two predefined functions with the given ordinal number:

Being more precise, only the first function is a must. The second one is required if you want to provide an Options dialog for your component. Before you will dig in into code samples, let me highlight a couple of trivial things regarding Today components.

First, your DLL will be loaded at startup by the shell and won't be released until you turn off or reset the device. Unchecking the component in Today's settings panel does not help you at all. Thus, it's pretty hard to debug it. To release the problematic DLL, you should manually change the Registry settings and then reset the PDA.

The next thing to be considered is a place on the screen covered by your component. Due to lack of screen size, you should produce a relatively small-dimensioned GUI. Moreover, if there are too many Today items simultaneously presented on the screen, Windows CE adds a scroll bar, so the actual screen width will be smaller that the standard 240 pixels.

Installing Your Custom Today Item

Your component should be registered to let the OS know about its existence. Literally, it means to make some changes in the Tegistry. You can do it either by preparing a .cab file or developing your own application to update the CE registry. Below is the .inf-file section to command the installer to make the Registry changes:

Initializing a Custom Item

As you have told learned, your DLL will export two functions: InitializeCustomItem and optionally CustomItemOptionsDlgProc. In most cases, you'll want to draw one or more icons or images. An important thing to be noted is that you should load all required resources at attaching the DLL and then release them when you exit:

InitializeComponent simply creates and registers a window class for your custom Today item. The shell will call the InitializeCustomItem function when it attempts to create it initially. This function is responsible for all initialization procedures, windows creation, and so forth. Here, you actually initialize all your internal stuff. Below some sample implementation is presented:

In your sample, you will implement an informational panel to show different, useful system info:

You can see similar implementation; for example, on a HP iPaq 2410. For simplicity, you won't deal with the options dialog. So, coming back to the above snippet, InitializeCustomItem makes a 'black job' of component initialization. Pay attention that it doesn't paint anything. All forthcoming messages will be handled in WndProc.

Creating Custom Today Screen Items

WEBINAR:On-Demand

Processing Window Messages

The window procedure of your custom Today item will handle all Windows messages. Most of them just pass to the default handler. You will be interested in processing the following messages:

WM_TODAYCUSTOM_QUERYREFRESHCACHE

WM_TODAYCUSTOM_CLEARCACHE

WM_TODAYCUSTOM_RECEIVEDSELECTION

WM_TODAYCUSTOM_LOSTSELECTION

WM_TODAYCUSTOM_USERNAVIGATION

WM_TODAYCUSTOM_ACTION

TODAYM_TOOKSELECTION

WM_LBUTTONUP

WM_PAINT

WM_ERASEBKGND

WM_DESTROY

Start from the WM_TODAYCUSTOM_QUERYREFRESHCACHE message. It will be sent to your component to determine whether your data has been updated. So, that's often a good place for requerying your data. Your sample component simply obtains new data values there. Remember that you should return TRUE if the component needs to be updated, or FALSE otherwise.

WM_TODAYCUSTOM_CLEARCACHE is sent to the component's windows when it is about to be unloaded. Here, you can release all resources that your component might use during its lifetime.

Now, here's an overview of newly introduced notification messages, which are controlled by the Selectability value in the Registry. Below, you'll find short explanations on each message. I'd like just remind you that Selectability should be equal to 2 to use and advantage most of these messages.

Message

Description

WM_TODAYCUSTOM_RECEIVEDSELECTION

wParam = nVirtKey, lParam is not used; return FALSE if you want to move selection to the next Today item; the component also will get WM_ERASEBKGND and WM_PAINT messages, regardless of the Selectability value

WM_TODAYCUSTOM_LOSTSELECTION

Sent when a custom item loses selection; neither wParam nor lParam are used

TODAYM_TOOKSELECTION

A Today item may request selection by sending this message to its parent window; in response, the component will get WM_TODAYCUSTOM_RECEIVEDSELECTION notification with wParam = 0 if the request was successful

WM_TODAYCUSTOM_USERNAVIGATION

Received by the Today item when it was selected upon each press of navigation buttons; for example, VK_UP, VK_DOWN, and so forth; your app can use it internally to navigate inside a component's screen between different controls of the plug-in; WinProc should return TRUE if message was processed; otherwise, the selection will be passed to the next component

WM_TODAYCUSTOM_ACTION

The same as the previous message, except that WM_TODAYCUSTOM_ACTION is sent when the user presses the 'Action' button (VK_RETURN); the return value is ignored; if Selectability equals 1, the OS will generate a pair of WM_LBUTTONDOWN/WM_LBUTTONUP messages at coordinates (1,1)

In the sample project, which is based on the Pocket PC 2003 SDK sample MemWatcher, you will use some of the notifications above. Even though your test project will not implement all the nice-to-have features, you'll get the general route of coding.

Processing 'Mouse' Events

When the user clicks on your custom component, WinProc will receive WM_LBUTTONXXX messages. You can process them and conduct specific actions in response to clicks. The sample project simply recognizes to which control area the click belongs, and responds by calling different Control Panel applets:

Conclusion

I hope this article has convinced you that creating custom Today items is kind of fun. You're set up well, having the plug-in's WinProc at hand to process all Windows messages. Besides, the Today API on Windows Mobile 2003 SE provides you with some additions that give you new features. With a relatively small effort, you're ready to create cool and powerful mobile applications.

About the Author

Alex Gusev started to play with mainframes t the end of the 1980s, using Pascal and REXX, but soon switched to C/C++ and Java on different platforms. When mobile PDAs seriously rose their heads in the IT market, Alex did it too. Now, he works at an international retail software company as a team leader of the Mobile R department, making programmers' lives in the mobile jungles a little bit simpler.

Advertiser Disclosure:
Some of the products that appear on this site are from companies from which QuinStreet receives compensation. This compensation may impact how and where products appear on this site including, for example, the order in which they appear. QuinStreet does not include all companies or all types of products available in the marketplace.

Thanks for your registration, follow us on our social networks to keep up-to-date