setPreferenceForKey()

Syntax:

[void] window.widget.setPreferenceForKey(String preference, String key) 

or

[void] widget.setPreferenceForKey(String preference, String key)

Description:

The setPreferenceForKey method allows a key to be stored along with its associated preference. The arguments are like name and value pairs. The preference value for the key is stored persistently, so if the widget or device is restarted, the value is retained. However, the values stored by a widget are removed when a widget is uninstalled from the device. This includes the case when a widget is reinstalled; where the old widget is uninstalled, the new widget is installed.

An existing preference can be overwritten with a new value by simply calling the method with the same key and new value.

A stored preference for a key can be removed by calling the method with the preference argument set to null

Arguments:

• preference:

  A text string specifying a reusable value to be stored.

• key:

  A short text string defined as the name of the preference to be stored.

Return value:

This method does not return a value.

Example code:

// Save the inputted Search key
var searchArg = document.forms[0].searchKey.value;
widget.setPreferenceForKey('searchKey',searchArg);