Allow column options in the xlet settings list widget (linuxmint#7040)

* settings widgets combobox: use the valtype if given, and take a variable type not a string

* xlet settings list widget: add the ability to supply options to a given key, and if so, use a combo box in the add/edit dialog rather than the usual widget for that type

* settings example applet: update to demonstrate the new options functionality introduced to the settings list widget

* settings reference tutorial: update to reflect changes to the list widget

docs/reference/cinnamon-tutorials/xlet-settings-ref.xml

@@ -308,15 +308,17 @@
       </itemizedlist>
 
       <para>
-        This widget provides a list which can be edited and reordered from the settings window. The columns in the list are specified by the <code>columns</code> propery. Each column object in the array must have the following properties:
+        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> propery. 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>
         </itemizedlist>
       </para>
       <para>
-        Each column type determines the data type that is stored. In addition, it specifies the widget that is generated when the user clicks the add or edit buttons. These widgets act just like the corresponding widgets in this document, and all the same properties are available, with the exception of <code>description</code> and <code>type</code>. The following types are currently available:
+        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>
@@ -325,7 +327,8 @@
           <listitem><code>boolean</code>: this type stores data as a bool. 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 row objects. Each row object has a set of key:value pairs where the key is the <code>column id</code> of the column to which the value corresponds.</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/[email protected]</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>
 

files/usr/share/cinnamon/applets/settings-example@cinnamon.org/settings-schema.json

@@ -192,7 +192,12 @@
             {"id": "number", "title": "Id number", "type": "integer", "min": 0, "max": 100},
             {"id": "icon", "title": "Icon", "type": "icon"},
             {"id": "key", "title": "Shortcut key", "type": "keybinding"},
-            {"id": "file", "title": "File Path", "type": "file", "select-dir": false}
+            {"id": "file", "title": "File Path", "type": "file", "select-dir": false},
+            {"id": "color", "title": "Color", "type": "integer", "default": 5, "options": {
+                    "red": 5,
+                    "blue": 4,
+                    "green": 3
+                }}
         ],
         "default" : []
     }

files/usr/share/cinnamon/cinnamon-settings/bin/SettingsWidgets.py

@@ -749,7 +749,7 @@ def set_rounding(self, digits):
 class ComboBox(SettingsWidget):
     bind_dir = None
 
-    def __init__(self, label, options=[], valtype="string", size_group=None, dep_key=None, tooltip=""):
+    def __init__(self, label, options=[], valtype=None, size_group=None, dep_key=None, tooltip=""):
         super(ComboBox, self).__init__(dep_key=dep_key)
 
         self.valtype = valtype
@@ -792,8 +792,11 @@ def connect_widget_handlers(self, *args):
         self.content_widget.connect('changed', self.on_my_value_changed)
 
     def set_options(self, options):
-        # assume all keys are the same type (mixing types is going to cause an error somewhere)
-        var_type = type(options[0][0])
+        if self.valtype is not None:
+            var_type = self.valtype
+        else:
+            # assume all keys are the same type (mixing types is going to cause an error somewhere)
+            var_type = type(options[0][0])
         self.model = Gtk.ListStore(var_type, str)
 
         for option in options:

files/usr/share/cinnamon/cinnamon-settings/bin/TreeListWidgets.py

@@ -38,7 +38,18 @@
 }
 
 def list_edit_factory(options):
-    class Widget(CLASS_TYPE_MAP[options["type"]]):
+    kwargs = {}
+    if 'options' in options:
+        kwargs['valtype'] = VARIABLE_TYPE_MAP[options['type']]
+        widget_type = ComboBox
+        options_list = options['options']
+        if isinstance(options_list, dict):
+            kwargs['options'] = [(b, a) for a, b in options_list.items()]
+        else:
+            kwargs['options'] = zip(options_list, options_list)
+    else:
+        widget_type = CLASS_TYPE_MAP[options["type"]]
+    class Widget(widget_type):
         def __init__(self, **kwargs):
             super(Widget, self).__init__(**kwargs)
 
@@ -78,7 +89,6 @@ def get_widget_value(self):
                     return self.bind_object.get_property(self.bind_prop)
                 return self.content_widget.get_property(self.bind_prop)
 
-    kwargs = {}
     for prop in options:
         if prop in PROPERTIES_MAP:
             kwargs[PROPERTIES_MAP[prop]] = options[prop]

files/usr/share/cinnamon/cinnamon-settings/modules/cs_calendar.py

@@ -33,4 +33,4 @@ def on_module_selected(self):
             settings.add_row(GSettingsSwitch(_("Display the date"), "org.cinnamon.desktop.interface", "clock-show-date"))
             settings.add_row(GSettingsSwitch(_("Display seconds"), "org.cinnamon.desktop.interface", "clock-show-seconds"))
             days = [[7, _("Use locale default")], [0, _("Sunday")], [1, _("Monday")]]
-            settings.add_row(GSettingsComboBox(_("First day of week"), "org.cinnamon.desktop.interface", "first-day-of-week", days, valtype="int"))
+            settings.add_row(GSettingsComboBox(_("First day of week"), "org.cinnamon.desktop.interface", "first-day-of-week", days, valtype=int))

files/usr/share/cinnamon/cinnamon-settings/modules/cs_desklets.py

@@ -53,7 +53,7 @@ def load(self, window):
 
         dec = [[0, _("No decoration")], [1, _("Border only")], [2, _("Border and header")]]
         widget = Gtk.Box(orientation=Gtk.Orientation.VERTICAL)
-        combo_box = GSettingsComboBox(_("Decoration of desklets"), "org.cinnamon", "desklet-decorations", dec, valtype="int")
+        combo_box = GSettingsComboBox(_("Decoration of desklets"), "org.cinnamon", "desklet-decorations", dec, valtype=int)
         widget.pack_start(combo_box, False, False, 0)
         line1 = Gtk.Label()
         line1.set_markup("<i><small>%s</small></i>" % _("Note: Some desklets require the border/header to be always present"))

files/usr/share/cinnamon/cinnamon-settings/modules/cs_general.py

@@ -23,7 +23,7 @@ def on_module_selected(self):
             settings = page.add_section(_("Desktop Scaling"))
 
             ui_scales = [[0, _("Auto")], [1, _("Normal")], [2, _("Double (Hi-DPI)")]]
-            combo = GSettingsComboBox(_("User interface scaling:"), "org.cinnamon.desktop.interface", "scaling-factor", ui_scales, valtype="uint")
+            combo = GSettingsComboBox(_("User interface scaling:"), "org.cinnamon.desktop.interface", "scaling-factor", ui_scales, valtype=int)
             settings.add_row(combo)
 
             # Some applications hard code the GNOME path for HiDPI settings,

files/usr/share/cinnamon/cinnamon-settings/modules/cs_mouse.py

@@ -96,7 +96,7 @@ def on_module_selected(self):
 
             clickpad_list = [[0, _("Left click only")], [3, _("Automatic")], [1, _("Emulate mouse buttons")], [2, _("Use multiple fingers for right and middle click")]]
 
-            combo = GSettingsComboBox(_("Click actions"), "org.cinnamon.settings-daemon.peripherals.touchpad", "clickpad-click", clickpad_list, valtype="int")
+            combo = GSettingsComboBox(_("Click actions"), "org.cinnamon.settings-daemon.peripherals.touchpad", "clickpad-click", clickpad_list, valtype=int)
             settings.add_row(combo)
 
             settings = SettingsBox(_("Scrolling"))
@@ -106,7 +106,7 @@ def on_module_selected(self):
             settings.add_row(switch)
 
             clickpad_list = [[0, _("No scrolling")], [3, _("Automatic")], [1, _("Two-finger scrolling")], [2, _("Edge scrolling")]]
-            combo = GSettingsComboBox(_("Scrolling method"), "org.cinnamon.settings-daemon.peripherals.touchpad", "scrolling-method", clickpad_list, valtype="int")
+            combo = GSettingsComboBox(_("Scrolling method"), "org.cinnamon.settings-daemon.peripherals.touchpad", "scrolling-method", clickpad_list, valtype=int)
             settings.add_row(combo)
             switch = GSettingsSwitch(_("Horizontal scrolling"), "org.cinnamon.settings-daemon.peripherals.touchpad", "horizontal-scrolling")
             settings.add_row(switch)

files/usr/share/cinnamon/cinnamon-settings/modules/cs_power.py

@@ -153,9 +153,9 @@ def on_module_selected(self):
                 section.add_row(GSettings2ComboBox(_("When the lid is closed"), CSD_SCHEMA, "lid-close-ac-action", "lid-close-battery-action", lid_options, size_group=size_group))
 
         else:
-            section.add_row(GSettingsComboBox(_("Turn off the screen when inactive for"), CSD_SCHEMA, "sleep-display-ac", SLEEP_DELAY_OPTIONS, valtype="int", size_group=size_group))
+            section.add_row(GSettingsComboBox(_("Turn off the screen when inactive for"), CSD_SCHEMA, "sleep-display-ac", SLEEP_DELAY_OPTIONS, valtype=int, size_group=size_group))
 
-            section.add_row(GSettingsComboBox(_("Suspend when inactive for"), CSD_SCHEMA, "sleep-inactive-ac-timeout", SLEEP_DELAY_OPTIONS, valtype="int", size_group=size_group))
+            section.add_row(GSettingsComboBox(_("Suspend when inactive for"), CSD_SCHEMA, "sleep-inactive-ac-timeout", SLEEP_DELAY_OPTIONS, valtype=int, size_group=size_group))
 
             if self.has_lid:
                 section.add_row(GSettingsComboBox(_("When the lid is closed"), CSD_SCHEMA, "lid-close-ac-action", lid_options, size_group=size_group))
@@ -246,9 +246,9 @@ def on_module_selected(self):
 
             section.add_row(GSettingsSwitch(_("On battery, dim screen when inactive"), CSD_SCHEMA, "idle-dim-battery"))
 
-            section.add_reveal_row(GSettingsComboBox(_("Brightness level when inactive"), CSD_SCHEMA, "idle-brightness", IDLE_BRIGHTNESS_OPTIONS, valtype="int", size_group=size_group), CSD_SCHEMA, "idle-dim-battery")
+            section.add_reveal_row(GSettingsComboBox(_("Brightness level when inactive"), CSD_SCHEMA, "idle-brightness", IDLE_BRIGHTNESS_OPTIONS, valtype=int, size_group=size_group), CSD_SCHEMA, "idle-dim-battery")
 
-            section.add_reveal_row(GSettingsComboBox(_("Dim screen after inactive for"), CSD_SCHEMA, "idle-dim-time", IDLE_DELAY_OPTIONS, valtype="int", size_group=size_group), CSD_SCHEMA, "idle-dim-battery")
+            section.add_reveal_row(GSettingsComboBox(_("Dim screen after inactive for"), CSD_SCHEMA, "idle-dim-time", IDLE_DELAY_OPTIONS, valtype=int, size_group=size_group), CSD_SCHEMA, "idle-dim-battery")
 
     def build_battery_page(self, *args):
 

files/usr/share/cinnamon/cinnamon-settings/modules/cs_screensaver.py

@@ -82,7 +82,7 @@ def on_module_selected(self):
 
         size_group = Gtk.SizeGroup.new(Gtk.SizeGroupMode.HORIZONTAL)
 
-        widget = GSettingsComboBox(_("Delay before starting the screensaver"), "org.cinnamon.desktop.session", "idle-delay", LOCK_INACTIVE_OPTIONS, valtype="uint", size_group=size_group)
+        widget = GSettingsComboBox(_("Delay before starting the screensaver"), "org.cinnamon.desktop.session", "idle-delay", LOCK_INACTIVE_OPTIONS, valtype=int, size_group=size_group)
         widget.set_tooltip_text(_("This option defines the amount of time to wait before starting the screensaver, when the computer is not being used"))
         settings.add_row(widget)
 
@@ -96,7 +96,7 @@ def on_module_selected(self):
         widget.set_tooltip_text(_("Enable this option to require a password when the screen turns itself off, or when the screensaver activates after a period of inactivity"))
         settings.add_row(widget)
 
-        widget = GSettingsComboBox(_("Delay before locking"), schema, "lock-delay", LOCK_DELAY_OPTIONS, valtype="uint", size_group=size_group)
+        widget = GSettingsComboBox(_("Delay before locking"), schema, "lock-delay", LOCK_DELAY_OPTIONS, valtype=int, size_group=size_group)
         widget.set_tooltip_text(_("This option defines the amount of time to wait before locking the screen, after showing the screensaver or after turning off the screen"))
         settings.add_reveal_row(widget, schema, "lock-enabled")