SystemSetting API
This API provides an interface and methods through features such as:
- HOME_SCREEN
- LOCK_SCREEN
- INCOMING_CALL
- NOTIFICATION_EMAIL
System Setting API may not be provided in some devices. The API capability can be checked by tizen.systeminfo.getCapability("http://tizen.org/feature/systemsetting").
In addition, not all the above properties may be available even though a device supports System Setting API. For instance, a watch device may provide the home screen image but may not support the lock screen wallpaper.
To check if SystemSettingType(e.g. HOME_SCREEN, LOCK_SCREEN and so on) is supported or not, use System Information API.
- HOME_SCREEN - tizen.systeminfo.getCapability("http://tizen.org/feature/systemsetting.home_screen")
- LOCK_SCREEN - tizen.systeminfo.getCapability("http://tizen.org/feature/systemsetting.lock_screen")
- INCOMING_CALL - tizen.systeminfo.getCapability("http://tizen.org/feature/systemsetting.incoming_call")
- NOTIFICATION_EMAIL - tizen.systeminfo.getCapability("http://tizen.org/feature/systemsetting.notification_email")
For more information on the System Setting features, see System Setting Guide.
Since: 2.0
Table of Contents
- 1. Type Definitions
- 1.1. SystemSettingType
- 2. Interfaces
- 2.1. SystemSettingObject
- 2.2. SystemSettingManager
- 2.3. SystemSettingSuccessCallback
- 3. Full WebIDL
Summary of Interfaces and Methods
Interface | Method |
---|---|
SystemSettingObject | |
SystemSettingManager |
void setProperty (SystemSettingType type, DOMString value, SuccessCallback successCallback, optional ErrorCallback? errorCallback)
void getProperty (SystemSettingType type, SystemSettingSuccessCallback successCallback, optional ErrorCallback? errorCallback)
|
SystemSettingSuccessCallback | void onsuccess (DOMString value) |
1. Type Definitions
1.1. SystemSettingType
enum SystemSettingType { "HOME_SCREEN", "LOCK_SCREEN", "INCOMING_CALL", "NOTIFICATION_EMAIL" };
Since: 2.0
The following values are supported in this release:
- HOME_SCREEN - For homescreen background image.
- LOCK_SCREEN - For lockscreen background image.
- INCOMING_CALL - For incoming call ringtone.
- NOTIFICATION_EMAIL - For email notification alert tone.
Defines supporting setting types. The HOME_SCREEN and LOCK_SCREEN are supported for images files. The INCOMING_CALL and NOTIFICATION_EMAIL are supported for sound files.
2. Interfaces
2.1. SystemSettingObject
[NoInterfaceObject] interface SystemSettingObject { readonly attribute SystemSettingManager systemsetting; };
Tizen implements SystemSettingObject;
Since: 2.0
There will be a tizen.systemsetting object that allows accessing the functionality of the System Setting API.
Attributes
-
readonly
SystemSettingManager systemsettingObject representing a system settings manager.
Since: 2.0
2.2. SystemSettingManager
[NoInterfaceObject] interface SystemSettingManager { void setProperty(SystemSettingType type, DOMString value, SuccessCallback successCallback, optional ErrorCallback? errorCallback) raises(WebAPIException); void getProperty(SystemSettingType type, SystemSettingSuccessCallback successCallback, optional ErrorCallback? errorCallback) raises(WebAPIException); };
Since: 2.0
Methods
-
setProperty
-
Sets the property of a device.
void setProperty(SystemSettingType type, DOMString value, SuccessCallback successCallback, optional ErrorCallback? errorCallback);
Since: 2.0
This method allows the user to set the image or sound file specified as an input parameter as the wallpaper or ringtone of a device.
The ErrorCallback method is launched with these error types:
- InvalidValuesError - If any of the input parameters contain an invalid value
- NotSupportedError - If the given type is not supported on the device
- UnknownError - If any other error occurs
Privilege level: public
Privilege: http://tizen.org/privilege/setting
Parameters:
- type: Setting type to set.
- value: Location path of a wallpaper or ringtone file.
- successCallback: Callback function that is called when the setting value is successfully set.
- errorCallback [optional] [nullable]: Callback function that is called when the setting value cannot be set.
Exceptions:
- WebAPIException
with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.
Code example:
/* Checks whether System Setting API is supported. */ var systemsetting_api_supported = tizen.systeminfo.getCapability("http://tizen.org/feature/systemsetting"); /* Checks whether the picture on home screen can be changed or retrieved through System Setting API. */ var home_screen_system_setting = tizen.systeminfo.getCapability("http://tizen.org/feature/systemsetting.home_screen"); /* Defines the success callback. */ function successCallback() { console.log("Succeeded in changing the property"); } /* Defines the error callback. */ function errorCallback(error) { console.log("Failed to change the property. Error: " + error.message); } if (systemsetting_api_supported === true) { /* tizen.systemsetting will be available. */ if (home_screen_system_setting === true) { /* Sets the home screen image. */ /* newHomeScreenImagePath variable should hold the path of the image to be set as home screen */ /* background. */ tizen.systemsetting.setProperty( "HOME_SCREEN", newHomeScreenImagePath, successCallback, errorCallback); } else { /* If tizen.systemsetting.setProperty("HOME_SCREEN", ...) is invoked, NotSupportedError is */ /* returned through ErrorCallback. */ } } else { /* tizen.systemsetting will be "undefined". */ console.log("System Setting API is not supported on the device"); }
-
getProperty
-
Gets the value of the property of a device.
void getProperty(SystemSettingType type, SystemSettingSuccessCallback successCallback, optional ErrorCallback? errorCallback);
Since: 2.0
This method allows the user to get the value of the specified system property as wallpaper or ringtone of a device.
The ErrorCallback method is launched with these error types:
- TypeMismatchError - If any input parameter is not compatible with the expected type for that parameter
- InvalidValuesError - If any of the input parameters contain an invalid value
- NotSupportedError - If the given type is not supported on the device
- UnknownError - If any other error occurs
Parameters:
- type: Type of the property to get.
- successCallback: Callback function that is called when the setting value is successfully retrieved.
- errorCallback [optional] [nullable]: Callback function that is called when the setting value cannot be retrieved.
Exceptions:
- WebAPIException
with error type InvalidValuesError, if any of the input parameters contain an invalid value.
with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.
with error type UnknownError in any other error case.
Code example:
/* Defines the success callback. */ function getPropertySuccessCallback(value) { /* Case: tizen.systeminfo.getCapability("http://tizen.org/feature/systemsetting.home_screen") */ /* returns "true". */ console.log("Succeeded in retrieving the property. The value is " + value); } /* Defines the error callback. */ function errorCallback(error) { console.log("Failed to get the property. Error: " + error.message); /* If the device does not support getting the image on home screen, NotSupportedError is thrown. */ } tizen.systemsetting.getProperty("HOME_SCREEN", getPropertySuccessCallback, errorCallback);
3. Full WebIDL
module SystemSetting { enum SystemSettingType { "HOME_SCREEN", "LOCK_SCREEN", "INCOMING_CALL", "NOTIFICATION_EMAIL" }; Tizen implements SystemSettingObject; [NoInterfaceObject] interface SystemSettingObject { readonly attribute SystemSettingManager systemsetting; }; [NoInterfaceObject] interface SystemSettingManager { void setProperty(SystemSettingType type, DOMString value, SuccessCallback successCallback, optional ErrorCallback? errorCallback) raises(WebAPIException); void getProperty(SystemSettingType type, SystemSettingSuccessCallback successCallback, optional ErrorCallback? errorCallback) raises(WebAPIException); }; [Callback=FunctionOnly, NoInterfaceObject] interface SystemSettingSuccessCallback { void onsuccess(DOMString value); }; };