PocketBuilder lets you add a custom item to the Today screen that can launch a PocketBuilder application. You set the properties for a custom Today item in the Application painter:
Property |
Description |
|---|---|
DisplayText |
Text that displays when the custom item first displays. If you do not specify a display application, this text is always used. |
DisplayApplication |
An application that changes the appearance of the custom item dynamically. For example, the application might have a timer event that replaces the display text with a reminder of when to run the application the item launches. |
Name |
The name used to identify the custom item in the Windows CE registry. |
RunApplication |
The name of the application to be launched when the user taps the custom item. This can be the same application you specified as a display application or a different application. If you specify separate display and run applications, set the Today item properties on the display application. If you do not specify a run application, nothing will happen when the user taps the custom item. |
Order |
The position in the list of Today items where the custom item displays. |
BackColor |
The background color of the custom item. By default, this is set to display the standard background used by the Today screen. |
TextColor |
The color of the text for custom item label. By default, this is set to display the standard text color used by the Today screen. |
The icon used in the Today screen is the same as the icon specified for the run application. You specify this icon in the Additional Properties dialog box launched from the General property page in the Application painter. The icon from the display application is used if you do not set a run application. No icon is used if you do not set a run or display application.
If you specify a display application, you can use it to change the text on the Today screen. For example, suppose you have a PocketBuilder application that initiates MobiLink synchronization. You could write a display application called SyncDisplay that counts the number of updates that have been performed on the local database since the last time it was synchronized. This statement changes the text in the custom item to show the latest count:
SyncDisplay.TodayDisplayText="Sync Update Count is " & + string(counter)
The user could monitor the count and use it to decide when to tap the custom item to launch the synchronization application.
Changing the displayed text is a useful feature. However, when planning to add a custom Today item, you should consider its memory requirements.
If you set both a display application and a run application, the PocketBuilder VM (PKVM) is loaded twice, in two separate processes, even if you use the same application as the display and run application. One is loaded with the Today screen and remains in memory at all times, or until the custom Today item is disabled or removed. The second PKVM is loaded when the custom item is tapped and remains in memory until the launched application terminates.
If you are concerned about memory requirements, specify a run application only. The PKVM is not loaded until the custom item is tapped. It remains in memory only while the application is running. (If you set neither a display nor a run application, the PKVM is never loaded.)
To deploy a Today item with an application, you must select the Deploy Today Item check box in the Project painter.
It is possible to set up different configurations for the Today item that you deploy to a device or emulator. The configuration you choose depends on the amount of memory you want to consume and the functionality that you want to make available to the end user.
Configuration |
Effects on memory consumption |
|---|---|
Valid values provided for Display Application and Run Application properties |
PocketBuilder VM is loaded at all times (remains in memory) |
Valid value provided for Run Application property; no Display Application is set |
PocketBuilder VM is loaded only after a user taps the custom Today item. It resides in memory until the application is shut down. |
No values provided for Display Application and Run Application properties |
PocketBuilder VM is not loaded, even after a user taps the custom Today item. |
When you deploy an application with a Today item to a Pocket PC device, a new key with the name you specified on the Today Item property page is added to the HKEY_LOCAL_MACHINE\Software\Microsoft\Today\Items registry key. The other properties are added to the new key as string or DWORD values. These registry settings are also added to the CAB file if you choose to build one.
If you use a display application to change the appearance or other characteristics of the custom item, use the Application object’s TodaySave function to update the current state of the custom item in the registry as well as on the Today screen. This ensures that the changes display if the device is reset or rebooted.
A user can enable or disable a custom item by selecting Settings>Today from the Start menu, and selecting or clearing the check box on the Items page. If the custom item is disabled, it does not display on the Today screen.
You can remove all custom PocketBuilder Today items by selecting Design>Delete Custom Today Items>Default Device from the Project painter menu. Making this selection does not immediately delete an active Today item, but it does make sure the item information is removed from the registry. The next time the device is reset or rebooted, the previously active custom item is also removed.
The properties associated with the Today item are described in the PowerScript Reference and in the online Help.
