# Applet, desklet and extension settings reference

This is the reference for the settings API.

## Widget types and required fields

### checkbox

- `type`: should be `checkbox`
- `default`: `true` or `false` (no quotes)
- `description`: String describing the setting

A simple checkbox that controls a `boolean` type value

### entry

- `type`: should be `entry`
- `default`: default string value
- `description`: String describing the setting

A text entry field that stores a `string`

### textview

- `type`: should be `textview`
- `default`: default string value
- `description`: String describing the setting
- `height`: (optional) Number indicating the height of the textview in pixels or leave off for default height (200 px)

A text entry field that stores a `string`. Unlike the entry type, this type is multi-line

### colorchooser

- `type`: should be `colorchooser`
- `default`: default color string - can be `"red"` or `"rgba(x,x,x,x)"`, etc...
- `description`: String describing the setting

A Color button that lets you choose a RGBA color code as a `string`

### keybinding

- `type`: should be `keybinding`
- `default`: default keybinding string - i.e. `<Control>F8` or other string parseable by gtk_accelerator_parse.
- `description`: String describing the setting

An input that allows you to select a keybinding for an action.

### radiogroup

- `type`: should be `radiogroup`
- `default`: default value from the list of options, or it can be a custom value if `custom` is defined
- `description`: String describing the setting
- `options`: node of desc:val pair options, where desc is the displayed option name, val is the stored value

A group of radio buttons whose description and values are defined by `options` in `description:value` pairs. Values may be `string` or `number`. also have a value of `custom`, and a text entry will be provided next to that option, to allow entering a custom value.

Options might be:

              "options" : {
                  "Option 1" : "this value",
                  "Option 2" : "that value",
                  "Option 3" : "other value"
              }

### filechooser

- `type`: should be `filechooser`
- `description`: String describing the setting
- `default`: Default filename to use
- `select-dir`: (optional) true or false, or leave off entirely. Forces directory selection.

Opens a file picker dialog to allow you to choose a filename. If `select-dir` is `true`, it will only allow directories to be selected. Stores as a `string`.

### iconfilechooser

- `type`: should be `iconfilechooser`
- `description`: String describing the setting
- `default`: default icon path or icon name to use

Provides a preview button and text entry field. You can open a file dialog to pick an image-type file, or enter a registered icon name in the text field. Stores as a `string`.

### combobox

- `type`: should be `combobox`
- `default`: default value to set
- `description`: String describing the setting
- `options`: node of desc:val pair options, where desc is the displayed option name, val is the stored value

Provides a dropdown list from which you can select from `description:value` pairs defined by `options`. The values can be `string`, `number`, or `boolean`.

### tween

- `type`: should be `tween`
- `default`: default tween value
- `description`: String describing the setting

Provides a dropdown list from which you can select a tween type. A tween value is a `string` of the form `ease<direction><shape>` where direction can be `In`, `Out`, `InOut`, or `OutIn` and shape can be `Quad`, `Cubic`, `Quart`, `Quint`, `Sine`, `Expo`, `Circ`, `Elastic`, `Back`, or `Bounce`. For example, to specify a direction of `In` and a shape of `Quad`, the resultant string would be `easeInQuad`. To specify no tween, use the special tween value `easeNone`.

### spinbutton

- `type`: should be `spinbutton`
- `default`: default value to use - int or leading
- `min`: minimum value
- `max`: maximum value
- `units`: String describing what the number is a unit of (pixels, bytes, etc..)
- `step`: adjustment amount
- `description`: String describing the setting

Provides a spin button and entry for changing setting a `number` value. This can be integer or floating point format. For floating point, all values must have leading 0's.

### scale

- `type`: should be `scale`
- `default`: default value to use - int or leading
- `min`: minimum value
- `max`: maximum value
- `step`: adjustment amount
- `description`: String describing the setting

Provides a scale widget to allow you to pick a `number` value between min and max, by step amount. Integer or floating point numbers can be used. For floating point, all values must have leading 0's.

### generic

- `type`: should be `generic`
- `default`: default value

A generic storage object for any type of value. This is generally intended for internal settings that won't be adjusted by the user. For example, a history, or most recent command. There is no corresponding widget for it in Cinnamon Settings.

### header

- `type`: should be `header`
- `description`: String to display as a bold header

A non-setting widget, this provides a bold-faced label for assisting in organizing your settings

### label

- `type`: should be `label`
- `description`: String to display as a label

A non-setting widget, this provides a label for making a note or describing something. Unlike a header which is bold-faced to stand out, a label is formatted just like the description of most of the other setting types.

### separator

- `type`: should be `separator`

A non-setting widget, this draws a horizontal separator for assisting in organizing your settings

### button

- `type`: should be `button`
- `description`: Label for the button
- `callback`: string of callback method name (no "this", just "myFunc")

A non-setting widget, this provides a button, which, when clicked, activates the `callback` method in your applet. Note: the callback value should be a string of the method name only. For instance, to call `this.myCallback()`, you would put `myCallback` for the callback value.

### Additional Setting Options

These fields can be added to any widget:

- `indent: true`: Indent the widget in the settings page to help with organizing your layout.
- `dependency: <key>`: where `key` is the name of a `checkbox` setting. If that checkbox setting is un-checked, this setting will be made insensitive (greyed out). The checkbox must occur before the setting that depends on it.
- `tooltip`: Adds a popup tooltip to the widget

## Signals

### `settings-changed`

Signal when the underlying config file has changed and the in-memory values have been updated.

### `changed::<key>`

Signals when `key` has changed in the configuration file. Use this in conjunction with `getValue` if you want to handle your own updating in a more traditional way (like gsettings).

The callback function will be called with three paramenters: `settingProvider, oldval, newval`, which are, respectively, the settings object (which you usually don't need), the original value and the updated value.

## Additional options in metadata.json

You can add the following items to `metadata.json` to affect how the settings are presented to the user:

- `hide-configuration`: Hides the configure button in Cinnamon Settings. Set to `true` if you are using only `generic`-type settings that should be hidden from the user. This is not a mandatory key. Omitting it will allow the configuration button to hide or display depending on whether you are utilizing the settings API or not.
- `external-configuration-app`: Allows you to define an external settings app to use instead of the built-in settings GUI. This should be a `string` with the name of your executable settings app (path relative to the applet's install directory). Note, this key can be overridden by the `hide-configuration` key. This is not a mandatory key. Omitting it will allow the configuration button to hide or display depending on whether you are utilizing the settings API or not.