Settings.XletSettingsBase: Cinnamon Javascript Reference Manual

Settings.XletSettingsBase

Settings.XletSettingsBase — Object for handling xlet settings updates

Functions

boolean	bindWithObject ()
boolean	bind ()
boolean	bindProperty ()
boolean	unbindWithObject ()
boolean	unbind ()
boolean	unbindProperty ()
boolean	unbindAll ()
	getValue ()
	setValue ()
	getDefaultValue ()
	getOptions ()
	setOptions ()
	finalize ()

Signals

	changed
	settings-changed

Object Hierarchy

    Object
    ╰── Settings.XletSettingsBase

Description

This object provides methods for binding settings to object properties, connecting to signal change events, and getting and setting values. This class should not be directly, but rather through one of the wrapper classes (AppletSettings, DeskletSettings, or ExtensionSettings)

Functions

bindWithObject ()

boolean
bindWithObject (object     bindObject,
                string     key,
                string     applet_prop,
                function   callback,
                           user_data);

Like bind this allows you to bind a setting to a property on an object. But unlike bind, this function allows you to specify the bindObject to which the property will be bound.

Parameters

bindObject	(optional) the object to which the setting will be bound or null to use the bindObject passed to `_init`
key	the id of the setting
applet_prop	the variable name that is used to hold the setting (eg. `this.value` passes as `"value`")
callback	(optional) the function to call when the setting changes
user_data	(optional) any extra data/object you wish to pass to the callback

Returns

Whether the bind was successful

bind ()

boolean
bind (string     key,
      string     applet_prop,
      function   callback,
                 user_data);

Bind a setting to a property on the bindObject passed to _init.

Parameters

key	the id of the setting
applet_prop	the variable name that is used to hold the setting (eg. `this.value` passes as `"value`")
callback	(optional) the function to call when the setting changes
user_data	(optional) any extra data/object you wish to pass to the callback

Returns

Whether the bind was successful

bindProperty ()

boolean
bindProperty (Settings.BindingDirection   direction,
              string                      key,
              string                      applet_prop,
              function                    callback,
                                          user_data);

Bind a setting to a property on the object bindObject passed to _init. This function is deprecaed and is now only a wrapper around bind for backward compatibility. Please use bind instead.

Parameters

direction	the direction of the binding
key	the id of the setting
applet_prop	the variable name that is used to hold the setting (eg. `this.value` passes as `"value`")
callback	(optional) the function to call when the setting changes
user_data	(optional) any extra data/object you wish to pass to the callback

Returns

Whether the bind was successful

unbindWithObject ()

boolean
unbindWithObject (object   bindObject,
                  string   key);

Removes the binding on an object. If you have bound key to multiple objects, this will only remove the one bound to bindObject. If you wish to remove all bindings, or you used bind or bindProperty to bind the setting, it is recommended that you use unbindPropery instead.

Parameters

bindObject	(optional) the object from which the setting will be unbound
key	the previously bound key to remove

Returns

Whether the unbind was successful.

unbind ()

boolean
unbind (string   key);

Removes the binding on an object that was bound using the bind function. If you have bound key to multiple objects using bindWithObject, you should use unbindWithObject or unbindAll instead.

Parameters

key

the previously bound key to remove

Returns

Whether the unbind was successful.

unbindProperty ()

boolean
unbindProperty (string   key);

Removes the binding of a key that was bound using bind, or bindProperty. This function is deprecaed and is now only a wrapper around unbind for backward compatibility. Please use unbind instead.

Parameters

key

the previously bound key to remove

Returns

Whether the unbind was successful.

unbindAll ()

boolean
unbindAll (string   key);

Removes all bindings of a key that were bound using bind, bindWithObject, or bindProperty.

Parameters

key

the previously bound key to remove

Returns

Whether the unbind was successful.

getValue ()


getValue (string   key);

Gets the value of the setting key.

Parameters

key

the name of the settings key

Returns

The current value of the setting

setValue ()


setValue (string   key,
                   value);

Sets the value of the setting key to value.

Parameters

key	the name of the settings key
value	the new value

getDefaultValue ()


getDefaultValue (string   key);

Gets the default value of the setting key.

Parameters

key

the name of the settings key

Returns

The default value of the setting

getOptions ()


getOptions (String   key);

Gets the current available options for the setting key.

Parameters

key

the name of the settings key

Returns

The currently stored options of the key (or undefined if the key does not support options)

setOptions ()


setOptions (string   key,
                     options);

Sets the available options of key to options. An error is given if the setting does not support options.

Parameters

key	the name of the settings key
options	the new options to set

finalize ()


finalize ();

Removes all bindings and disconnects all signals. This function should be called prior to deleting the object.

Signal details

The `“changed”` signal

user_function (string   key,
                  oldValue,
                  newValue);

Emitted when the value of the setting changes

Parameters

key	The settings key who's value changed
oldValue	The value of the key before the setting changed
newValue	The value of the key after the setting changed

The `“settings-changed”` signal

user_function ();

Emitted when any of the settings changes