Applet, Desklet and Extension Settings Reference

Applet, Desklet and Extension Settings Reference

---

Jump to overview

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

---

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

---

###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. One option entry may 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.
• allow-none (optional) - true or false, or leave off entirely. Allows no file to be selected

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. If allow-none is true, A checkbox is added, that allows you to unset the chosen file. 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 or number.

---

###spinbutton

• type : should be "spinbutton"
• default : default value to use - int or leading 0 float
• 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 0 float
• 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

---

###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 by one tab stop, 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). NOTE: The checkbox must occur before the setting that depends on it.
• tooltip - Add a popup tooltip to the widget, to explain its usage, for example.

---

AppletSettings/DeskletSettings/ExtensionSettings Constructors

new AppletSettings.AppletSettings(this, "settings-example@cinnamon.org", instanceId);

new DeskletSettings.DeskletSettings(this, "settings-example@cinnamon.org", instanceId);

new ExtensionSettings.ExtensionSettings(this, "settings-example@cinnamon.org");

---

AppletSettings/DeskletSettings/ExtensionSettings provider public methods

boolean bindProperty(sync_type, key_name, applet_var, applet_callback, user_data)

Binds a setting to the applet_var property

• sync_type: BindingDirection
• key_name: string of JSON key name
• applet_var: string of applet property
• applet_callback: applet callback method (i.e. this.on_settings_changed)
• user_data : extra data to be sent to callback method (optional)
• Returns: Whether the binding was successful

---

getValue(key_name)

Returns the currently stored value of the key key_name. May be boolean, string, or number.

• key_name : The key name to fetch the value for

---

setValue(key_name, value)

Sets the value of key_name to value. May be boolean, string, or number.

• key_name : The key name to set the value for
• value : The new value

---

AppletSettings/DeskletSettings/ExtensionSettings Signals

settings-changed

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

---

Binding Directions

AppletSettings.BindingDirection.SYNC_ONCE DeskletSettings.BindingDirection.SYNC_ONCE ExtensionSettings.BindingDirection.SYNC_ONCE

• Only set the property this one time, no permanent binding is set up. This is useful if you have a setting you wish to read at startup only, but allow it to be changed (by the user or otherwise) during runtime, and those changes not stored.

---

AppletSettings.BindingDirection.ONE_WAY DeskletSettings.BindingDirection.ONE_WAY ExtensionSettings.BindingDirection.ONE_WAY

• Set the property at binding time, and automatically update the property and execute the callback when the setting file changes. This is probably the most common mode.

---

AppletSettings.BindingDirection.BIDIRECTIONAL DeskletSettings.BindingDirection.BIDIRECTIONAL ExtensionSettings.BindingDirection.BIDIRECTIONAL

• Same behavior as BindingDirection.ONE_WAY, but also allows the applet to update the settings file simply by changing the value of the property.

---

Additional Options in metadata.json

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.