HostPreferences - Kirix Documentation

Developer Resources

Class Index By Category

HostPreferences

Overview

The HostPreferences class allows programs to store their own user preferences (for example, saved form information) in the application's preference database. Preference key names normally have a dotted namespace format such as 'program_name.component.preference_name', and programs which use this class should follow this convention.

Methods

HostPreferences.deleteValue
Deletes a preference value from the application preference database
HostPreferences.exists
Checks for the existence of a preference
HostPreferences.getAll
Retrieves all preferences from the preference database
HostPreferences.getValue
Retrieves a preference value from the application preference database
HostPreferences.setValue
Sets a preference value in the application preference database

Example

// instantiate a preferences object
var prefs = new HostPreferences;

// set an preference value
prefs.setValue("myextension.mysection.mypref", "This is a test");

// get a preference value
var value = prefs.getValue("myextension.mysection.mypref");

// display it
alert(value);

// get all preferences
var preferences;
var all_prefs = prefs.getAll();
for (var pref_name in all_prefs)
{
    preferences += pref_name;
    preferences += " equals ";
    preferences += all_prefs[pref_name];
    preferences += "\n";
}

alert(preferences);

HostPreferences.deleteValue

function HostPreferences.deleteValue(pref_name : String) : Boolean

Returns

True if the preference was successfully deleted from the preference database, false otherwise.

Description

Deletes the preference entry specified in the pref_name parameter. If the value doesn't exist in the application's preference database, or the value could not be deleted, false is returned.

HostPreferences.exists

function HostPreferences.exists(pref_name : String) : Boolean

Returns

True if the preference exists, false otherwise.

Description

Checks if the preference specified in the pref_name parameter exists in the application database.

HostPreferences.getAll

function HostPreferences.getAll() : Array(Number/String)

Returns

An array containing all preferences, or null if the call failed

Description

This method returns all preferences in the application preference database. The object returned is a |dictionary array| indexed by preference name and containing the preference values. See the example for more information on using this method.

HostPreferences.getValue

function HostPreferences.getValue(pref_name : String) : Any

Returns

The value of the preference, or null if the preference was not found or could not be retrieved.

Description

Retrieves the value of the preference specified in the pref_name parameter. If the value doesn't exist in the application's preference database, or the value could not be retrieved, null is returned. Otherwise either a string or numeric value is returned containing the preference value.

HostPreferences.setValue

function HostPreferences.setValue(pref_name : String, value : Any) : Boolean

Returns

True if the preference was properly set, false otherwise

Description

Sets the value of a preference in the application preference database. If the preference entry does not already exist, a new entry is created. If the preference entry does already exist, the old value is replaced with the value passed to this method. A string, number, or boolean value may be passed in the value parameter.