Developing Screen Orientation-Aware Applications

Microsoft

March 2004

Applies to:
   Windows Mobile™ 2003 Second Edition software

Summary: Learn about how Windows Mobile-based devices display in both portrait and landscape modes, the background of this feature, the information to develop mobile applications for this feature, and the new developer guidelines with suggestions and examples. (8 printed pages)

Download Crossword.msi from the Microsoft Download Center.

Introduction
Changing Screen Orientation
How Your Application Windows Become Aware of Screen Orientation
Redrawing Content
RelayoutDialog
Behavior of Legacy Applications
Installation Warning Messages
Conclusion

Windows Mobile™ 2003 Second Edition software for Pocket PC introduces the ability for a Windows Mobile-based device to display in both portrait and landscape modes. In some devices landscape may be the default viewing mode. Additionally, users will be able to rotate the screen between the two orientations, on the fly, without resetting the device.

This topic provides background information about this new feature, provides you with the information you need to develop mobile applications for portrait and landscape screens, and presents new developer guidelines for you to follow, complete with suggestions and examples.

Normally, the screen orientation only changes when the user uses the Screen Orientation control panel, or presses a hardware button to rotate the screen.

Your application may also change the screen orientation programmatically using the ChangeDisplaySettingsEx function as described on MSDN under "Rotating the Content of the Screen". You may do this, for example, if your application can only operate in portrait mode. However, realize that it may be confusing and frustrating to the user if the screen orientation changes unexpectedly. Your application should always ask the user for confirmation before rotating the screen.

To display in portrait mode, set the dmDisplayOrientation field of the DEVMODE structure to DMDO_0. For right-handed landscape mode, use DMDO_270. For left-handed landscape mode, use DMDO_90.

When the screen orientation changes, or when the Input Panel appears, all full-screen, top-level application windows to fit the new orientation.

Note A window is considered full-screen if it's top, left, and right co-ordinates are at or outside the work area boundaries. The work area is the entire screen area below the title bar. A top-level window is any window that does not have a parent window — that is, has a NULL parent.

When a window's size changes, it receives a WM_SIZE notification. The low-order word of the WM_SIZE message's lParam parameter specifies the new width of the client area, and the high-order word specifies the new height. Your application should be aware when the window size changes and should update its layout accordingly. In addition, it should re-layout any child windows it contains.

If your application has no full-screen window, it does not receive a WM_SIZE notification. Instead, it should listen for a WM_SETTINGCHANGE message with the wParam parameter set to SETTINGCHANGE_RESET.

Note   If your application has a top-level window or creates a window that makes use of the methods SHHandleWMSettingChange, SHInitDialog, and SHFullScreen, it receives both the WM_SIZE and WM_SETTINGCHANGE messages. If your app creates a child window, however, the child window will not receive a WM_SIZE message – even if the child window is full-screen.

The following code sample is a WindowProc template that makes use of both the WM_SIZE and WM_SETTINGCHANGE messages.

    switch (uMessage)
    {
        case WM_SIZE:
            // Recompute the layout of any child windows; resize
            // list views and edit boxes, and reposition buttons, 
            // statics, and other controls.
            break;
        case WM_SETTINGCHANGE:
            if (SETTINGCHANGE_RESET == wParam) {
                // An orientation change occurred. This is where you
                // perform processing that you cannot perform in WM_SIZE, 
                // such as resizing full-screen child windows, calling 
                // MoveWindow on the top-level window, and so on.                // If there 
                // is no need to handle the WM_SETTINGCHANGE message,                 // you can
                // simply ignore it.
            }
            break;
      }

The smallest possible Windows Mobile 2003 Second Edition software for Pocket PC display is 240 pixels tall and 240 pixels wide. Programmers should make sure that their applications are usable on this minimum configuration. A common problem is having a menu that fits the display in portrait mode but that may not fit in landscape. If this is the case, you may need to rearrange items between menus.

You have the following four programming options when redrawing your application content:

• Fit content to the window
• Change content
• Change layout
• Design for the 240x240 visible square common to all layouts

Table 1 shows examples of each approach (with two examples of the fit-content-to-window option) to redrawing content among Windows Mobile software for Pocket PC applications:

Table 1. Redraw options for Portrait and Landscape views

Redraw option	Portrait	Landscape
Fit content to window. Calendar resizes the grid cells to fit the work area.
Fit content to window. The Memory settings control panel resizes its list box to the maximum size, and then repositions all other UI elements around it.
Change the content. Calendar in landscape mode displays only eight months at a time.
Change the layout. Windows Media Player buttons appear to the side of the video clip in landscape mode, not below.
Design for square. The Calendar Options dialog fits its entire content into the 240x240 square visible in both orientations.

It is a good idea to keep your layout as general as possible so that your applications will work with displays of arbitrary size and width-to-height ratios. This means avoiding separate landscape and portrait modes whenever possible. If you must have different landscape and portrait modes, do not assume that your application should display in landscape mode simply because the screen width is greater than the screen height. For example, a device could have a screen width of 321 pixels and a screen height of 320 pixels. On such a device, which might be capable of displaying your application in landscape or in portrait mode, your application should choose its best or preferred layout, which could be portrait mode.

In the CrosswordSample application, there is a helper function called RelayoutDialog that eliminates the tedium of resizing and repositioning child controls on dialogs. For example, suppose your dialog has two dialog templates — one for landscape and one for portrait. If the templates have the same controls, with the same control IDs, you can use the following code as your WM_SIZE handler:

case WM_SIZE:
RelayoutDialog(g_hInst, hDlg, InWideMode() ?
         MAKEINTRESOURCE(IDD_TOOLS_OPTIONS_1_WIDE) :
MAKEINTRESOURCE(IDD_TOOLS_OPTIONS_1));

Note   Controls defined as IDC_STATIC all have the same control ID, so if you have more than one IDC_STATIC, you should rename them to IDC_STATIC_1, IDC_STATIC_2, and so on.

RelayoutDialog also updates the text and bitmaps of your static controls if they change in the new layout.

When users run legacy applications on Windows Mobile 2003 Second Edition-based Pocket PCs, their user experience will remain the same in portrait mode but will be somewhat different in landscape mode. In landscape mode, the lower part of a dialog box might run off the bottom of the screen. To address this, a vertical scrollbar will appear, allowing users to scroll the clipped part of the screen into view. The vertical scroll bar will appear only if there are visible controls that would ordinarily appear at the bottom of a portrait screen. It will not appear for controls that would be off-screen in portrait mode.

Whether an application is "legacy" is determined by the subsystem version information in the executable header. By default, applications compiled with the Windows Mobile 2003 SDKs and earlier set this value to 4.20 or lower; in future releases of the Pocket PC SDK, this value will be set to 4.21 and higher. Applications with a subsystem version of 4.20 or lower are considered legacy applications and will get scrollbars.

Be aware that this behavior opens up the possibility that users will be able to scroll hidden images into view (images and controls that you assumed would be inaccessible). You can still use this technique to store and retrieve images quickly, but you should do it off to the left side of the screen instead.

Ideally, your dialog boxes should never require scroll bars. A good way to accomplish this is to design them so that controls are never covered by the Input Panel when it appears in portrait mode and hence design for the minimum 240 by 240 resolution.

When a legacy application is installed on a Windows Mobile-based Pocket PC capable of screen rotation, the following warning message in Figure 11 will appear:

Figure 11. Installation warning message

This dialog is to advise the user that the application they are about to use may not be aware of square screens or screen rotation, and may not display properly in landscape mode. This dialog will only appear if the VersionMin value (which specifies the lowest OS revision number your app supports) file is less than 4.21.

Since setting VersionMin to 4.21 will prevent your application from installing on older Windows Mobile-based Pocket PCs, it is recommend that you disable this warning message by setting the BuildMax value (which is typically unused) equal to the following values in Table 2:

Table 2. BuildMax values

These parameters can be changed by editing the [CEDevice] section of the INF file which cabwiz uses to generate your CAB file. For more information on the INF file format, please consult MSDN documentation.

Developing applications for Windows Mobile 2003 Second Edition software for Pocket PC requires removing assumptions about screen orientation. By using the simple guidelines in this document you can write applications that install and run on portrait, landscape and square screen devices.