Home / Reference / Cinnamon Tutorials / Extension System

Applet, desklet and extension settings reference

This is the reference for the settings API.

Widget types and required fields

checkbox

A simple checkbox that controls a boolean type value

entry

A text entry field that stores a string

colorchooser

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

keybinding

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

radiogroup

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

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

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

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

spinbutton

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

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

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.

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

separator

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

button

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:

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: