Applications can respond to high-level orientation, and shake events or elect to receive raw accelerometer data through acceleration events. You will use framework controller functions or event listeners to receive accelerometer events.

You can use the orientation events to rotate your application to track the orientation of the device between portrait and landscape modes. Shake events can be applied in creative ways as alternatives for user input, such as start/stop indicators. The raw acceleration data is useful for games or other applications that can integrate device movement directly into the application’s interaction with the user.

if (this.controller.stageController.setWindowOrientation) {
 this.controller.stageController.setWindowOrientation("free");
}

this.controller.listen(document, "orientationchange",
    this.handleOrientation.bindAsEventListener(this));
.
.
.
MyAssistant.prototype.handleOrientation(event)
     Mojo.Log.info("Orientation change position: ", event.position, " pitch: ",
       event.pitch, " roll: ", event.roll);
};

this.controller.listen(document, "shaking",
  this.handleShaking.bindAsEventListener(this));
.
.
.
MyAssistant.prototype.shaking(event)    {
     Mojo.Log.info("Shaking with magnitude: ", event.magnitude);
);

this.controller.listen(document, "acceleration",
    this.handleAcceleration.bindAsEventListener(this));
.
.
.
MyAssistant.prototype.acceleration(event)    {
     Mojo.Log.info("X: ", event.accelX, "; Y:", event.accelY,
       "; Z:", event.accelZ, "; time: ", event.time);

You should use the JavaScript window methods setInterval() or setTimeout() to return to your application after a delay:

var wakeupFunction = function() {
        Mojo.Log.info("It's a wakeup call!");
};
window.setTimeout(wakeupFunction, 20000);

This is a lightweight delay timer, which executes a function after a specified period. In this example code, wakeupFunction is executed after a delay of 20 seconds. This type of alarm will work as long as the device is awake and where some imprecision is acceptable.

In all other situations, you will want to use the Alarm service, which is based on the device’s real-time clock (RTC). Alarms are intended to wake applications while minimized or maximized, or to drive polling for dashboard applications. Alarms will:

A good example of an alarm at work is using the Alarm service to wake an application up periodically:

this.controller.serviceRequest("palm://com.palm.power/timeout", {
    method: "set",
    parameters: {
        key: "com.palm.app.news.update",
        in: News.feedUpdateInterval,
        wakeup: "true",
        uri: "palm://com.palm.applicationManager/open",
        params: {
            id: "com.palm.app.news",
            params: {action: "updateFeed"}
        }
    },
    onSuccess: this.onSuccessHandler,
    onFailure: this.onFailureHandler
});

This example from News sets a relative alarm according to the requested News.feedUpdateInterval and requests that it wake up the device if it is asleep. When the alarm fires, it will use the Application Manager to launch News (even if News isn’t running at the time) with a launch parameter indicating that this is an alarm for feed updates. You will learn more about handling launch events and using alarms with background applications in Chapter 10.

Another option is to set an alarm at a specific date and time:

this.controller.serviceRequest("palm://com.palm.power/timeout", {
    method: "set",
    parameters: {
        key: "com.palm.app.news.daily",
        at: "04-23-2009 03:30:00",
        wakeup: "true",
        uri: "palm://com.palm.applicationManager/open",
        params: {
            id: "com.palm.app.news",
            params: {action: "updateFeed"}
        }
    },
    onSuccess: this.onSuccessHandler,
    onFailure: this.onFailureHandler
});

In this example, News could be set to update the news feeds at 3:30 A.M. GMT. This calendar alarm uses the at property (in place of the in property for a relative alarm) to set the date and time for the alarm. By definition, you must set calendar alarms for each occurrence; there isn’t a provision at this time for periodic or recurring alarms.

To clear the alarm, use the clear method:

this.controller.serviceRequest("palm://com.palm.power/timeout", {
    method: "clear",
    parameters: {
        key: "com.palm.app.news.daily",
    },
    onSuccess: this.onSuccessHandler,
    onFailure: this.onFailureHandler
});

The alarm’s key property is used to clear the periodic alarm that was set with that property.

Some additional notes about alarms:

Because the Alarm service can wake up your application even while the device is asleep, the service is integral to running an application in the background. We’ll use alarms to turn News into a background application in Chapter 10.

Use the Connection Manager’s getStatus method to get updates on the device connection status. Some applications need to manage data access based on the connection state or type of connection available:

this.controller.serviceRequest("palm://com.palm.connectionmanager", {
    method: "getStatus",
    parameters: {subscribe:true},
    onSuccess: this.onSuccessHandler,
    onFailure: this.onFailureHandler
});

The response will provide the connection status at the time of the call. Use the subscription option to register for updates each time the connection status changes. In every case, the onSuccess callback is made with a single response argument, an object describing the connection status. The return value is set to true and the connection properties are provided as described in Table 9-3.

Palm webOS provides basic location services to get one or more location fixes. You can specify fixes by mode. In automatic mode, the system picks the most appropriate mode based upon your accuracy and response time requirements. Specific fix types include assisted GPS and Cell ID with or without WiFi ID.

this.controller.serviceRequest("palm://com.palm.location", {
    method: "getCurrentPosition",
    parameters: {},
    onSuccess: this.locationSuccess.bind(this),
    onFailure: this.locationFailure.bind(this)
});

this.trackingHandle = this.controller.serviceRequest("palm://com.palm.location", {
    method: "startTracking",
    parameters:{subscribe: true},
    onSuccess: this.trackingSuccess.bind(this),
    onFailure: this.trackingFailure.bind(this)
});

this.trackingHandle.cancel();

this.controller.serviceRequest("palm://com.palm.location", {
    method: "getReverseLocation",
    parameters: {
        latitude: "37.7779",
        longitude: "-122.414"
    },
    onSuccess: this.reverseSuccess.bind(this),
    onFailure: this.reverseFailure.bind(this)
});

street address;
locality (eg. in the US, city, state, zipcode);
country

98th 8th St ;San Francisco, CA 94103 ;USA

The device will automatically go to sleep after a period of inactivity, where inactivity is primarily defined as the absence of user interaction: gestures, touches, or keyboard input. The user can set a preference to trigger sleep after a minimum of 30 seconds or a maximum of 3 minutes. Some system services, such as audio or video playback will defer sleep, but if you need to keep the device awake, you can use the activityStart() and activityEnd() methods in the Power Management service.

You would use these service methods if your application performs an extended operation, such as syncing or downloading a lot of data, or if your application includes a passive viewing feature like a slide show. You will also use this in background applications where you need more than the few seconds allotted during an alarm wakeup.

Alert the Power Management service that you are starting an activity that will require the device to stay awake:

this.controller.serviceRequest("palm://com.palm.power/com/palm/power", {
    method: "activityStart",
    parameters: {
        id: "com.palm.app.news.update-1",
        duration_ms: '120000'
    },
    onSuccess: this.activitySuccess.bind(this),
    onFailure: this.activityFailure.bind(this)
});

Provide a unique ID, which should be your application ID with an activity name and an occurrence count. This recommended format will allow you to distinguish between requests and manage multiple requests if needed, but the only requirement is that the ID string be unique. The activity’s expected duration is provided in milliseconds and cannot exceed 900,000 milliseconds (15 minutes).

The power management service will automatically terminate your activity request at the end of its duration or 15 minutes, whichever is shorter. You should notify the service when your activity completes, as every bit of power efficiency is important:

this.controller.serviceRequest("palm://com.palm.power/com/palm/power", {
    method: "activityEnd",
    parameters: {
        id: "com.palm.app.news.update-1"
    },
    onSuccess: this.activitySuccess.bind(this),
    onFailure: this.activityFailure.bind(this)
});

The only parameter is the id provided to the activityStart() method. Activities are not canceled when an application is closed, so you should use activityEnd() in your cleanup() method when there are any outstanding activity requests.

Applications can request a named system property, which is currently limited to retrieving the unique device ID. Generally, the requested system property is named as a string to parameter.key; in this case, the device ID is named com.palm.properties.nduid:

this.controller.serviceRequest("palm://com.palm.preferences/systemProperties", {
    method: "getSysProperty" ,
    parameters:{"key": "com.palm.properties.nduid" },
    onSuccess: this.onSuccessHandler
    }
});

The nduid is a hardware-encoded device ID that is guaranteed to be unique. An example device ID is a66690b3632bb592b29c6a15416717b9ee072b3f.

On a successful callback, you will find the device ID as the value assigned to the key, com.palm.properties.nduid. In this example:

this.onSuccessHandler = function() {
    Mojo.Log.info("Success; nduid = ", response["com.palm.properties.nduid"]);
};

The device ID is the recommended way to uniquely identify the user or their device. The device ID is better than the phone number or device serial number because it is guaranteed to be unique to a specific device, yet it is difficult for others to use it to identify a specific user. The phone number is considered private user information and should never be used or transmitted with any user data. The serial number is printed on the device, making it easier to associate a device to a specific user.

The system is designed to expose a set of services enabling applications to access some general system settings. Currently, the only exposed service is one that provides the system time.

Make the request to the getSystemTime method, and optionally subscribe to notifications of changes to the time or timezone:

this.controller.serviceRequest("palm://com.palm.systemservice/time", {
    method: "getSystemTime",
    parameters: {subscribe: true},
    onSuccess: this.timeSuccess.bind(this),
    onFailure: this.timeFailure.bind(this)
});

Whether the subscribe property is set or not, the onSuccess function will be called initially with the response object as an argument. The properties are described in Table 9-6.

The System Sounds service is used to create audio feedback for direct user actions. This might include button or keypad clicks, transition sounds, action audio, or any audible response to a user action. It’s not intended for sustained audio, such as background audio or any lengthy playback. The call is limited to a static list of sounds and is not customizable.

The specified sounds will be played as soon as the call is received, with low latency. Call System Sounds using the playFeedback method, with the requested sound name as a string assigned to the name property:

this.controller.serviceRequest("palm://com.palm.audio/systemsounds", {
    method: "playFeedback",
    parameters:{name: "shutter",
        onSuccess: this.onSuccessHandler,
        onFailure: this.onFailureHandler
    }
});

The callbacks will receive the response object with returnValue set to true if the sound played successfully; otherwise, it will be set to false. If false is returned, the errorText property will include an indication of the type of error encountered.

The available sounds are enumerated in Appendix B, and you can find them on the Palm developer site.