![]() |
![]() |
![]() |
![]() |
This is the reference for the settings API.
type
: should be switch
default
: true
or false
(no quotes)description
: String describing the settingA simple switch that controls a boolean
type value.
New in Cinnamon 3.2
type
: should be spinbutton
default
: default value to use - must be number
min
: minimum valuemax
: maximum valueunits
: (optional) String describing the unit type (pixels, bytes, etc..)step
: adjustment amountdescription
: String describing the settingProvides a spin button and entry that control 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 - must be number
min
: minimum valuemax
: maximum valuestep
: adjustment amountdescription
: String describing the settingProvides a scale widget that allows 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 entry
default
: default string valuedescription
: String describing the settingexpand-width
: (optional) true or false, or leave off entirely. Forces editable fields of entry
's elements to occupy the entire space available in a rowA single-line text entry field that stores a string
.
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.expand-width
: (optional) true or false, or leave off entirely. Forces editable fields of filechooser
's elements to occupy the entire space available in a rowOpens a file chooser dialog that allows 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 soundfilechooser
description
: String describing the settingdefault
: default icon path or icon name to useProvides a button which shows the currently selected file name and opens a file dialog when clicked. A preview button is also provided to allow the user to test the selected sound. Stores as a string
.
New in Cinnamon 3.2
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 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 color. Stores an RGBA color code as a string
type
: should be fontchooser
default
: default font string - should be the font name followed by the font size. (eg. "sans 12")description
: String describing the settingA button that opens a dialog that lets you select a font. Stores a font string as a string
New in Cinnamon 3.2
type
: should be datechooser
default
: default date - should be of the form {d: '1', m: '1', y: '2000'}
description
: String describing the settingA button that opens a dialog that lets you select a date. The date is stored as three key/value pairs representing the numerical value for the day('d'), month('m'), and year('y').
New in Cinnamon 3.2
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
.
New in Cinnamon 2.6
type
: should be section
description
: String to display as the section titleA non-setting widget, this specifies a new section for assisting in organizing your settings.
New in Cinnamon 3.2
type
: should be layout
pages
: An array of strings representing page itemsA non-setting widget, this allows you to specify a particular layout for your settings rather than relying on the order they appear in your settings-schema.json file. This has the added advantage of using settings pages to further organize your settings into tabs. This is only recommended when you have a large number of settings that wont all fit without scrolling. To use the layout object, you must place it at the beginning of the settings-schema.json file as the first "setting". Any section items not placed within the layout object will be ignored.
To use the layout object, you must define any number of page
and section
types as key/value pairs in the layout item. Each page will include a sections
key which is an array of section
items. Each section
item in turn will contain a property called keys which is an array of key. In addition, the layout object also must include the pages
key which is an array that contains a list of the pages in your layout. The each item in pages
and sections
must correspond to a page or section key in the layout property and each item in keys
must correspond to one of the settings keys in your settings-schema.json file. The pages, sections and keys will be displayed in the order in which their key names appear in their respective arrays and do not depend on their order in the layout object or your settings file.
Here is an example of what a layout object might look like:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 |
"layout" : { "pages" : ["page1", "page2"], "page1" : { "type" : "page", "title" : "1st page", "sections" : ["section1", "section2"] }, "page2" : { "type" : "page", "title" : "2nd page", "sections" : ["section3", "section4"] }, "section1" : { "type" : "section", "title" : "1st section", "sections" : ["setting1", "setting2"] }, "section2" : { "type" : "section", "title" : "2nd section", "sections" : ["setting3", "setting4"] }, "section3" : { "type" : "section", "title" : "3rd section", "sections" : ["setting5", "setting6"] }, "section1" : { "type" : "section", "title" : "4th section", "sections" : ["setting7", "setting8"] } } |
New in Cinnamon 3.2
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 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 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.
New in Cinnamon 2.6
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, desklet, or extension. 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.
Note: for an applet or desklet, the callback function must be a method of the applet or desklet object. For an extension, it can be a method of any object, but that object must be returned from the enabled()
function of your extension in order for it to work.
Please do not use the following settings types in new code. They may be removed in future versions.
type
: should be checkbox
default
: true
or false
(no quotes)description
: String describing the settingFormerly generating a checkbox widget, this widget type now functions exactly like the switch
settings type.
Deprecated since Cinnamon 3.2
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 valueFormerly generating a series of radio buttons this widget now functions exactly like the combobox
settings type.
Deprecated since Cinnamon 3.2
type
: should be header
description
: String to display as a bold headerA non-setting widget, it formerly generated a bold-faced label for assisting in organizing your settings. It now functions exactly like the section
type.
Deprecated since Cinnamon 3.2
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.