System Services
The system exposes a general set of services enabling applications to access various system settings. It is part of the System Manager and is available only when the UI is running. The following types of methods are available:
- Preferences
- Time
- Wallpaper
Preferences Methods
This section describes the following methods:
- getPreferences
- getPreferenceValues
- setPreferences
getPreferences
The getPreferences method retrieves the values for preferences keys specified in the passed array. If subscribe is set to true, then getPreferences sends an update any time the values of the keys change.
Required parameter:
- keys
Parameters
Parameter | Type | Description |
---|---|---|
keys | array | An array of keys for which to retrieve values. |
subscribe | boolean | If true, getPreferences sends an update whenever the value of one of the keys changes. |
Return Handling
onSuccess
Attribute | Type | Description |
---|---|---|
{no name} | JSON object | Key-value pairs containing the values for the requested preferences. If the requested preferences key or keys do not exist, the object is empty. |
onFailure
No onFailure callback is required.
Example
this.controller.serviceRequest('palm://com.palm.systemservice', { method:"getPreferences", parameters:{"keys":["locale"]}, onSuccess: myCallback, onFailure: myFailureCallback });
The above call returns the following, for example:
{ "locale": { "languageCode": "en", "countryCode": "us" } }
getPreferenceValues
Retrieve the list of valid values for the specified key. If the key is of a type that takes one of a discrete set of valid values, getPreferenceValues returns that set. For example, calling getPreferences on timeFormat returns "HH12" and "HH24". Otherwise, getPreferenceValues returns nothing for the key.
Required parameter:
- key
Parameters
Parameter | Type | Description |
---|---|---|
key | text | The key for which to retrieve valid values. |
Return Handling
onSuccess
Attribute | Type | Description |
---|---|---|
{no name} | JSON object | The key and the valid values. |
onFailure
No return value.
Example
this.controller.serviceRequest('palm://com.palm.systemservice', { method:"getPreferenceValues", parameters:{"key":"timeFormat" }, onSuccess: myCallback, onFailure: myFailureCallback });
The above call returns the following JSON object:
{ "timeFormat": [ "HH12", "HH24" ] }
setPreferences
Sets preference keys to specified values.
Required parameter:
- params
Parameters
Parameter | Type | Description |
---|---|---|
params | JSON object | An object containing one or more key-value pairs. |
Return Handling
onSuccess
Attribute | Type | Description |
---|---|---|
returnValue | boolean | (true) Indicates whether the call was successful. |
onFailure
Attribute | Type | Description |
---|---|---|
returnValue | boolean | (false) Indicates whether the call was successful. |
errorText | string | Text describing the reason the call failed. |
Example
this.controller.serviceRequest('palm://com.palm.systemservice', { method:"setPreferences", parameters:{"food":"pizza"}, onSuccess: myCallback, onFailure: myFailureCallback });
Time Method
This section describes the following method:
- getSystemTime
getSystemTime
Requests the system time, and if the subscribe property is true, receives notifications when the time zone changes and/or the system time changes by a significant amount (currently 5 min.).
For info about world time zones, see Wikipedia®.
Required parameter:
- subscribe
Parameters
Parameter | Type | Description |
---|---|---|
subscribe | boolean | If true, receives notifications when the time zone changes and/or the system time changes by a system-defined threshold (currently 5 min.). |
Return Handling
onSuccess
Attribute | Type | Description |
---|---|---|
localtime | object |
The time and date for the current time zone. The format is: "year":, "month":, "day":, "hour":, "minute":, "second": Where:
|
offset | integer | The number of minutes from UTC. This can be negative for time zones west of UTC and positive for time zones east of UTC. |
timezone | string | The current system time zone. It has the same format as the " TZ " environment variable. For information, see http://www.gnu.org/software/libc/manual/html_node/TZ-Variable.html . |
TZ | string | The time zone abbreviation in standard Unix format that corresponds to the current time zone (e.g., PDT (Pacific Daylight Time)). |
utc | integer | The number of seconds since Unix Epoch (midnight of January 1, 1970 UTC). |
onFailure
The function always succeeds, providing that com.palm.systemservice is running.
Example
this.controller.serviceRequest('palm://com.palm.systemservice/time', { method:"getSystemTime", parameters:{}, onSuccess: myCallback, onFailure: myFailureCallback });
Wallpaper Methods
This section describes the following methods:
- wallpaper/importWallpaper
- wallpaper/refresh
- wallpaper/info
- wallpaper/deleteWallpaper
The Wallpaper API lets your application change (or detect) the wallpaper (the image that appears on the screen behind the Launcher or Card view).
To set wallpaper on the device:
- Use importWallpaper to convert an image to a wallpaper object.
- Pass the wallpaper object as the new value for the wallpaper key in setPreferences.
wallpaper/importWallpaper
Converts an image to a wallpaper for the device. The image is either re-centered and cropped, or scaled:
- If no focus or scale parameters are passed, importWallpaper scales the entire image to 320 x 480 pixels.
- If focus parameters are passed but scale is not specified, the image is re-centered at the point specified by the focus parameters and cropped. Black is added anywhere the image does not reach the edge of the screen.
- If scale is passed but focus is not specified, then the image is scaled and then cropped.
- If focus and scale parameters are passed, the image is first scaled and then re-centered and cropped.
The focusX and focusY parameters are the coordinates of the new center of the image. The scale parameter determines the new size of the image.
Once the image has been converted, the wallpaper is stored in the internal list of wallpapers on the device, and is available until deleted using deleteWallpaper. Note: the internal list of wallpapers is not the same as the Wallpapers folder that is visible to the user.
Required parameter:
- target
Parameters
Parameter | Type | Description |
---|---|---|
target | string | The URL of the image file to be converted to a wallpaper (must be PNG or JPG). Only the file:// scheme is supported (no remote schemes are supported) |
focusX | float | The horizontal coordinate of the new center of the image, from 0.0 (left edge) to 1.0 (right edge). A value of 0.5 preserves the current horizontal center of the image. |
focusY | float | The vertical coordinate of the new center of the image, from 0.0 (top edge) to 1.0 (bottom edge). A value of 0.5 preserves the current vertical center of the image. |
scale | float | The new scale of the image, from 0.1 to 10.0 times the current size. |
Return Handling
onSuccess
Attribute | Type | Description |
---|---|---|
returnValue | boolean | (true) Indicates whether the call was successful. |
wallpaper | JSON object | A wallpaper object that can be passed to setPreferences to set the wallpaper key. |
onFailure
Attribute | Type | Description |
---|---|---|
returnValue | boolean | (false) Indicates whether the call was successful. |
Example
this.controller.serviceRequest('palm://com.palm.systemservice/wallpaper', { method:"importWallpaper", parameters:{ "target":"file:///media/internal/photos/mypic.jpg" }, onSuccess: myCallback, onFailure: myFailureCallback });
wallpaper/refresh
Refreshes the internal list of available wallpapers. Under normal circumstances, there is no need to call wallpaper/refresh directly.
Parameters
None.
Return Handling
onSuccess
Attribute | Type | Description |
---|---|---|
returnValue | boolean | (true) Indicates whether the call was successful. |
onFailure
Attribute | Type | Description |
---|---|---|
returnValue | boolean | (false) Indicates whether the call was successful. |
wallpaper/info
Retrieves a wallpaper object using either the wallpaperName or wallpaperFile attribute.
Required parameters:
- Either wallpaperName or wallpaperFile
Parameters
Parameter | Type | Description |
---|---|---|
wallpaperName | string | The wallpaper attribute that specifies the name of the wallpaper. |
wallpaperFile | string | The wallpaper attribute that specifies the file containing the wallpaper image. |
Return Handling
onSuccess
Attribute | Type | Description |
---|---|---|
returnValue | boolean | (true) Indicates whether the call was successful. |
wallpaper | JSON object | A wallpaper object that can be passed to setPreferences to set the wallpaper key. |
onFailure
Attribute | Type | Description |
---|---|---|
returnValue | boolean | (false) Indicates whether the call was successful. |
Example
this.controller.serviceRequest('palm://com.palm.systemservice/wallpaper', { method:"info", parameters:{"wallpaperName":"flowers"}, onSuccess: myCallback, onFailure: myFailureCallback });
wallpaper/deleteWallpaper
Deletes the specified wallpaper from the list of available wallpapers on the device.
Warning: Do not call deleteWallpaper on the currently active wallpaper!
Required parameter:
- wallpaperName
Parameters
Parameter | Type | Description |
---|---|---|
wallpaperName | string | The wallpaperName attribute of the wallpaper object to delete. |
Return Handling
onSuccess
Attribute | Type | Description |
---|---|---|
returnValue | boolean | (true) Indicates whether the call was successful. |
onFailure
Attribute | Type | Description |
---|---|---|
returnValue | boolean | (false) Indicates whether the call was successful. |
Example
this.controller.serviceRequest('palm://com.palm.systemservice/wallpaper', { method:"deleteWallpaper", parameters:{"wallpaperName":"flowers"}, onSuccess: myCallback, onFailure: myFailureCallback });
Sample Code
See Services Sample.