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 ()
| _checkSettings ()
| _hasSettingChanged ()
| 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 |

### _checkSettings ()

    _checkSettings ();

Checks whether any settings have been changed and handles callbacks/signals if they have.

### _hasSettingChanged ()

    _hasSettingChanged (value,
                        valueType,
                        oldValue);

Checks whether a setting has changed by comparing is current value to the previous one

#### Parameters

value | current value |
valueType | current value setting type |
oldValue | previous value |

### 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