What's New for Developers in Windows Mobile 2003 Second Edition Software

What's New for Developers in Window...

Pocket PC (General) Technical Articles

Andy Sjostrom
Microsoft

March 2004

Applies to:
   Windows Mobile™ 2003 Second Edition software for Pocket PCs
   Windows Mobile 2003 Second Edition software for Smartphones
   Microsoft® .NET Compact Framework
   Microsoft ActiveSync®

Summary: Learn about what is new in Windows Mobile 2003 Second Edition software from a developer's point of view. (13 printed pages)

Introduction
Windows Mobile 2003 Second Edition Highlights
Developing Screen Orientation-Aware Applications
Developing DPI-Aware Applications
Installation with DPI-Specific Resources
Enhancements to the ActiveSync Programming Model
Quarter VGA Smartphone Home Screen
Today Screen Selection API
Conclusion

Introduction

Windows Mobile® 2003 Second Edition software will continue the trend of enabling innovation and meeting customer needs. Second Edition delivers a new platform to Original Equipment Manufacturers (OEMs), Mobile Operators and Independent Software Vendor (ISV) partners that enable targeted hardware and software solutions to solve specific end-user scenarios. Second Edition releases key functionality that will result in exciting new hardware designs that address key market segments.

The 'Second Edition' naming reflects that this is a platform release implementing vital new features that enables partners to innovate on the Windows Mobile experience. As a developer, Windows Mobile 2003 Second Edition introduces new device form factors including landscape and square screens as well as devices supporting high dpi screens. This is both a challenge for developers — who may have assumed certain screen orientations and resolutions — as well as an opportunity to satisfy specific usage scenarios and to enhance existing application experience. For example, a piece of mapping software could now support higher resolution and hence more detailed maps on a high resolution device.

The purpose of this document is to provide a developer's overview of what's new in Windows Mobile 2003 Second Edition software. This article forms part of the Developer Resources for Windows Mobile 2003 software package. If you do not have this package you can download it from the Microsoft Download Center.

In addition to the list of articles below, this package contains new and helper headers and libraries as well as sample code. The readme in this package explains how to add support for the APIs and helper functions mentioned in this document to your existing eMbedded Visual C++® development environment.

Developing Screen Orientation-Aware Applications
Developing dpi-Aware Applications
Developing Screen Orientation and dpi-Aware applications in Managed Code
Installation with dpi-Specific Resources
Enhancements to the Microsoft® ActiveSync® Programming Model
QVGA Smartphone Home Screen
Today Screen Selection API

Windows Mobile 2003 Second Edition Highlights

In summary, the major highlights are:

Windows Mobile 2003 Second Edition for Pocket PC supports portrait, landscape and square modes. The user can switch between portrait and landscape on the fly. Not all devices will support switching between modes, i.e. landscape-only, portrait-only or square-only devices are possible.
Windows Mobile 2003 Second Edition supports the following modes, resolutions and dpi implementations:

Pocket PC:

Portrait / Landscape QVGA (240x320, 96 dpi)
Portrait / Landscape VGA (480x640, 192 dpi)
Square screen (240x240, 96 dpi)
Square screen VGA (480x480, 192 dpi)

Smartphone:

Portrait (176x220, 96 dpi)
Portrait QVGA (240x320, 131 dpi)

Devices will be fixed to one dpi implementation i.e. the user will not be able to switch from 96 dpi to 192 dpi or vice versa.
Microsoft .NET Compact Framework Service Pack 2 is built into ROM in all new Windows Mobile 2003 Second Edition devices. No APIs have changed from the first .NET Compact Framework version to Service Pack 2. Existing .NET Compact Framework applications will therefore continue to work as before.
Enhancements to the ActiveSync Programming Model are delivered by adding new interfaces for Sync Service Providers (SSP). The new interfaces increase the SSP's ability to be interactive with the user.
A new Today Screen Selection API supports navigation between built-in and custom today screen plug-ins with the hardware keypad and hence one handed operation of the Pocket PC today screen.
To enable support for Windows Mobile 2003 Second Edition software from eMbedded Visual C++ 4.0, you need to download and install the new service pack, service pack 3.
New emulator images allow you to test your applications for this new platform. These are available for download:
- Pocket PC
- Smartphone
There is no Windows Mobile 2003 Second Edition specific SDK however there is a Developer Resources for Windows Mobile 2003 Second Edition package available for download.

More information about developing for Windows Mobile can be found on the following sites:

Windows Mobile Developer Home

Mobility and Embedded Application Development Center

Developing Screen Orientation-Aware Applications

Introduction

As some devices will have different default modes (portrait or landscape), and the fact that users will be allowed to change orientation on the fly, makes it necessary for applications to be screen orientation-aware.

Handle Orientation

One simple solution to handle the issue of an existing application that only support portrait mode, is to use the ability to change the orientation from within your application (using the ChangeDisplaySettingsEx function as described on MSDN under "Rotating the Content of the Screen"). However, you should make it a habit to ask the user first.

When the orientation changes, your application receives a WM_SIZE message (if it has a full-screen window) and a WM_SETTINGCHANGE message with the wParam parameter set to SETTINGCHANGE_RESET. Typically, when you handle the WM_SIZE message you change the position and/or size of child windows (controls), and in the WM_SETTINGCHANGE message you handle things that you cannot perform in the WM_SIZE message such as resizing full-screen child windows, calling MoveWindow on the top-level window, and so on.

.NET Compact Framework developers need only listen for the Form.Resize event and take action to adjust their layout or content.

Adjust Content

When the screen content needs to be changed for different orientations, there are a number of suggested approaches (in order of recommendation):

Design for square (the top, left, 240 x 240 pixels always visible)
Change layout
Change content

The easiest and often best solution is to simply design for the top, left square (240x240 or 480x480) always visible, as Figure 1 displays:

Figure 1. Design for square (click the thumbnail for a larger image)

This will not require any code to run when the orientation changes. But although very tempting, it does not work for all screen layouts. In many cases you want to make more use of the screen area available, but in different ways depending on current orientation, as shown in Figure 2:

Figure 2. Change layout (click the thumbnail for a larger image)

It would be possible to use the "design for square" approach, but the layout looks much better if the buttons are moved out to the right and the list view is resized. The two described approaches should be enough for most scenarios. However, sometimes there is no other way but to change the actual content of the screen:

Figure 3. Change the content (click the thumbnail for a larger image)

In Figure 3, you see that the Calendar in landscape mode displays only eight months at a time. This is sometimes the only solution, but note that this approach affects the logic of your application. In portrait mode there is no need for navigation to view the full year, but in landscape there is.

Orientation-Unaware Applications

An application marked with a subsystem version number (in the executable header) of 4.20 or below will be considered a legacy application assumed to only support portrait mode. To make these applications usable even in landscape mode, a vertical scrollbar will appear in landscape mode if the application is dialog based. The scrollbar will allow the clipped part of the screen to be scrolled into view. This also happens for .NET Compact Framework applications.

When installing a legacy application and the VersionMin value of the [CEDevice] key in the setup information (.inf) file is set to 4.20 or below, the following warning message in Figure 4 will appear:

Figure 4. Legacy Application Installation Warning

The easiest way to remove this warning is to change the VersionMin value to 4.21 or above, but then the application will not install on older devices such as those running Pocket PC 2002 or Windows Mobile. A way to work around this is to add the BuildMax value to the [CEDevice] section of the setup information (.inf) file.

[CEDevice]

VersionMin=3.00     ; allow install on Pocket PC 2002
BuildMax=0xE0000000 ; support for square screens and screen rotation

The BuildMax value can be used to indicate that the application supports square screens (BuildMax=0xA0000000), screen rotation (BuildMax=0xC0000000), or both (BuildMax=0xE0000000).

Conclusion

There are several options available for making your applications screen orientation-aware, and although legacy applications will run in landscape (with a scrollbar), the user experience can be greatly improved by implementing specific support for different orientations. For more details, please see the article Developing Screen Orientation-Aware Applications and Developing Orientation and dpi Aware Applications for the .NET Compact Framework in the Developer Resources for Windows Mobile 2003 Second Edition.

Developing DPI-Aware Applications

Introduction

"Dots per inch" (dpi) is a measure of the sharpness on a display screen. The more dots that can be fitted into the same area, the sharper the image gets. Print media has taken advantage of high-dpi technology for a long time. A document printed on a 1200-dpi printer prints text of the same size as a 300-dpi printer, but the text is much sharper.

Windows Mobile 2003 Second Edition software supports a 192 dpi implementation as well as the previous 96 dpi. Devices will be fixed to one implementation, i.e. the user will not be able to switch from 96 dpi to 192 dpi or vice versa. This means that if you target only a fixed number of devices with a known dpi implementation, as often is the case in enterprise application development, then you can optimize the code base just for that implementation. However, if you need to support both implementations from the same code base then read on to find out how to best go about doing that.

The increased dpi measure leads to dramatic improvements in sharpness. Upgrading your application to support dpi-awareness will not only ensure correct appearance on high-dpi devices but will also prepare your application for these high-dpi advantages:

Sharper text: the most noticeable improvement that comes with almost no cost. Every application that is dpi-aware and uses TrueType fonts inherits this improvement.

More detailed graphics: if steps are taken to provide high-resolution bitmaps, applications can use the increased resolution to display more detailed icons and graphics.

Key Issues

In dpi-aware applications for Pocket PCs and Smartphones, it's important to focus on the following three general areas as shown in Table 1:

Table 1. General areas to pay attention to in dpi-aware applications

Application Development Area	Comments
Layout	UI elements whose positions and sizes are specified in pixel coordinates that assume 96-dpi will be incorrect on high-dpi devices. In general, all UI elements should be laid out using scaled positions and sizes, or relative to controls, fonts, or system metrics. The GetDeviceCaps Windows Mobile function can be used to obtain a display's dpi by passing in either LOGPIXELSX or LOGPIXELSY as the second parameter. You can continue to work in pixels but remove assumptions about the dpi by using the following techniques: Using the SCALEX and SCALEY macros to scale 96-dpi coordinates, or using the metrics returned by GetSystemMetrics when applicable. Expressing sizes or positions relative to other controls. Expressing sizes or positions relative to a font. Dialog boxes already use font sizes to determine their layout, so typically they need no special modification to work on high-dpi devices.
Text and Fonts	While TrueType fonts scale nicely, they don't scale linearly: increasing the dpi by 10 percent generally does not increase a string's length by exactly 10 percent. The cumulative effect, especially in longer strings, may cause text in different resolutions to be relatively shorter or to be clipped or to wrap unexpectedly. It is therefore important to use the Windows Mobile GetTextExtent function instead of making assumptions about how much space a string will take up. For static layouts like dialogs, you should allocate some extra width for text elements to fit properly in any dpi. In addition, different fonts exhibit different nonlinear scaling effects, which means that the use of multiple fonts on a screen may cause some to appear disproportionate to others in different resolutions. To be dpi-aware, an application can make no assumptions about the pixel sizes of various screen elements, such as icon sizes or border widths. Windows Mobile-based Smartphones and Pocket PCs provide a number of system metrics to provide information about the user's system. For example, the following information can be queried via the GetSystemMetrics Windows Mobile function. Screen size dimensions should be obtained by using GetSystemMetrics(SM_CXSCREEN) or GetSystemMetrics(SM_CXSCREEN). Border dimensions should be obtained by using GetSystemMetrics(SM_CXBORDER) or GetSystemMetrics(SM_CYBORDER). Large and small icon sizes should be obtained by using GetSystemMetrics(SM_CXICON) or GetSystemMetrics(SM_CXSMICON). At higher dpi values, line thickness has to be increased to maintain proportionate visual size. To be dpi-aware, your application should scale the width of any pens with which it draws. The behavior of the Windows Mobile Graphics Device Interface (GDI) with respect to drawing thick (greater than 1 pixel) lines makes precise and correct positioning tricky. For calls to the Windows Mobile functions LineTo and Polyline, the GDI takes the specified origin point as the center of the pen's width. For lines of odd thickness, the width of the line is equally distributed to each side of the origin point; but for lines of even thickness, the GDI biases the top and left sides. If your application has been positioning lines without making assumptions about the thickness of pens, it will probably handle thicker pens due to high-dpi without any changes. But if it has been assuming a constant pen width, such as one pixel, you should be aware of the effect that GDI behavior can have on layouts.
Images	In this document image refers to all raster-based image files (BMP/JPEG/GIF), icons, and cursors. Since their dimensions are fixed in pixel units, they present unique problems for a dpi-aware application. While image scaling can stretch images to the correct logical sizes, to truly take advantage of the high-dpi screen and create a positive customer experience, high-visibility graphics should be manually re-created. Stretching Images If the display dpi is not the same as the dpi for which the image was designed, the image needs to be stretched to display at the correct physical size. However, you will need to determine whether the image should be stretched every time it is painted or whether a new bitmap should be created that is stretched only once. If the bitmap painting code is accessible to you, changing the code to stretch on paint is less memory intensive than stretching the bitmap on load. If, however, you are using a function or object that does not allow you to scale the bitmap (for example, an image list function), you may need to stretch on load. An alternative to scaling is using multiple images, each authored for a different dpi. This technique yields the best results. The .ico format is already capable of storing multiple image sizes in a single file. When you load the icon or cursor, the application asks for the size that the GetSystemMetrics function suggests; the system then picks the closest image. Windows Mobile automatically scales bitmaps in static controls on high-dpi displays, unless the bitmap is equal to or larger than the control that contains it, in which case Windows Mobile assumes that the bitmap was authored for high-dpi. This means that for static controls to work correctly you probably will not need to make any special changes. The article "Installation with DPI-Specific Resources" in the Developer Resources for Windows Mobile 2003 Second Edition deals with how to have both graphics available in your installation package.

Application Development Area

Comments

Layout

UI elements whose positions and sizes are specified in pixel coordinates that assume 96-dpi will be incorrect on high-dpi devices. In general, all UI elements should be laid out using scaled positions and sizes, or relative to controls, fonts, or system metrics.

The GetDeviceCaps Windows Mobile function can be used to obtain a display's dpi by passing in either LOGPIXELSX or LOGPIXELSY as the second parameter.

You can continue to work in pixels but remove assumptions about the dpi by using the following techniques:

Using the SCALEX and SCALEY macros to scale 96-dpi coordinates, or using the metrics returned by GetSystemMetrics when applicable.

Expressing sizes or positions relative to other controls.

Expressing sizes or positions relative to a font.

Dialog boxes already use font sizes to determine their layout, so typically they need no special modification to work on high-dpi devices.

Text and Fonts

While TrueType fonts scale nicely, they don't scale linearly: increasing the dpi by 10 percent generally does not increase a string's length by exactly 10 percent. The cumulative effect, especially in longer strings, may cause text in different resolutions to be relatively shorter or to be clipped or to wrap unexpectedly. It is therefore important to use the Windows Mobile GetTextExtent function instead of making assumptions about how much space a string will take up. For static layouts like dialogs, you should allocate some extra width for text elements to fit properly in any dpi. In addition, different fonts exhibit different nonlinear scaling effects, which means that the use of multiple fonts on a screen may cause some to appear disproportionate to others in different resolutions.

To be dpi-aware, an application can make no assumptions about the pixel sizes of various screen elements, such as icon sizes or border widths. Windows Mobile-based Smartphones and Pocket PCs provide a number of system metrics to provide information about the user's system. For example, the following information can be queried via the GetSystemMetrics Windows Mobile function.

Screen size dimensions should be obtained by using GetSystemMetrics(SM_CXSCREEN) or GetSystemMetrics(SM_CXSCREEN).
Border dimensions should be obtained by using GetSystemMetrics(SM_CXBORDER) or GetSystemMetrics(SM_CYBORDER).
Large and small icon sizes should be obtained by using GetSystemMetrics(SM_CXICON) or GetSystemMetrics(SM_CXSMICON).

At higher dpi values, line thickness has to be increased to maintain proportionate visual size. To be dpi-aware, your application should scale the width of any pens with which it draws.

The behavior of the Windows Mobile Graphics Device Interface (GDI) with respect to drawing thick (greater than 1 pixel) lines makes precise and correct positioning tricky. For calls to the Windows Mobile functions LineTo and Polyline, the GDI takes the specified origin point as the center of the pen's width. For lines of odd thickness, the width of the line is equally distributed to each side of the origin point; but for lines of even thickness, the GDI biases the top and left sides.

If your application has been positioning lines without making assumptions about the thickness of pens, it will probably handle thicker pens due to high-dpi without any changes. But if it has been assuming a constant pen width, such as one pixel, you should be aware of the effect that GDI behavior can have on layouts.

Images

In this document image refers to all raster-based image files (BMP/JPEG/GIF), icons, and cursors. Since their dimensions are fixed in pixel units, they present unique problems for a dpi-aware application. While image scaling can stretch images to the correct logical sizes, to truly take advantage of the high-dpi screen and create a positive customer experience, high-visibility graphics should be manually
re-created.

Stretching Images

If the display dpi is not the same as the dpi for which the image was designed, the image needs to be stretched to display at the correct physical size. However, you will need to determine whether the image should be stretched every time it is painted or whether a new bitmap should be created that is stretched only once.

If the bitmap painting code is accessible to you, changing the code to stretch on paint is less memory intensive than stretching the bitmap on load. If, however, you are using a function or object that does not allow you to scale the bitmap (for example, an image list function), you may need to stretch on load.

An alternative to scaling is using multiple images, each authored for a different dpi. This technique yields the best results.

The .ico format is already capable of storing multiple image sizes in a single file. When you load the icon or cursor, the application asks for the size that the GetSystemMetrics function suggests; the system then picks the closest image.

Windows Mobile automatically scales bitmaps in static controls on high-dpi displays, unless the bitmap is equal to or larger than the control that contains it, in which case Windows Mobile assumes that the bitmap was authored for high-dpi. This means that for static controls to work correctly you probably will not need to make any special changes.

The article "Installation with DPI-Specific Resources" in the Developer Resources for Windows Mobile 2003 Second Edition deals with how to have both graphics available in your installation package.

Legacy Support

High-resolution Windows Mobile 2003 Second Edition-based Pocket PCs also provide an emulation layer for backwards compatibility with old applications. With this emulation layer, the display appears to legacy applications as a traditional 240 x 320 display; however, the operating system scales all the graphics to fit the actual display size. Fonts are linearly scaled in height.

Applications that use GAPI frequently make assumptions about the screen size based on earlier versions of Pocket PC and Smartphone hardware. To preserve backward compatibility with legacy applications, an emulation layer has been added to GAPI. By default, this layer will scale GAPI drawing to fit the screen; however, a high-resolution-aware application can choose to bypass the emulation layer to have complete access to the display hardware. Legacy applications that use GAPI also get the same backward compatibility support that non-GAPI applications receive.

Conclusion

The emulation layer will always make sure that old and current applications run fine on high dpi Windows Mobile-based Pocket PCs. Measures have to be taken to optimize the use of the higher dpi as well as to best support devices with the ability to use more than one dpi measure. For more information, read the article Developing DPI-Aware Applications and Developing Orientation and dpi Aware Applications for the .NET Compact Framework in the Developer Resources for Windows Mobile 2003 Second Edition.

Installation with DPI-Specific Resources

Background

When developing and distributing dpi-aware applications, you probably want to include high-resolution bitmaps and other resources. One solution would be to add these resources alongside the old, but this would create two challenges:

Both set of resources are included on all devices requiring more device memory than necessary. The 96 dpi resources are not needed on a 192 dpi device and vice versa.
The code need to be updated to load different resource depending on the device resolution.

The challenge becomes even greater when considering that future devices could require yet another resolution (>192 dpi).

Solution

One solution to this challenge is to separate the resources into two separate resource-specific DLLs, and during installation only the appropriate DLL on the device. A SetupDLL.dll library is provided in the Developer Resources for Windows Mobile 2003 Second Edition to assist you in doing this.

SetupDPI.dll

The SetupDPI.dll will run after your installation and rename and delete resource files depending on the current resolution of the device. It will look at a Registry key that contains a list of files (inserted during the installation, see below) and rename or delete the files accordingly. If the current resolution is 192DPI, the file RES_192.DLL will be rename to RES.DLL and the file RES_096.DLL will be deleted. An example of how to do this using the SetupDPI.dll library is the ResDLL sample that ships with the Installation with DPI-Specific Resources technical article.

Code Changes

First, you need to make sure that the resource IDs are identical in the two DLLs as well as in the application itself. The preferred method (as shown in the sample) is to use the same resource constant file. Then, you should open the resource DLL on application initialization and then use the returned handle whenever you need a resource:

#include "res_096\resource.h"
// ...
g_hInstRes = LoadLibrary(_T("RES.DLL"));
// ...
hBMP = LoadBitmap(g_hInstRes, MAKEINTRESOURCE(IDB_MYBITMAP));

Setup Changes

In the setup information (.inf) file you need to add the resource file list as a number of Registry entries:

[AddRegSection]
HKLM,Software\Microsoft\SetupDPI,%InstallDir%\Res_096.DLL,65537,0
HKLM,Software\Microsoft\SetupDPI,%InstallDir%\Res_192.DLL,65537,0

Conclusion

Using the SetupDPI.dll will ease the addition of dpi-specific resources to your application and also minimize the impact on your code and setup files. For more details, please see the article Installation with DPI-Specific Resources and the ResDLL sample in the Developer Resources for Windows Mobile 2003 Second Edition.

Enhancements to the ActiveSync Programming Model

Introduction

Enhancements to the ActiveSync Programming Model are delivered by adding three new interfaces for Sync Service Providers (SSP). The new interfaces increase the SSP's ability to be interactive with the user. The new interfaces are:

OnSSPEnable - The function will be called when the SSP is enabled in the ActiveSync Options dialog.
OnSSPDisable - The function will be called when the SSP is disabled in the ActiveSync Options dialog.
IReplStore2 - new interface derived from IReplStore that gives a SSP the ability to display its settings dialog before it has been enabled.

The new interfaces OnSSPEnable and OnSSPDisable allow a SSP to react to the user clicking the enable checkbox in the Options dialog. This can be helpful if multiple SSPs need to interact with each other or if a SSP needs to inform another process when it is enabled or disabled. The IReplStore2 interface allows a SSP to display the settings dialog in all cases. If a SSP does not implement this interface then ActiveSync will not display settings if the SSP was not enabled before displaying the options dialog. These interfaces can be used with ActiveSync versions 3.7.1 and later.

Interface Descriptions

OnSSPEnable

New function a SSP can export. The function will be called when the SSP is enabled in the ActiveSync Options dialog.

The OnSSPEnable function uses the following signature:

HRESULT WINAPI OnSSPEnable (HWND hwndParent);

hwndParent: HWND the SSP should use to parent any dialog box it displays when this function is called.

Remarks: The IReplStore::Initialize function may not have been called prior to this function being called so you must not use any internal variables that depend on IReplStore::Initialize being called.

OnSSPDisable

New function a SSP can export. The function will be called when the SSP is disabled in the ActiveSync Options dialog.

The function uses this signature:

HRESULT  WINAPI OnSSPDisable (HWND hwndParent);

hwndParent: HWND the SSP should use to parent any dialog box it displays when this function is called.

IReplStore2

This is a new interface derived from IReplStore that gives a SSP the ability to display its settings dialog before it has been enabled.

Conclusion

The new interfaces open up new ways for SSPs to design and develop synchronization related features that are more intuitive and easier to use. For more details, please see the article Enhancements to the ActiveSync Programming Model in the Developer Resources for Windows Mobile 2003 Second Edition.

Quarter VGA Smartphone Home Screen

Introduction

Smartphones running Windows Mobile 2003 Second Edition software support 240 x 320 (Quarter VGA, or QVGA) resolution display, as well as the "classic" 176 x 220 resolution display. Table 2 illustrates the Windows Mobile software versions and supported resolutions.

Table 2. Windows Mobile software versions and supported resolutions

Version	176 x 220	240 x 320
Windows Mobile 2002	X
Windows Mobile 2003 for Smartphone	X
Windows Mobile 2003 Second Edition for SmartphoneX	X	X

Authors of customized Home Screens should be aware of a few changes to the Smartphone Home Screen API that reflect this new feature.

Quarter VGA Backgrounds

On classic Smartphone, the display is 200 pixels tall, with a 20 pixel area for the soft key buttons. On QVGA Smartphone, the soft key area is expanded to 27 pixels, which leaves 293 vertical pixels for the Home Screen. Therefore, you need to resize your background images to 240 x 293 pixels in order to target QVGA Smartphone.

In addition to re-authoring your background image, you need to add the following attributes to the Default tag in the Home Screen XML file:

<default target-width="240" target-height="320">

Legacy Support

If Quarter VGA Smartphone cannot find these property values in the Home Screen XML file, it will assume that the home screen was authored for classic Smartphone, and will emulate a classic Smartphone display by scaling all layout coordinates and graphics upwards by 36%.

Conclusion

Home Screen authors need to be aware of how the higher resolution affects the Home Screen appearance. For more information on how to efficiently manage the changes, please read the article QVGA Smartphone Home Screen in the Developer Resources for Windows Mobile 2003 Second Edition.

Today Screen Selection API

Introduction

Windows Mobile 2003 Second Edition software for Pocket PC allows a user to navigate between and within Pocket PC Today screen plug-ins. This means that a user can now use the Today screen without having to use the stylus improving one handed operation.

The ability to navigate between today screen plug-ins with the hardware keypad can be supported by your plug-in in the following ways (by setting the Registry key "HKEY_LOCAL_MACHINE\Software\Microsoft\Today\Items\<yourpluginname>" and value "Selectability"):

Selectability=0 (or if it does not exist) means that the plug-in cannot be selected and never receives any notifications.
If Selectability=1 it means that the Today screen manages the selection and no notifications are sent to the plug-in.
Selectability=2 means that notifications are sent to the plug-in according to what is described below.

Notification Messages

The following notification messages are sent to the today plug-in:

Incoming:

WM_TODAYCUSTOM_RECEIVEDSELECTION is received when the plug-in receives the selection. The virtual key pressed (i.e. VK_DOWN or VK_UP) is in the wParam parameter. If the plug-in accepts the selection change, it should return TRUE.
WM_PAINT and WM_ERASEBKGND messages will be received regardless of the value of Selectability to enable redraw.
WM_TODAYCUSTOM_USERNAVIGATION is received when a hardware navigation key is pressed. The virtual key pressed (i.e. VK_UP, VK_DOWN, VK_LEFT, VK_RIGHT) is in the wParam parameter. If the navigation is handled, the return value should be TRUE.
WM_TODAYCUSTOM_ACTION is received when the hardware "Action" key is pressed.
WM_TODAYCUSTOM_LOSTSELECTION is sent to the plug-in when it has lost the selection.

Outgoing:

TODAYM_DRAWWATERMARK can be sent (usually in response to the WM_PAINT message) to the Today screen to draw the background.
TODAYM_TOOKSELECTION can be sent to the Today screen to indicate that the plug-in want to take the selection (e.g. as a response to a user tap). The Today screen will respond with a TODAYM_RECEIVEDSELECTION message where wParam set to 0 to indicate that the selection change was successful.

Conclusion

Necessary changes to include basic support for selection of Today screen plug-ins are minimal. Full support is also possible without major updates to the code, but allow for advanced features like selection of the controls inside the plug-in. For more details, please see the article Today Screen Selection API in the Developer Resources for Windows Mobile 2003 Second Edition.

Conclusion

New features and platform improvements in Windows Mobile 2003 Second Edition including new screen orientation modes and resolutions, enhancements to the ActiveSync Programming Model, and latest .NET Compact Framework in ROM, provides a basis for a richer user experience. The platform improvements enable OEMs to build new hardware designs, Mobile Operators to deliver innovative services and ISVs to develop new and improved applications.

Download the Developer Resources for Windows Mobile 2003 Second Edition to get access to the complete versions of these articles and the samples and helper functions that accompany them.

Get started and explore the new features in Windows Mobile 2003 Second Edition to enhance your user's experience and the richness of your application. Read more at the Mobility and Embedded Application Development Center.

Contents

Introduction

Windows Mobile 2003 Second Edition Highlights

Developing Screen Orientation-Aware Applications

Introduction

Handle Orientation

Adjust Content

Orientation-Unaware Applications

Conclusion

Developing DPI-Aware Applications

Introduction

Key Issues

Legacy Support

Conclusion

Installation with DPI-Specific Resources

Background

Solution

SetupDPI.dll

Code Changes

Setup Changes

Conclusion

Enhancements to the ActiveSync Programming Model

Introduction

Interface Descriptions

OnSSPEnable

OnSSPDisable

IReplStore2

Conclusion

Quarter VGA Smartphone Home Screen

Introduction

Quarter VGA Backgrounds

Legacy Support

Conclusion

Today Screen Selection API

Introduction

Notification Messages

Conclusion

Conclusion