Preference API

The Preference API provides functions to store and retrieve small pieces of data which can be used for management of application's preferences.

For more information on the Preferences features, see Preferences Guide.

Since: 2.3.2

Table of Contents

Summary of Interfaces and Methods

Interface Method
PreferenceManagerObject
PreferenceData
PreferenceManager
void getAll (PreferenceGetAllCallback successCallback, optional ErrorCallback? errorCallback)
void setValue (DOMString key, PreferenceValueType value)
PreferenceValueType getValue (DOMString key)
void remove (DOMString key)
void removeAll ()
boolean exists (DOMString key)
void setChangeListener (DOMString key, PreferenceChangeCallback listener)
void unsetChangeListener (DOMString key)
PreferenceChangeCallback
PreferenceGetAllCallback
void onsuccess (PreferenceData[] preferences)

1. Type Definitions

1.1. PreferenceValueType

Specifies the type of a preference value. 
  typedef (DOMString or long or double or boolean) PreferenceValueType;

Since: 2.3.2

2. Interfaces

2.1. PreferenceManagerObject

This interface defines what is instantiated by the Tizen object on the Tizen Platform. 
  [NoInterfaceObject] interface PreferenceManagerObject {
    readonly attribute PreferenceManager preference;
  };
  Tizen implements PreferenceManagerObject;

Since: 2.3.2

The tizen.preference object provides access to the Preference service API's functionality.

Attributes

  • readonly PreferenceManager preference
    Object representing a preference manager.

    Since: 2.3.2

2.2. PreferenceData

The PreferenceData interface stores data of application preferences. 
  [NoInterfaceObject] interface PreferenceData {
    readonly attribute DOMString key;
    readonly attribute PreferenceValueType value;
  };

Since: 2.3.2

Attributes

  • readonly DOMString key
    The key name of the preferences data value.

    Since: 2.3.2

  • readonly PreferenceValueType value
    The value associated with a given key.

    Since: 2.3.2

2.3. PreferenceManager

The Preference API provides functions to store and retrieve small pieces of data which can be for application preferences. 
  [NoInterfaceObject] interface PreferenceManager {
    void getAll(PreferenceGetAllCallback successCallback, optional ErrorCallback? errorCallback) raises(WebAPIException);
    void setValue(DOMString key, PreferenceValueType value) raises(WebAPIException);
    PreferenceValueType getValue(DOMString key) raises(WebAPIException);
    void remove(DOMString key) raises(WebAPIException);
    void removeAll() raises(WebAPIException);
    boolean exists(DOMString key) raises(WebAPIException);
    void setChangeListener(DOMString key, PreferenceChangeCallback listener) raises(WebAPIException);
    void unsetChangeListener(DOMString key) raises(WebAPIException);
  };

Since: 2.3.2

Methods

getAll
Gets all preferences data. 
void getAll(PreferenceGetAllCallback successCallback, optional ErrorCallback? errorCallback);

Since: 2.3.2

Parameters:

  • successCallback: The callback method to be invoked when all preferences are got.
  • errorCallback [optional] [nullable]: The callback method to be invoked when an error occurs.

Exceptions:

  • WebAPIException

    • with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

Code example:

var successCB = function(preferences)
{
  if (preferences.length)
  {
    console.log(
        "The first preference - key: " + preferences[0].key + " value: " + preferences[0].value);
  }
};

tizen.preference.getAll(successCB);

Output example:

The first preference - key: key1 value: Sample value
setValue
Sets the preference value. 
void setValue(DOMString key, PreferenceValueType value);

Since: 2.3.2

Parameters:

  • key: The key name of the preference value to set.
  • value: The new value for the given key.

Exceptions:

  • WebAPIException

    • with error type IOError, if a write error occurs.

    • with error type AbortError, if out of memory.

Code example:

tizen.preference.setValue("key1", "New value");
getValue
Gets a preference value. 
PreferenceValueType getValue(DOMString key);

Since: 2.3.2

Parameters:

  • key: The key name of the preference value to retrieve.

Return value:

    PreferenceValueType: The value associated with the given key.

Exceptions:

  • WebAPIException

    • with error type IOError, if a read error occurs.

    • with error type NotFoundError, if required key not available.

    • with error type AbortError, if out of memory.

Code example:

var currentValue = tizen.preference.getValue("key1");
console.log("The current value of the preference key1 is: " + currentValue);

Output example:

The current value of the preference key1 is: New value
remove
Removes a value with the given key from the preferences. 
void remove(DOMString key);

Since: 2.3.2

Parameters:

  • key: The key name of the preference to remove.

Exceptions:

  • WebAPIException

    • with error type IOError, if a write error occurs.

    • with error type NotFoundError, if required key not available.

    • with error type AbortError, if out of memory.

Code example:

tizen.preference.remove("key1");
removeAll
Removes all key-value pairs from the preferences. 
void removeAll();

Since: 2.3.2

Exceptions:

  • WebAPIException

    • with error type IOError, if a write error occurs.

    • with error type AbortError, if out of memory.

Code example:

tizen.preference.removeAll();
exists
Checks whether the preference with given key exists. 
boolean exists(DOMString key);

Since: 2.3.2

Parameters:

  • key: The key name of the preference to check.

Return value:

    boolean: If true the key exists in the application preference, otherwise false.

Exceptions:

  • WebAPIException

    • with error type IOError, if a read error occurs.

    • with error type AbortError, if out of memory.

Code example:

if (tizen.preference.exists("key1"))
{
  console.log("Preference with the key key1 exists");
}
else
{
  console.log("Preference with the key key1 doesn't exist");
}

Output example:

Preference with the key key1 exists
setChangeListener
Sets the listener to receive notifications about changes of the preference value with the given key. 
void setChangeListener(DOMString key, PreferenceChangeCallback listener);

Since: 2.3.2

Parameters:

  • key: The key name of the preference to listen.
  • listener: The preference value change listener to set.

Exceptions:

  • WebAPIException

    • with error type TypeMismatchError, if the input parameter is not compatible with the expected type.

    • with error type IOError, if a read error occurs.

    • with error type NotFoundError, if required key not available.

    • with error type AbortError, if out of memory.

Code example:

var listener = function(data)
{
  console.log("Preference with the key: " + data.key + " has a new value: " + data.value);
};

tizen.preference.setChangeListener("key1", listener);

Output example:

Preference with the key: key1 has a new value: Sample value
unsetChangeListener
Unsets the listener, so stop receiving notifications about changes of the preference with the given key. 
void unsetChangeListener(DOMString key);

Since: 2.3.2

Parameters:

  • key: The key name of the preference to stop listen.

Exceptions:

  • WebAPIException

    • with error type IOError, if a read error occurs.

    • with error type NotFoundError, if required key not available.

    • with error type AbortError, if out of memory.

Code example:

var listener = function(data)
{
  tizen.preference.unsetChangeListener(data.key);
};

tizen.preference.setChangeListener("key1", listener);

2.4. PreferenceChangeCallback

The callback function to be used as a change listener for a preference with the given key. 
  [Callback=FunctionOnly, NoInterfaceObject] interface PreferenceChangeCallback {
    void onsuccess(PreferenceData data);
  };

Since: 2.3.2

Methods

onsuccess
Called when the preference with the given key changed. 
void onsuccess(PreferenceData data);

Since: 2.3.2

Parameters:

  • data: The PreferenceData object with the new value of a preference.

Code example:

var listener = function(data)
{
  tizen.preference.unsetChangeListener(data.key);
};

tizen.preference.setChangeListener("key1", listener);

2.5. PreferenceGetAllCallback

The callback function used to get data of the all preferences. 
  [Callback=FunctionOnly, NoInterfaceObject] interface PreferenceGetAllCallback {
    void onsuccess(PreferenceData[] preferences);
  };

Since: 2.3.2

Methods

onsuccess
Called with all preferences' data as an argument. 
void onsuccess(PreferenceData[] preferences);

Since: 2.3.2

Parameters:

  • preferences: The array of PreferenceData objects for all preferences.

Code example:

var successCB = function(preferences)
{
  if (preferences.length)
  {
    console.log(
        "First preference - key: " + preferences[0].key + " value: " + preferences[0].value);
  }
};

tizen.preference.getAll(successCB);

Output example:

First preference - key: key1 value: Sample value

3. Full WebIDL

module Preference {
  typedef (DOMString or long or double or boolean) PreferenceValueType;
  Tizen implements PreferenceManagerObject;
  [NoInterfaceObject] interface PreferenceManagerObject {
    readonly attribute PreferenceManager preference;
  };
  [NoInterfaceObject] interface PreferenceData {
    readonly attribute DOMString key;
    readonly attribute PreferenceValueType value;
  };
  [NoInterfaceObject] interface PreferenceManager {
    void getAll(PreferenceGetAllCallback successCallback, optional ErrorCallback? errorCallback) raises(WebAPIException);
    void setValue(DOMString key, PreferenceValueType value) raises(WebAPIException);
    PreferenceValueType getValue(DOMString key) raises(WebAPIException);
    void remove(DOMString key) raises(WebAPIException);
    void removeAll() raises(WebAPIException);
    boolean exists(DOMString key) raises(WebAPIException);
    void setChangeListener(DOMString key, PreferenceChangeCallback listener) raises(WebAPIException);
    void unsetChangeListener(DOMString key) raises(WebAPIException);
  };
  [Callback=FunctionOnly, NoInterfaceObject] interface PreferenceChangeCallback {
    void onsuccess(PreferenceData data);
  };
  [Callback=FunctionOnly, NoInterfaceObject] interface PreferenceGetAllCallback {
    void onsuccess(PreferenceData[] preferences);
  };
};
Except as noted, this content - excluding the Code Examples - is licensed under Creative Commons Attribution 3.0 and all of the Code Examples contained herein are licensed under BSD-3-Clause.
For details, see the Content License.