SystemSetting API

The SystemSetting API provides interfaces and methods providing web applications with access to various values of the system.

This API provides an interface and methods through features such as:

SystemSetting 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 SystemSetting 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 SystemInformation API.

For more information on the SystemSetting features, see System Setting Guide.

Since: 2.0

Table of Contents


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

Specifies the type of supported system setting.
  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

The SystemSettingObject interface defines what is instantiated by the Tizen object from the Tizen Platform.
  [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 SystemSetting API.

2.2. SystemSettingManager

The SystemSettingManager interface is the top-level interface for the SystemSetting API that provides access to the module functionalities.
  [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);

  };

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.

    • with error type SecurityError, if this functionality is not allowed.

Code example:

 // Checks whether SystemSetting 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 SystemSetting 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.
         // The 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 would be returned through ErrorCallback.
     }
 } else {
     // tizen.systemsetting will be 'undefined'.
     console.log("SystemSetting 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) {
     // the 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 to get the image on home screen, NotSupportedError would be thrown.
 }

 tizen.systemsetting.getProperty("HOME_SCREEN", getPropertySuccessCallback, errorCallback);

 

2.3. SystemSettingSuccessCallback

The SystemSettingSuccessCallback interface defines the success callback for getProperty().
  [Callback=FunctionOnly, NoInterfaceObject] interface SystemSettingSuccessCallback {
    void onsuccess(DOMString value);
  };

Since: 2.0

Methods

onsuccess
Called when the value of the system setting property is successfully retrieved.
void onsuccess(DOMString value);
             

Since: 2.0

Parameters:

  • value: The value of the requested property.

3. Full WebIDL

module SystemSetting {

  [NoInterfaceObject] interface SystemSettingObject {
    readonly attribute SystemSettingManager systemsetting;
  };
    Tizen implements SystemSettingObject;

  enum SystemSettingType {"HOME_SCREEN", "LOCK_SCREEN", "INCOMING_CALL", "NOTIFICATION_EMAIL"};

  [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);
  };

};