Using the Today API
Add custom information about your application, company, or other important messages to the Today screen. Here is a very short sample how to get started with the Today API.
Applies to:
Microsoft Windows Powered Pocket PC 2000
Microsoft eMbedded Visual C++
Download the Today API code
Languages Supported
English (and others if applicable)
The Today screen normally contains information about the owner of the Pocket PC, upcoming appointments, tasks and e-mail messages. Microsoft has provided an API to add your own custom information to the Today screen. Information about your application, notification of your application, or other useful statements could be added here and so immediately bring it to the attention of the user. The following very short sample will tell you how to do this.
Creating the MyToday.DLL
- Start eMbedded Visual C++ and create a new WCE Dynamic-Link Library project named MyToday.
- On the second screen of the eMbedded Visual C++ wizard, select An empty DLL.
We now have to create three essential files:
- MyToday.def — Containing two export definitions used by the Today Screen
- MyToday.cpp — the Source file containing our custom code
- MyToday.rc — a Resource file containing a dialog resource
MyToday.def
This definition file contains only three lines:
EXPORTS
InitializeCustomItem @ 240 NONAME
CustomItemOptionsDlgProc @ 241 NONAME
The CustomItemOptionDlgProc is optional but I included it here anyway to show how to use it. The Option Dialog Box will pop up if you go to the Today applet, then Settings, and then select the Options button. The ordinal numbers 240 and 241 are important. Otherwise the Today screen will not be able to load the correct function.
MyToday.cpp
The MyToday.cpp source file contains the code to the exported function and the window procedure for our new child window:
#include <windows.h>
#include <Todaycmn.h>
HINSTANCE hInstance;
HWND APIENTRY InitializeCustomItem(TODAYLISTITEM *ptli,
HWND hwndParent);
LRESULT CALLBACK WndProc(HWND hWnd, UINT message,
WPARAM wParam, LPARAM lParam);
BOOL APIENTRY CustomItemOptionsDlgProc(HWND hDlg, UINT message,
UINT wParam, LONG lParam)
{
switch (message)
{
case WM_INITDIALOG:
return TRUE;
case WM_COMMAND:
if (LOWORD(wParam) == IDOK) {
EndDialog(hDlg, LOWORD(wParam));
return TRUE;
}
break;
//case WM_CTLCOLORSTATIC:
// break;
default:
return DefWindowProc(hDlg, message, wParam, lParam);
}
return 0;
}HWND APIENTRY InitializeCustomItem(TODAYLISTITEM *ptli,
HWND hwndParent)
{
WNDCLASS wc;
HWND hWnd = NULL;
if (ptli->fEnabled==0) return NULL;
hInstance = ptli->hinstDLL;
wc.style = CS_HREDRAW | CS_VREDRAW;
wc.lpfnWndProc = (WNDPROC) WndProc;
wc.cbClsExtra = 0;
wc.cbWndExtra = 0;
wc.hInstance = hInstance;
wc.hIcon = 0;
wc.hCursor = 0;
wc.hbrBackground = (HBRUSH) GetStockObject(LTGRAY_BRUSH);
wc.lpszMenuName = 0;
wc.lpszClassName = TEXT("MyToday");
RegisterClass(&wc);
hWnd = CreateWindow(TEXT("MyToday"), TEXT("MyTodayScreen"),
WS_VISIBLE|WS_CHILD,CW_USEDEFAULT,CW_USEDEFAULT,
240, 25, hwndParent, NULL, hInstance, NULL);
return hWnd;
}LRESULT CALLBACK WndProc(HWND hWnd, UINT message,
WPARAM wParam, LPARAM lParam)
{
HDC hdc;
PAINTSTRUCT ps;
switch (message)
{
case WM_TODAYCUSTOM_CLEARCACHE :
break;
case WM_TODAYCUSTOM_QUERYREFRESHCACHE:
break;
case WM_PAINT:
RECT rt;
hdc = BeginPaint(hWnd, &ps);
GetClientRect(hWnd, &rt);
SetBkMode(hdc,TRANSPARENT);
DrawText(hdc, TEXT("Pocket PC Rules!"), 16, &rt,
DT_SINGLELINE | DT_VCENTER | DT_CENTER);
EndPaint(hWnd, &ps);
break;
case WM_LBUTTONUP:
break;
default:
return DefWindowProc(hWnd, message, wParam, lParam);
}
return 0;
}
Check out the CreateWindow function. Despite the Today API documentation, I created the windows with a vertical size of 25 pixels. Using zero pixels here did not show anything and I never got the "resize" from the "Today" application as the documentation of the Today API promised.
In the WndProc you can use the WM_LBUTTONUP notification to start any application or do other sorts of fun stuff. For more details on the Today API read the eMbedded Visual Tools documentation. A very good article is in the section "Pocket PC SDK/Writing Applications for Pocket PC/Updating Applications for Pocket PC/Customizing Today Items."
MyToday.rc
The option dialog requires a simple dialog resource:
#include "winuser.h" // extract from windows header
#include "winver.h"
#define IDD_TODAY_CUSTOM 500
#define IDC_STATIC_TITLE 444
#define IDC_STATIC_DESC 445
IDD_TODAY_CUSTOM DIALOG DISCARDABLE 0, 0, 140, 57
STYLE DS_CONTROL | WS_POPUP | WS_VISIBLE
CAPTION "My Today Settings"
EXSTYLE WS_EX_CAPTIONOKBTN
BEGIN
LTEXT "MyToday - Options", IDC_STATIC_TITLE,4, 3, 124, 10
LTEXT "Description of the options for your DLL go here.",
IDC_STATIC_DESC, 5, 18, 124, 16
// Other controls go here.
END
Some Registry Settings…
To activate our DLL we have to add the following registry entries using the remote registry editor:
[HKEY_LOCAL_MACHINE\Software\Microsoft\Today\Items\"MyToday"]
"Type"=dword:4 ; 4 == Custom
"Enabled"=dword:0 ; set by the "Settings/Today" applet
"Options"=dword:1 ; set to 0 if you do not want options
"DLL"="\Windows\MyToday.DLL" ; path to the DLL
The Final Step
To activate our new Today message go to the Pocket PC Settings, then to the Today applet, and select your MyToday entry in there. As soon as you select Today in the Start screen you will see your own custom text as shown in the figure.
.gif)
Figure 1: Here's our custom Today screen.
Gotcha
It is extremely difficult to debug such a custom Today library. Every time the Pocket PC starts up it loads your DLL and does not release it even if you deselect it in the Settings/Today applet or even remove the DLL path entry.
To remove the DLL, disable the DLL, change the path to the DLL in the registry setting DLL, and then reset the Pocket PC.