Gears on Mobile Devices

Gears is now available on Windows Mobile 5 and 6 devices.

Mobile devices are, by their nature, often disconnected from the network. Even when connected, the latencies in data connections in mobile networks can make web applications sluggish. Gears gives developers the tools to overcome these obstacles.

Gears works in exactly the same way on a Windows Mobile 5 or 6 device as it does on a desktop PC. If you've already written an application that uses Gears, your application will also work on a Windows Mobile 5 or 6 device. Except, of course, only within the limitations of that device. This means you need to consider things such as small screen and limited ability to input text as well as the limitations of the Document Object Model and CSS APIs present on mobile devices. Limitations of Windows Mobile 5 and 6 devices are discussed later in this document.

Contents

Audience

This document is intended for experienced AJAX programmers who want to develop Gears-enabled web applications for Windows Mobile 5 or 6 devices. It provides instructions on setting up a development environment and discusses known limitatations and workarounds.

Getting Started

That's it!

Windows Mobile 5 and 6 Limitations

Limitations to consider when writing AJAX applications for Windows Mobile 5 and 6 devices, and some workarounds, are provided below:

CSS

Neither Windows Mobile 5 nor 6 support the CSS position: style attribute. This means text is not positioned in any way, it simply appears within the normal flow of an HTML document.

Document Object Model

Document Object Model (DOM) limitations, and example workarounds, are provided below:

Accessing a Document Element

Windows Mobile 5 does not support document.getElementById(), though Windows Mobile 6 does. The following code snippet provides a workaround using the document.all DOM property.

/**
 * Tests if an element is defined.
 * @param type - The type of the element to be tested.
 */
function isDefined(type) {
  return type != 'undefined' && type != 'unknown';
}

/**
 * Retrieve a DOM element by its ID.
 * @param id - The ID of the element to locate.
 */
function getDOMElementById(id) {
  if (isDefined(typeof document.getElementById)) {
     return document.getElementById(id);
  } else if (isDefined(typeof document.all)) {
     return document.all[id];
  } else {
    throw new Error("Can not find a method to locate DOM element.");
    return null;
  }
}

Creating a Document Element

Windows Mobile 5 does not support createElement, though Windows Mobile 6 does. For Windows Mobile 5 devices, create elements using the innerHTML property. This method also works for all modern desktop browsers.

node.innerHTML = "<p id='myElement'></p>";

Setting Element Text

Windows Mobile 5 does not support the createTextNode method. To set the text content of an element use the innerText property instead:

function setElementText(node, text) {
 if (isDefined(typeof node.innerText)) {
   node.innerText = text;
 } else {
   while (node.firstChild) {
     node.removeChild(node.firstChild);
   }
   node.appendChild(document.createTextNode(text));
 }
}

Modifying a Document Element

Use the innerHTML and innerText properties to modify an element on both Windows Mobile 5 and 6.

ActiveX : Problems with setting some objects

On Windows Mobile 5 and 6 some objects that you may expect to be JavaScript objects are instead ActiveX controls. Notably the window object is an ActiveX control, and so does not support expando properties. This means that you cannot add methods or properties to a window as follows:

window.myObject = new Array(); // Does not work!

A workaround is to declare myObject as a top-level object in the global scope. It is then accessible with the notation window.myObject, for example:

myObject = new Array();
alert(window.myObject);       // OK!

Checking whether a method exists before calling it does not work if myObject is an ActiveX object. For example, the following will silently crash:

if (myObject.askQuestion) {
  myObject.askQuestion(42);
}

Instead, a safe way to do the same check is:

if (isDefined(typeof myObject.askQuestion)) {
  myObject.askQuestion(42);
}

where the isDefined function is

function isDefined(type) {
 return type != 'undefined' && type != 'unknown';
}

Recursion

Avoid recursion. Both Windows Mobile 5 and 6 have an extremely limited call stack of about 16 javascript function calls. Violate it and your JavaScript will no longer execute.

Layout Refresh

Windows Mobile does not always correctly update the page layout when a new element is inserted dynamically into the DOM. For example, modifications to an existing table element will not be reflected in the layout. To avoid this, you must replace the entire table element whenever it is modified.

MSDN Resources

MSDN contains a lot of useful information on Windows Mobile development. See, for example:

Setting up a Windows Mobile Emulator

There are four types of Windows Mobile device:

Due to greater support of HTML elements, CSS, the Document Object Model, and the presence of a touchscreen, we recommend you use a Windows Mobile 6 Classic/Professional device or emulator when developing a web app. Instructions are provided below.

The Windows Mobile 6 emulator runs only on a Windows PC. It can be used either through Visual Studio or as a stand-alone application. The latter is recommended unless you are also contributing to the Gears open source project.

Note: The Windows Mobile 6 emulator requires ActiveSync (for XP systems) or Windows Mobile Device Center (for Vista). Instructions for installing both are included below.

1. Install ActiveSync (for XP systems) or Windows Mobile Device Center (for Vista):

2. Install the Windows Mobile 6 Emulator:

3. If you are working on an XP system configure ActiveSync:

4. If you are working on a Vista system configure Windows Mobile Device Center:

5. Run the Windows Mobile 6 Emulator: