<chapter id="xlet-settings-ref">
  <title>Applet, desklet and extension settings reference</title>
  <para>This is the reference for the settings API.</para>

  <sect2>
    <title>Basic settings types</title>
    <sect3>
      <title>switch</title>
      <itemizedlist>
        <listitem><code>type</code>: should be <code>switch</code></listitem>
        <listitem><code>default</code>: <code>true</code> or <code>false</code> (no quotes)</listitem>
        <listitem><code>description</code>: String describing the setting</listitem>
      </itemizedlist>

      <para>A simple switch that controls a <code>boolean</code> type value.</para>
      <para>New in Cinnamon 3.2</para>

    </sect3>
    <sect3>
      <title>spinbutton</title>
      <itemizedlist>
        <listitem><code>type</code>: should be <code>spinbutton</code></listitem>
        <listitem><code>default</code>: default value to use - must be <code>number</code></listitem>
        <listitem><code>min</code>: minimum value</listitem>
        <listitem><code>max</code>: maximum value</listitem>
        <listitem><code>units</code>: (optional) String describing the unit type (pixels, bytes, etc..)</listitem>
        <listitem><code>step</code>: adjustment amount</listitem>
        <listitem><code>description</code>: String describing the setting</listitem>
      </itemizedlist>

      <para>Provides a spin button and entry that control a <code>number</code> value. This can be integer or floating point format. For floating point, all values must have leading 0's.</para>

    </sect3>
    <sect3>
      <title>scale</title>
      <itemizedlist>
        <listitem><code>type</code>: should be <code>scale</code></listitem>
        <listitem><code>default</code>: default value to use - must be <code>number</code></listitem>
        <listitem><code>min</code>: minimum value</listitem>
        <listitem><code>max</code>: maximum value</listitem>
        <listitem><code>step</code>: adjustment amount</listitem>
        <listitem><code>show-value</code>: (optional) whether to show the current value on the slider - default: true</listitem>
        <listitem><code>description</code>: String describing the setting</listitem>
      </itemizedlist>

      <para>Provides a scale widget that allows you to pick a <code>number</code> 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.</para>

    </sect3>
    <sect3>
      <title>entry</title>
      <itemizedlist>
        <listitem><code>type</code>: should be <code>entry</code></listitem>
        <listitem><code>default</code>: default string value</listitem>
        <listitem><code>description</code>: String describing the setting</listitem>
        <listitem><code>expand-width</code>: (optional) true or false, or leave off entirely. Forces editable fields of <code>entry</code>'s elements to occupy the entire space available in a row</listitem>
      </itemizedlist>

      <para>A single-line text entry field that stores a <code>string</code>.</para>

    </sect3>
    <sect3>
      <title>textview</title>
      <itemizedlist>
        <listitem><code>type</code>: should be <code>textview</code></listitem>
        <listitem><code>default</code>: default string value</listitem>
        <listitem><code>description</code>: String describing the setting</listitem>
        <listitem><code>height</code>: (optional) Number indicating the height of the textview in pixels or leave off for default height (200 px)</listitem>
      </itemizedlist>

      <para>A multi-line text entry field that stores a <code>string</code>.</para>
      <para>New in Cinnamon 2.0</para>

    </sect3>
  </sect2>

  <sect2>
    <title>File chooser widgets</title>
    <sect3>
      <title>filechooser</title>
      <itemizedlist>
        <listitem><code>type</code>: should be <code>filechooser</code></listitem>
        <listitem><code>description</code>: String describing the setting</listitem>
        <listitem><code>default</code>: Default filename to use</listitem>
        <listitem><code>select-dir</code>: (optional) true or false, or leave off entirely. Forces directory selection.</listitem>
      </itemizedlist>

      <para>Opens a file chooser dialog that allows you to choose a filename. If <code>select-dir</code> is <code>true</code>, it will only allow directories to be selected. Stores as a <code>string</code>.</para>

    </sect3>
    <sect3>
      <title>iconfilechooser</title>
      <itemizedlist>
        <listitem><code>type</code>: should be <code>iconfilechooser</code></listitem>
        <listitem><code>description</code>: String describing the setting</listitem>
        <listitem><code>default</code>: default icon path or icon name to use</listitem>
        <listitem><code>expand-width</code>: (optional) true or false, or leave off entirely. Forces editable fields of <code>iconfilechooser</code>'s elements to occupy the entire space available in a row</listitem>
      </itemizedlist>

      <para>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 <code>string</code>.</para>

    </sect3>
    <sect3>
      <title>soundfilechooser</title>
      <itemizedlist>
        <listitem><code>type</code>: should be <code>soundfilechooser</code></listitem>
        <listitem><code>description</code>: String describing the setting</listitem>
        <listitem><code>default</code>: default icon path or icon name to use</listitem>
        <listitem><code>event-sounds</code>: (optional) true or false, or leave off entirely. Unless this property is set to false, the file chooser will only allow wav and ogg/oga type files as these are the only types currently supported by cinnamon sound events. (New in Cinnamon 4.2)</listitem>
      </itemizedlist>

      <para>Provides 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 <code>string</code>.</para>
      <para>New in Cinnamon 3.2</para>

    </sect3>
  </sect2>

  <sect2>
    <title>Other chooser widgets</title>
    <sect3>
      <title>combobox</title>
      <itemizedlist>
        <listitem><code>type</code>: should be <code>combobox</code></listitem>
        <listitem><code>default</code>: default value to set</listitem>
        <listitem><code>description</code>: String describing the setting</listitem>
        <listitem><code>options</code>: node of desc:val pair options, where desc is the displayed option name, val is the stored value</listitem>
      </itemizedlist>

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

    </sect3>
    <sect3>
      <title>colorchooser</title>
      <itemizedlist>
        <listitem><code>type</code>: should be <code>colorchooser</code></listitem>
        <listitem><code>default</code>: default color string - can be <code>"red"</code> or <code>"rgba(x,x,x,x)"</code>, etc...</listitem>
        <listitem><code>description</code>: String describing the setting</listitem>
      </itemizedlist>

      <para>A Color button that lets you choose a color. Stores an RGBA color code as a <code>string</code></para>

    </sect3>
    <sect3>
      <title>fontchooser</title>
      <itemizedlist>
        <listitem><code>type</code>: should be <code>fontchooser</code></listitem>
        <listitem><code>default</code>: default font string - should be the font name followed by the font size. (eg. "sans 12")</listitem>
        <listitem><code>description</code>: String describing the setting</listitem>
      </itemizedlist>

      <para>A button that opens a dialog that lets you select a font. Stores a font string as a <code>string</code></para>
      <para>New in Cinnamon 3.2</para>

    </sect3>
    <sect3>
      <title>datechooser</title>
      <itemizedlist>
        <listitem><code>type</code>: should be <code>datechooser</code></listitem>
        <listitem><code>default</code>: default date - should be of the form <code>{d: '1', m: '1', y: '2000'}</code></listitem>
        <listitem><code>description</code>: String describing the setting</listitem>
      </itemizedlist>

      <para>A 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').</para>
      <para>New in Cinnamon 3.2</para>

    </sect3>
    <sect3>
      <title>timechooser</title>
      <itemizedlist>
        <listitem><code>type</code>: should be <code>timechooser</code></listitem>
        <listitem><code>default</code>: default time - should be of the form <code>{h: '12', m: '0', s: '0'}</code></listitem>
        <listitem><code>description</code>: String describing the setting</listitem>
      </itemizedlist>

      <para>A button that opens a dialog that lets you select a time. The time is stored as three key/value pairs representing the numerical value for the hour('h'), minute('m'), and second('s').</para>
      <para>New in Cinnamon 4.2</para>

    </sect3>
    <sect3>
      <title>tween</title>
      <itemizedlist>
        <listitem><code>type</code>: should be <code>tween</code></listitem>
        <listitem><code>default</code>: default tween value</listitem>
        <listitem><code>description</code>: String describing the setting</listitem>
      </itemizedlist>

      <para>Provides a dropdown list from which you can select a tween type. A tween value is a <code>string</code> of the form <code>ease&lt;direction&gt;&lt;shape&gt;</code> where direction can be <code>In</code>, <code>Out</code>, <code>InOut</code>, or <code>OutIn</code> and shape can be <code>Quad</code>, <code>Cubic</code>, <code>Quart</code>, <code>Quint</code>, <code>Sine</code>, <code>Expo</code>, <code>Circ</code>, <code>Elastic</code>, <code>Back</code>, or <code>Bounce</code>. For example, to specify a direction of <code>In</code> and a shape of <code>Quad</code>, the resultant string would be <code>easeInQuad</code>. To specify no tween, use the special tween value <code>easeNone</code>.</para>
      <para>New in Cinnamon 2.6</para>

    </sect3>
    <sect3>
      <title>effect</title>
      <itemizedlist>
        <listitem><code>type</code>: should be <code>effect</code></listitem>
        <listitem><code>default</code>: default effect type</listitem>
        <listitem><code>description</code>: String describing the setting</listitem>
      </itemizedlist>

      <para>Provides a dropdown list from which you can select an effect type. An effect type specifies what an animation looks like. Stores as a <code>string</code>.</para>
      <para>New in Cinnamon 3.2</para>

    </sect3>
  </sect2>

  <sect2>
    <title>Layout types</title>
    <sect3>
      <title>section</title>
      <itemizedlist>
        <listitem><code>type</code>: should be <code>section</code></listitem>
        <listitem><code>description</code>: String to display as the section title</listitem>
      </itemizedlist>

      <para>A <emphasis>non-setting</emphasis> widget, this specifies a new section for assisting in organizing your settings.</para>
      <para>New in Cinnamon 3.2</para>

    </sect3>
    <sect3>
      <title>layout</title>
      <itemizedlist>
        <listitem><code>type</code>: should be <code>layout</code></listitem>
        <listitem><code>pages</code>: An array of strings representing page items</listitem>
      </itemizedlist>

      <para>A <emphasis>non-setting</emphasis> 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.</para>
      <para>To use the layout object, you must define any number of <code>page</code> and <code>section</code> types as key/value pairs in the layout item. Each page will include a <code>sections</code> key which is an array of <code>section</code> items. Each <code>section</code> item in turn will contain a property called keys which is an array of key. In addition, the layout object also must include the <code>pages</code> key which is an array that contains a list of the pages in your layout. The each item in <code>pages</code> and <code>sections</code> must correspond to a page or section key in the layout property and each item in <code>keys</code> 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.</para>
      <para>Here is an example of what a layout object might look like:</para>
      <informalexample>
        <programlisting>
"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",
    "keys" : ["setting1", "setting2"]
  },
  "section2" : {
    "type" : "section",
    "title" : "2nd section",
    "keys" : ["setting3", "setting4"]
  },
  "section3" : {
    "type" : "section",
    "title" : "3rd section",
    "keys" : ["setting5", "setting6"]
  },
  "section4" : {
    "type" : "section",
    "title" : "4th section",
    "keys" : ["setting7", "setting8"]
  }
}</programlisting>
      </informalexample>
      <para>New in Cinnamon 3.2</para>

    </sect3>
  </sect2>

  <sect2>
    <title>Other settings types</title>
    <sect3>
      <title>keybinding</title>
      <itemizedlist>
        <listitem><code>type</code>: should be <code>keybinding</code></listitem>
        <listitem><code>default</code>: default keybinding string - i.e. <code>&lt;Control&gt;F8</code> or other string parseable by gtk_accelerator_parse.</listitem>
        <listitem><code>description</code>: String describing the setting</listitem>
      </itemizedlist>

      <para>An input that allows you to select a keybinding for an action.</para>

    </sect3>
    <sect3>
      <title>generic</title>
      <itemizedlist>
        <listitem><code>type</code>: should be <code>generic</code></listitem>
        <listitem><code>default</code>: default value</listitem>
      </itemizedlist>

      <para>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.</para>

    </sect3>
    <sect3>
      <title>label</title>
      <itemizedlist>
        <listitem><code>type</code>: should be <code>label</code></listitem>
        <listitem><code>description</code>: String to display as a label</listitem>
      </itemizedlist>

      <para>A <emphasis>non-setting</emphasis> 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.</para>
      <para>New in Cinnamon 2.6</para>

    </sect3>
    <sect3>
      <title>button</title>
      <itemizedlist>
        <listitem><code>type</code>: should be <code>button</code></listitem>
        <listitem><code>description</code>: Label for the button</listitem>
        <listitem><code>callback</code>: string of callback method name (no "this", just "myFunc")</listitem>
      </itemizedlist>

      <para>A <emphasis>non-setting</emphasis> widget, this provides a button, which, when clicked, activates the <code>callback</code> method in your applet, desklet, or extension. The callback value should be a string of the method name only. For instance, to call <code>this.myCallback()</code>, you would put <code>myCallback</code> for the callback value.</para>
      <para>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 <code>enabled()</code> function of your extension in order for it to work.</para>

    </sect3>
    <sect3>
      <title>list</title>
      <itemizedlist>
        <listitem><code>type</code>: should be <code>list</code></listitem>
        <listitem><code>description</code>: (optional) String to describe the setting</listitem>
        <listitem><code>columns</code>: Array of objects specifying the columns in the list widget</listitem>
        <listitem><code>default</code>: default value</listitem>
        <listitem><code>show-buttons</code>: (optional) Whether to show the action buttons below the list (<code>true</code> by default)</listitem>
      </itemizedlist>

      <para>
        This widget provides a list with columns, and rows which can be created, edited, deleted and reordered. The columns in the list are specified by the <code>columns</code> property. All columns have the following properties:
        <itemizedlist>
          <listitem><code>id</code>: a unique string for identifying the column</listitem>
          <listitem><code>title</code>: the title that will be displayed in the column header</listitem>
          <listitem><code>type</code>: the data type for the column</listitem>
          <listitem><code>default</code>: (optional) a default value for the column when a new row is being created. This will only be used to auto-populate the corresponding widget when it is first generated in the add row dialog. If this property is omitted, the default will be determined by the widget.</listitem>
          <listitem><code>options</code>: (optional) A list of acceptable values for that column. Either an array or an object with key value pairs may be used. If an object is given, the key is displayed as the text of the widget, and must be a string; the value must match the data type of the column (ie. string, integer, boolean, etc).</listitem>
          <listitem><code>align</code>: (optional) A number between 0 and 1 indicating how the value should be aligned with respect to the column in which it is displayed. 0 aligns to the left of the cell, 1 to the right, and 0.5 in the center. (New in Cinnamon 4.2)</listitem>
        </itemizedlist>
      </para>
      <para>
        The column type determines the type of data that will be stored. When the user presses the add or edit button, a dialog is generated with a widget for each column definition. Starting in Cinnamon 3.8, if the <code>options</code> property is given, the widget will be a combo box. Otherwise the widget will be determined by the data type of the column as listed below. These widgets act just like the corresponding widgets in this document, and all the same properties can be included in the column definition, with the exception of <code>description</code> and <code>type</code>. The following types are currently available:
        <itemizedlist>
          <listitem><code>string</code>: this type stores data as a string. An <code>entry</code> is generated in the add/edit dialog. The default value for new entries is an empty string unless specified with the <code>default</code> property.</listitem>
          <listitem><code>file</code>: this type stores data as a string. A <code>filechooser</code> is generated in the add/edit dialog. The default value for new entries is an empty string unless specified with the <code>default</code> property.</listitem>
          <listitem><code>integer</code>: this type stores data as an integer. A <code>spinbutton</code> is generated in the add/edit dialog. The default value for new entries is 0 unless specified with the <code>default</code> property.</listitem>
          <listitem><code>float</code>: this type stores data as a floating point number. A <code>spinbutton</code> is generated in the add/edit dialog. The default value for new entries is 0.0 unless specified with the <code>default</code> property.</listitem>
          <listitem><code>boolean</code>: this type stores data as a boolean. A <code>switch</code> is generated in the add/edit dialog. The default value for new entries is false unless specified with the <code>default</code> property.</listitem>
        </itemizedlist>
      </para>
      <para>The values are stored as an array of objects where each object in the array corresponds to a row in the list, and each entry in the row object is a key:value pair where the key being the <code>column id</code> of the column to which the value corresponds.</para>
      <para>For an example of how to use this widget, see the settings example applet that is included with Cinnamon. The source code for it can be found in <code>/usr/share/cinnamon/applets/settings-example@cinnamon.org</code></para>
      <para>Note: For appearance, it is recommended that you do not use the description property of this setting, but rather place it in it's own <code>section</code>.</para>
      <para>New in Cinnamon 3.4</para>

    </sect3>
  </sect2>

  <sect2>
    <title>Deprecated settings types</title>

    <para>Please do not use the following settings types in new code. They may be removed in future versions.</para>
    <sect3>
      <title>checkbox</title>
      <itemizedlist>
        <listitem><code>type</code>: should be <code>checkbox</code></listitem>
        <listitem><code>default</code>: <code>true</code> or <code>false</code> (no quotes)</listitem>
        <listitem><code>description</code>: String describing the setting</listitem>
      </itemizedlist>

      <para>Formerly generating a checkbox widget, this widget type now functions exactly like the <code>switch</code> settings type.</para>
      <para>Deprecated since Cinnamon 3.2</para>

    </sect3>
    <sect3>
      <title>radiogroup</title>
      <itemizedlist>
        <listitem><code>type</code>: should be <code>radiogroup</code></listitem>
        <listitem><code>default</code>: default value from the list of options, or it can be a custom value if <code>custom</code> is defined</listitem>
        <listitem><code>description</code>: String describing the setting</listitem>
        <listitem><code>options</code>: node of desc:val pair options, where desc is the displayed option name, val is the stored value</listitem>
      </itemizedlist>

      <para>Formerly generating a series of radio buttons this widget now functions exactly like the <code>combobox</code> settings type.</para>
      <para>Deprecated since Cinnamon 3.2</para>

    </sect3>
    <sect3>
      <title>header</title>
      <itemizedlist>
        <listitem><code>type</code>: should be <code>header</code></listitem>
        <listitem><code>description</code>: String to display as a bold header</listitem>
      </itemizedlist>

      <para>A <emphasis>non-setting</emphasis> widget, it formerly generated a bold-faced label for assisting in organizing your settings. It now functions exactly like the <code>section</code> type.</para>
      <para>Deprecated since Cinnamon 3.2</para>

    </sect3>
    <sect3>
      <title>separator</title>
      <itemizedlist>
        <listitem><code>type</code>: should be <code>separator</code></listitem>
      </itemizedlist>

      <para>A <emphasis>non-setting</emphasis> widget, it formerly drew a horizontal separator for assisting in organizing your settings. It currently is ignored. It is recommended that you use sections instead.</para>
      <para>Deprecated since Cinnamon 3.2</para>

    </sect3>
  </sect2>

  <sect2>
    <title>Additional setting options</title>
    <sect3>
      <title>Additional Setting Options</title>
      These fields can be added to any widget:

      <itemizedlist>
        <listitem>
            <code>dependency: </code>Shows or hides the settings widget based on the value of another key in the settings-schema file. There are several possible values for this option:
            <itemizedlist>
                <listitem>The most common value for this option is simply the <code>key</code> of the setting you wish to depend on. This is most useful for depending on a boolean setting such as a switch. This will make your setting hide if the key you're depending on is false, and show it when the key is true.</listitem>
                <listitem>If you wish to 'invert' the dependence you can precede the key with a <code>!</code>. This will make your setting hide if the key you're depending on is true, and show it when the key is false.</listitem>
                <listitem>For non-boolean values, you can use a simple expression of the form <code>my-key=value</code> where <code>my-key</code> is the key you're depending on, and <code>value</code> is the value that wish to compare to. In addition to '=' you can also use '&lt;', '&lt;=', '&gt;', '&gt;=', and '!='.</listitem>
            </itemizedlist>
            <para>In addition to settings widgets, a dependency can also be added to a section to show or hide the section and all it's widgets. This works with or without the <code>layout</code> item.</para>
            <para>New in Cinnamon 3.8.</para>
        </listitem>
        <listitem><code>tooltip</code>: Adds a popup tooltip to the widget</listitem>
        <listitem><code>indent: true</code>: Indent the widget in the settings page to help with organizing your layout. Note: this key has been deprecated since Cinnamon 3.2 and will be ignored.</listitem>
      </itemizedlist>
    </sect3>
  </sect2>

  <sect2>
    <title>Signals</title>
    <sect3>
      <title><code>settings-changed</code></title>
      Signal when the underlying config file has changed and the in-memory values have been updated.
    </sect3>
    <sect3>
      <title><code>changed::&lt;key&gt;</code></title>

      <para>Signals when <code>key</code> has changed in the configuration file. Use this in conjunction with <code>getValue</code> if you want to handle your own updating in a more traditional way (like gsettings).</para>

      <para>The callback function will be called with three parameters: <code>settingProvider, oldval, newval</code>, which are, respectively, the settings object (which you usually don't need), the original value and the updated value.</para>
    </sect3>
  </sect2>

  <sect2>
    <title>Additional options in metadata.json</title>
    You can add the following items to <code>metadata.json</code> to affect how the settings are presented to the user:

    <itemizedlist>
      <listitem><code>hide-configuration</code>: Hides the configure button in Cinnamon Settings. Set to <code>true</code> if you are using only <code>generic</code>-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.</listitem>
      <listitem><code>external-configuration-app</code>: Allows you to define an external settings app to use instead of the built-in settings GUI. This should be a <code>string</code> with the name of your executable settings app (path relative to the applet's install directory). Note, this key can be overridden by the <code>hide-configuration</code> 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.</listitem>
    </itemizedlist>
  </sect2>

  <sect2>
    <title>Accessing the settings window from command-line</title>

    <para>
      You can access the settings with one of the following commands:
    </para>
    <informalexample>
      <programlisting>
xlet-settings &lt;type&gt; &lt;uuid&gt; &lt;instanceid&gt;</programlisting>
    </informalexample>
    <informalexample>
      <programlisting>
xlet-settings &lt;type&gt; &lt;uuid&gt; -i &lt;instanceid&gt; -t &lt;tabnumber&gt;</programlisting>
    </informalexample>
    <para>
      Where <code>type</code> is <code>applet</code>, <code>desklet</code> or <code>extension</code> depending on what type it is. The <code>instanceid</code> is optional. The <code>tabnumber</code> is optional and designates the tab (or page) you want to access; the tabs are numbered from <code>0</code> to <code>number of tabs - 1</code>. 
    </para>
    <para>
      The second command is new in Cinnamon 4.2.
    </para>
  </sect2>
</chapter>