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

---

keybinding

• type : should be "keybinding"
• default : default keybinding string - i.e. "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.

---

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

---

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.

---

These fields can be added to any widget:

• indent: true - Indent the widget by , 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 : string - Adds a popup tooltip to the widget

---

AppletSettings/DeskletSettings/ExtensionSettings Constructors

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

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

new Settings.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

---

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).

Callback function:

on_setting_changed: function(setting_provider, oldval, newval)

• setting_provider: The settings object (discard)
• oldval: The original value
• newval: The updated value

---

Binding Directions

Settings.BindingDirection.IN

• 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.

---

Settings.BindingDirection.OUT

• Set the property at binding time, and automatically update the setting file when the property changes. The callback can be omitted when using this mode, as it will not be used.

---

Settings.BindingDirection.BIDIRECTIONAL

• Combines the effects of .IN and .OUT

---

Using keybindings in your applet

Setting up a keybinding:

Main.keybindingManager.addHotKey(id, this.keybinding, Lang.bind(this, this.on_hotkey_triggered));

• id can be any string. If your applet or desklet supports multiple instances, add the instance ID to this string to keep it unique from other instances.
• this.keybinding is what contains the parseable keybinding string (probably gotAPI)
• this.on_hotkey_triggered is the callback method you want triggered when your hotkey is pressed

---

Removing a keybinding (usually called in a cleanup method like on_applet_removed_from_panel):

Main.keybindingManager.removeHotKey(id)

• id is the string you used when you originally defined the keybinding

---

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.

max-instances

• Allow multiple instances in the panel. Remember to pass the instanceId in function calls.

Command line access to configuration page in Cinnamon Settings

--

cinnamon-settings applets *uuid*

cinnamon-settings desklets *uuid*

cinnamon-settings extensions *uuid*