This is the reference for the settings API.
type: should be checkbox
default: true or false (no quotes)description: String describing the settingA simple checkbox that controls a boolean type value
type: should be entry
default: default string valuedescription: String describing the settingA text entry field that stores a string
type: should be textview
default: default string valuedescription: String describing the settingheight: (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
type: should be colorchooser
default: default color string - can be "red" or "rgba(x,x,x,x)", etc...description: String describing the settingA Color button that lets you choose a RGBA color code as a string
type: should be keybinding
default: default keybinding string - i.e. <Control>F8 or other string parseable by gtk_accelerator_parse.description: String describing the settingAn input that allows you to select a keybinding for an action.
type: should be radiogroup
default: default value from the list of options, or it can be a custom value if custom is defineddescription: String describing the settingoptions: node of desc:val pair options, where desc is the displayed option name, val is the stored valueA 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:
1 2 3 4 5 |
"options" : { "Option 1" : "this value", "Option 2" : "that value", "Option 3" : "other value" } |
type: should be filechooser
description: String describing the settingdefault: Default filename to useselect-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.
type: should be iconfilechooser
description: String describing the settingdefault: default icon path or icon name to useProvides 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.
type: should be combobox
default: default value to setdescription: String describing the settingoptions: node of desc:val pair options, where desc is the displayed option name, val is the stored valueProvides a dropdown list from which you can select from description:value pairs defined by options. The values can be string, number, or boolean.
type: should be tween
default: default tween valuedescription: String describing the settingProvides 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.
type: should be spinbutton
default: default value to use - int or leadingmin: minimum valuemax: maximum valueunits: String describing what the number is a unit of (pixels, bytes, etc..)step: adjustment amountdescription: String describing the settingProvides 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.
type: should be scale
default: default value to use - int or leadingmin: minimum valuemax: maximum valuestep: adjustment amountdescription: String describing the settingProvides 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.
type: should be generic
default: default valueA 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.
type: should be header
description: String to display as a bold headerA non-setting widget, this provides a bold-faced label for assisting in organizing your settings
type: should be label
description: String to display as a labelA 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.
type: should be separator
A non-setting widget, this draws a horizontal separator for assisting in organizing your settings
type: should be button
description: Label for the buttoncallback: 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.
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 widgetSignals 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.
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.