Make `SelectionWidget.values` a dict

rename 'labels' and '_value' to 'value_names' and 'value_name'.

To specify a mapping of value names and values, use a dict.
If you specify `values=[list]`, then an OrderedDict will be used.

Assignment after construction only supports a dict.

IPython/html/static/notebook/js/widgets/widget_selection.js

@@ -1,376 +1,376 b''
 //----------------------------------------------------------------------------
 //  Copyright (C) 2013 The IPython Development Team
 //
 //  Distributed under the terms of the BSD License.  The full license is in
 //  the file COPYING, distributed as part of this software.
 //----------------------------------------------------------------------------
 
 //============================================================================
 // SelectionWidget
 //============================================================================
 
 /**
  * @module IPython
  * @namespace IPython
  **/
 
 define(["notebook/js/widgets/widget"], function(WidgetManager){
 
     var DropdownView = IPython.DOMWidgetView.extend({
         render : function(){
             // Called when view is rendered.
             this.$el
                 .addClass('widget-hbox-single');
             this.$label = $('<div />')
                 .appendTo(this.$el)
                 .addClass('widget-hlabel')
                 .hide();
             this.$buttongroup = $('<div />')
                 .addClass('widget_item')
                 .addClass('btn-group')
                 .appendTo(this.$el);
             this.$el_to_style = this.$buttongroup; // Set default element to style
             this.$droplabel = $('<button />')
                 .addClass('btn')
                 .addClass('widget-combo-btn')
                 .text(' ')
                 .appendTo(this.$buttongroup);
             this.$dropbutton = $('<button />')
                 .addClass('btn')
                 .addClass('dropdown-toggle')
                 .addClass('widget-combo-carrot-btn')
                 .attr('data-toggle', 'dropdown')
                 .append($('<span />').addClass("caret"))
                 .appendTo(this.$buttongroup);
             this.$droplist = $('<ul />')
                 .addClass('dropdown-menu')
                 .appendTo(this.$buttongroup);
             
             // Set defaults.
             this.update();
         },
         
         update : function(options){
             // Update the contents of this view
             //
             // Called when the model is changed.  The model may have been 
             // changed by another view or by a state update from the back-end.
 
             if (options === undefined || options.updated_view != this) {
-                var selected_item_text = this.model.get('_value');
+                var selected_item_text = this.model.get('value_name');
                 if (selected_item_text.length === 0) {
                     this.$droplabel.text(' ');
                 } else {
                     this.$droplabel.text(selected_item_text);
                 }
                 
-                var items = this.model.get('labels');
+                var items = this.model.get('value_names');
                 var $replace_droplist = $('<ul />')
                     .addClass('dropdown-menu');
                 var that = this;
                 _.each(items, function(item, i) {
                     var item_button = $('<a href="#"/>')
                         .text(item)
                         .on('click', $.proxy(that.handle_click, that));
                     $replace_droplist.append($('<li />').append(item_button));
                 });
 
                 this.$droplist.replaceWith($replace_droplist);
                 this.$droplist.remove();
                 this.$droplist = $replace_droplist;
                 
                 if (this.model.get('disabled')) {
                     this.$buttongroup.attr('disabled','disabled');
                     this.$droplabel.attr('disabled','disabled');
                     this.$dropbutton.attr('disabled','disabled');
                     this.$droplist.attr('disabled','disabled');
                 } else {
                     this.$buttongroup.removeAttr('disabled');
                     this.$droplabel.removeAttr('disabled');
                     this.$dropbutton.removeAttr('disabled');
                     this.$droplist.removeAttr('disabled');
                 }
 
                 var description = this.model.get('description');
                 if (description.length === 0) {
                     this.$label.hide();
                 } else {
                     this.$label.text(description);
                     this.$label.show();
                 }
             }
             return DropdownView.__super__.update.apply(this);
         },
 
         handle_click: function (e) {
             // Handle when a value is clicked.
             
             // Calling model.set will trigger all of the other views of the 
             // model to update.
-            this.model.set('_value', $(e.target).text(), {updated_view: this});
+            this.model.set('value_name', $(e.target).text(), {updated_view: this});
             this.touch();
         },
         
     });
     WidgetManager.register_widget_view('DropdownView', DropdownView);
 
 
     var RadioButtonsView = IPython.DOMWidgetView.extend({    
         render : function(){
             // Called when view is rendered.
             this.$el
                 .addClass('widget-hbox');
             this.$label = $('<div />')
                 .appendTo(this.$el)
                 .addClass('widget-hlabel')
                 .hide();
             this.$container = $('<div />')
                 .appendTo(this.$el)
                 .addClass('widget-container')
                 .addClass('vbox');
             this.$el_to_style = this.$container; // Set default element to style
             this.update();
         },
         
         update : function(options){
             // Update the contents of this view
             //
             // Called when the model is changed.  The model may have been 
             // changed by another view or by a state update from the back-end.
             if (options === undefined || options.updated_view != this) {
                 // Add missing items to the DOM.
-                var items = this.model.get('labels');
+                var items = this.model.get('value_names');
                 var disabled = this.model.get('disabled');
                 var that = this;
                 _.each(items, function(item, index) {
                     var item_query = ' :input[value="' + item + '"]';
                     if (that.$el.find(item_query).length === 0) {
                         var $label = $('<label />')
                             .addClass('radio')
                             .text(item)
                             .appendTo(that.$container);
                         
                         $('<input />')
                             .attr('type', 'radio')
                             .addClass(that.model)
                             .val(item)
                             .prependTo($label)
                             .on('click', $.proxy(that.handle_click, that));
                     }
                     
                     var $item_element = that.$container.find(item_query);
-                    if (that.model.get('_value') == item) {
+                    if (that.model.get('value_name') == item) {
                         $item_element.prop('checked', true);
                     } else {
                         $item_element.prop('checked', false);
                     }
                     $item_element.prop('disabled', disabled);
                 });
                 
                 // Remove items that no longer exist.
                 this.$container.find('input').each(function(i, obj) {
                     var value = $(obj).val();
                     var found = false;
                     _.each(items, function(item, index) {
                         if (item == value) {
                             found = true;
                             return false;
                         }
                     });
                     
                     if (!found) {
                         $(obj).parent().remove();
                     }
                 });
 
                 var description = this.model.get('description');
                 if (description.length === 0) {
                     this.$label.hide();
                 } else {
                     this.$label.text(description);
                     this.$label.show();
                 }
             }
             return RadioButtonsView.__super__.update.apply(this);
         },
 
         handle_click: function (e) {
             // Handle when a value is clicked.
             
             // Calling model.set will trigger all of the other views of the 
             // model to update.
-            this.model.set('_value', $(e.target).val(), {updated_view: this});
+            this.model.set('value_name', $(e.target).val(), {updated_view: this});
             this.touch();
         },
     });
     WidgetManager.register_widget_view('RadioButtonsView', RadioButtonsView);
 
 
-    var ToggleButtonsView = IPython.DOMWidgetView.extend({    
+    var ToggleButtonsView = IPython.DOMWidgetView.extend({
         render : function(){
             // Called when view is rendered.
             this.$el
                 .addClass('widget-hbox-single');
             this.$label = $('<div />')
                 .appendTo(this.$el)
                 .addClass('widget-hlabel')
                 .hide();
             this.$buttongroup = $('<div />')
                 .addClass('btn-group')
                 .attr('data-toggle', 'buttons-radio')
                 .appendTo(this.$el);
             this.$el_to_style = this.$buttongroup; // Set default element to style
             this.update();
         },
         
         update : function(options){
             // Update the contents of this view
             //
             // Called when the model is changed.  The model may have been 
             // changed by another view or by a state update from the back-end.
             if (options === undefined || options.updated_view != this) {
                 // Add missing items to the DOM.
-                var items = this.model.get('labels');
+                var items = this.model.get('value_names');
                 var disabled = this.model.get('disabled');
                 var that = this;
                 _.each(items, function(item, index) {
                    var item_query = ' :contains("' + item + '")';
                     if (that.$buttongroup.find(item_query).length === 0) {
                         $('<button />')
                             .attr('type', 'button')
                             .addClass('btn')
                             .text(item)
                             .appendTo(that.$buttongroup)
                             .on('click', $.proxy(that.handle_click, that));
                     }
                     
                     var $item_element = that.$buttongroup.find(item_query);
-                    if (that.model.get('_value') == item) {
+                    if (that.model.get('value_name') == item) {
                         $item_element.addClass('active');
                     } else {
                         $item_element.removeClass('active');
                     }
                     $item_element.prop('disabled', disabled); 
                 });
                 
                 // Remove items that no longer exist.
                 this.$buttongroup.find('button').each(function(i, obj) {
                     var value = $(obj).text();
                     var found = false;
                     _.each(items, function(item, index) {
                         if (item == value) {
                             found = true;
                             return false;
                         }
                     });
 
                     if (!found) {
                         $(obj).remove();
                     }
                 });
 
                 var description = this.model.get('description');
                 if (description.length === 0) {
                     this.$label.hide();
                 } else {
                     this.$label.text(description);
                     this.$label.show();
                 }
             }
             return ToggleButtonsView.__super__.update.apply(this);
         },
 
         handle_click: function (e) {
             // Handle when a value is clicked.
             
             // Calling model.set will trigger all of the other views of the 
             // model to update.
-            this.model.set('_value', $(e.target).text(), {updated_view: this});
+            this.model.set('value_name', $(e.target).text(), {updated_view: this});
             this.touch();
         },    
     });
     WidgetManager.register_widget_view('ToggleButtonsView', ToggleButtonsView);
 
 
     var SelectView = IPython.DOMWidgetView.extend({    
         render : function(){
             // Called when view is rendered.
             this.$el
                 .addClass('widget-hbox');
             this.$label = $('<div />')
                 .appendTo(this.$el)
                 .addClass('widget-hlabel')
                 .hide();
             this.$listbox = $('<select />')
                 .addClass('widget-listbox')
                 .attr('size', 6)
                 .appendTo(this.$el);
             this.$el_to_style = this.$listbox; // Set default element to style
             this.update();
         },
         
         update : function(options){
             // Update the contents of this view
             //
             // Called when the model is changed.  The model may have been 
             // changed by another view or by a state update from the back-end.
             if (options === undefined || options.updated_view != this) {
                 // Add missing items to the DOM.
-                var items = this.model.get('labels');
+                var items = this.model.get('value_names');
                 var that = this;
                 _.each(items, function(item, index) {
                    var item_query = ' :contains("' + item + '")';
                     if (that.$listbox.find(item_query).length === 0) {
                         $('<option />')
                             .text(item)
-                            .attr('_value', item)
+                            .attr('value_name', item)
                             .appendTo(that.$listbox)
                             .on('click', $.proxy(that.handle_click, that));
                     } 
                 });
 
                 // Select the correct element
-                this.$listbox.val(this.model.get('_value'));
+                this.$listbox.val(this.model.get('value_name'));
                 
                 // Disable listbox if needed
                 var disabled = this.model.get('disabled');
                 this.$listbox.prop('disabled', disabled);
 
                 // Remove items that no longer exist.
                 this.$listbox.find('option').each(function(i, obj) {
                     var value = $(obj).text();
                     var found = false;
                     _.each(items, function(item, index) {
                         if (item == value) {
                             found = true;
                             return false;
                         }
                     });
                     
                     if (!found) {
                         $(obj).remove();
                     }
                 });
 
                 var description = this.model.get('description');
                 if (description.length === 0) {
                     this.$label.hide();
                 } else {
                     this.$label.text(description);
                     this.$label.show();
                 }
             }
             return SelectView.__super__.update.apply(this);
         },
 
         handle_click: function (e) {
             // Handle when a value is clicked.
             
             // Calling model.set will trigger all of the other views of the 
             // model to update.
-            this.model.set('_value', $(e.target).text(), {updated_view: this});
+            this.model.set('value_name', $(e.target).text(), {updated_view: this});
             this.touch();
         },    
     });
     WidgetManager.register_widget_view('SelectView', SelectView);
 });

IPython/html/tests/casperjs/test_cases/widgets_selection.js

@@ -1,133 +1,135 b''
 // Test selection class
 casper.notebook_test(function () {
     index = this.append_cell(
         'from IPython.html import widgets\n' + 
         'from IPython.display import display, clear_output\n' +
         'print("Success")');
     this.execute_cell_then(index);
 
     var combo_selector = '.widget-area .widget-subarea .widget-hbox-single .btn-group .widget-combo-btn';
     var multibtn_selector = '.widget-area .widget-subarea .widget-hbox-single .btn-group[data-toggle="buttons-radio"]';
     var radio_selector = '.widget-area .widget-subarea .widget-hbox .vbox';
     var list_selector = '.widget-area .widget-subarea .widget-hbox .widget-listbox';
 
     var selection_index;
     var selection_values = 'abcd';
     var check_state = function(context, index, state){
         if (0 <= index && index < selection_values.length) {
             var multibtn_state = context.cell_element_function(selection_index, multibtn_selector + ' .btn:nth-child(' + (index + 1) + ')', 'hasClass', ['active']);
             var radio_state = context.cell_element_function(selection_index, radio_selector + ' .radio:nth-child(' + (index + 1) + ') input', 'prop', ['checked']);
             var list_val = context.cell_element_function(selection_index, list_selector, 'val');
             var combo_val = context.cell_element_function(selection_index, combo_selector, 'html');
             
             var val = selection_values.charAt(index);
             var list_state = (val == list_val);
             var combo_state = (val == combo_val);
 
             return multibtn_state == state &&
                 radio_state == state &&
                 list_state == state &&
                 combo_state == state;
         }
         return true;
     };
 
     var verify_selection = function(context, index){
         for (var i = 0; i < selection_values.length; i++) {
             if (!check_state(context, i, i==index)) {
                 return false;
             }
         }
         return true;
     };
 
 //values=["' + selection_values + '"[i] for i in range(4)]
     selection_index = this.append_cell(
         'values=["' + selection_values + '"[i] for i in range(4)]\n' +
         'selection = [widgets.DropdownWidget(values=values),\n' +
         '    widgets.ToggleButtonsWidget(values=values),\n' +
         '    widgets.RadioButtonsWidget(values=values),\n' +
         '    widgets.SelectWidget(values=values)]\n' +
         '[display(selection[i]) for i in range(4)]\n' +
         'for widget in selection:\n' +
         '    def handle_change(name,old,new):\n' +
         '        for other_widget in selection:\n' +
         '            other_widget.value = new\n' +
         '    widget.on_trait_change(handle_change, "value")\n' +
         'print("Success")\n');
     this.execute_cell_then(selection_index, function(index){
         this.test.assertEquals(this.get_output_cell(index).text, 'Success\n', 
             'Create selection cell executed with correct output.');
 
         this.test.assert(this.cell_element_exists(index, 
             '.widget-area .widget-subarea'),
             'Widget subarea exists.');
 
         this.test.assert(this.cell_element_exists(index, combo_selector),
              'Widget combobox exists.');
 
         this.test.assert(this.cell_element_exists(index, multibtn_selector),
             'Widget multibutton exists.');
 
         this.test.assert(this.cell_element_exists(index, radio_selector),
             'Widget radio buttons exists.');
 
         this.test.assert(this.cell_element_exists(index, list_selector),
             'Widget list exists.');
 
         // Verify that no items are selected.
         this.test.assert(verify_selection(this, -1), 'No items selected.');
     });
 
     index = this.append_cell(
         'for widget in selection:\n' +
         '    widget.value = "a"\n' +
         'print("Success")\n');
     this.execute_cell_then(index, function(index){
         this.test.assertEquals(this.get_output_cell(index).text, 'Success\n', 
             'Python select item executed with correct output.');
 
         // Verify that the first item is selected.
         this.test.assert(verify_selection(this, 0), 'Python selected');
 
         // Verify that selecting a radio button updates all of the others.
         this.cell_element_function(selection_index, radio_selector + ' .radio:nth-child(2) input', 'click');
     });
     this.wait(500);
     this.then(function () {
         this.test.assert(verify_selection(this, 1), 'Radio button selection updated view states correctly.');
 
         // Verify that selecting a list option updates all of the others.
         this.cell_element_function(selection_index, list_selector + ' option:nth-child(3)', 'click');
     });
     this.wait(500);
     this.then(function () {
         this.test.assert(verify_selection(this, 2), 'List selection updated view states correctly.');
 
         // Verify that selecting a multibutton option updates all of the others.
         this.cell_element_function(selection_index, multibtn_selector + ' .btn:nth-child(4)', 'click');
     });
     this.wait(500);
     this.then(function () {
         this.test.assert(verify_selection(this, 3), 'Multibutton selection updated view states correctly.');
 
         // Verify that selecting a combobox option updates all of the others.
         this.cell_element_function(selection_index, '.widget-area .widget-subarea .widget-hbox-single .btn-group ul.dropdown-menu li:nth-child(3) a', 'click');
     });
     this.wait(500);
     this.then(function () {
         this.test.assert(verify_selection(this, 2), 'Combobox selection updated view states correctly.');
     });
 
     this.wait(500); // Wait for change to execute in kernel
 
     index = this.append_cell(
         'for widget in selection:\n' +
-        '    widget.values = list(widget.values) + ["z"]\n' +
+        '    d = widget.values.copy()\n' +
+        '    d["z"] = "z"\n' +
+        '    widget.values = d\n' +
         'selection[0].value = "z"');
     this.execute_cell_then(index, function(index){
 
         // Verify that selecting a combobox option updates all of the others.
         this.test.assert(verify_selection(this, 4), 'Item added to selection widget.');
     });
 });
  No newline at end of file

IPython/html/widgets/widget_selection.py

@@ -1,95 +1,113 b''
-"""SelectionWidget class.  
+"""SelectionWidget classes.
 
 Represents an enumeration using a widget.
 """
 #-----------------------------------------------------------------------------
 # Copyright (c) 2013, the IPython Development Team.
 #
 # Distributed under the terms of the Modified BSD License.
 #
 # The full license is in the file COPYING.txt, distributed with this software.
 #-----------------------------------------------------------------------------
 
 #-----------------------------------------------------------------------------
 # Imports
 #-----------------------------------------------------------------------------
+
+from collections import OrderedDict
 from threading import Lock
 
 from .widget import DOMWidget
-from IPython.utils.traitlets import Unicode, List, Bool, Any, Dict
+from IPython.utils.traitlets import Unicode, List, Bool, Any, Dict, TraitError
+from IPython.utils.py3compat import unicode_type
 
 #-----------------------------------------------------------------------------
 # SelectionWidget
 #-----------------------------------------------------------------------------
 class _SelectionWidget(DOMWidget):
-    value = Any(help="Selected value") 
-    values = List(help="List of values the user can select")
-    labels = List(help="""List of string representations for each value.  
-        These string representations are used to display the values in the
-        front-end.""", sync=True) # Only synced to the back-end.
+    """Base class for Selection widgets
+    
+    ``values`` can be specified as a list or dict. If given as a list,
+    it will be transformed to a dict of the form ``{str(value):value}``.
+    """
+    
+    value = Any(help="Selected value")
+    values = Dict(help="""Dictionary of {name: value} the user can select.
+    
+    The keys of this dictionary are the strings that will be displayed in the UI,
+    representing the actual Python choices.
+    
+    The keys of this dictionary are also available as value_names.
+    """)
+    value_name = Unicode(help="The name of the selected value", sync=True)
+    value_names = List(Unicode, help="""List of names for each value.
+        
+        If values is specified as a list, this is the string representation of each element.
+        Otherwise, it is the keys of the values dictionary.
+        
+        These strings are used to display the choices in the front-end.""", sync=True)
     disabled = Bool(False, help="Enable or disable user changes", sync=True)
     description = Unicode(help="Description of the value this widget represents", sync=True)
+    
 
-    _value = Unicode(sync=True) # Bi-directionally synced.
-
-    def __init__(self, *pargs, **kwargs):
-        """Constructor"""
+    def __init__(self, *args, **kwargs):
         self.value_lock = Lock()
-        self.on_trait_change(self._string_value_set, ['_value'])
-        DOMWidget.__init__(self, *pargs, **kwargs)
-
-    def _labels_changed(self, name=None, old=None, new=None):
-        """Handles when the value_names Dict has been changed.
+        if 'values' in kwargs:
+            values = kwargs['values']
+            # convert list values to an dict of {str(v):v}
+            if isinstance(values, list):
+                # preserve list order with an OrderedDict
+                kwargs['values'] = OrderedDict((unicode_type(v), v) for v in values)
+        DOMWidget.__init__(self, *args, **kwargs)
+    
+    def _values_changed(self, name, old, new):
+        """Handles when the values dict has been changed.
 
-        This method sets the _reverse_value_names Dict to the inverse of the new
-        value for the value_names Dict."""
+        Setting values implies setting value names from the keys of the dict.
+        """
+        self.value_names = list(new.keys())
+    
+    def _value_names_changed(self, name, old, new):
         if len(new) != len(self.values):
-            raise TypeError('Labels list must be the same size as the values list.')
-
-    def _values_changed(self, name=None, old=None, new=None):
-        """Handles when the value_names Dict has been changed.
-
-        This method sets the _reverse_value_names Dict to the inverse of the new
-        value for the value_names Dict."""
-        if len(new) != len(self.labels):
-            self.labels = [(self.labels[i] if i < len(self.labels) else str(v)) for i, v in enumerate(new)]
+            raise TraitError("Expected %i value names, got %i." % (len(self.values), len(new)))
 
     def _value_changed(self, name, old, new):
         """Called when value has been changed"""
         if self.value_lock.acquire(False):
             try:
-                # Make sure the value is in the list of values.
-                if new in self.values:
-                    # Set the string version of the value.
-                    self._value = self.labels[self.values.index(new)]
-                else:
-                    raise TypeError('Value must be a value in the values list.')
+                # Make sure the value is one of the options
+                for k,v in self.values.items():
+                    if new == v:
+                        # set the selected value name
+                        self.value_name = k
+                        return
+                raise TraitError('Value not found: %r' % new)
             finally:
                 self.value_lock.release()
 
-    def _string_value_set(self, name, old, new):
-        """Called when _value has been changed."""
+    def _value_name_changed(self, name, old, new):
+        """Called when the value name has been changed (typically by the frontend)."""
         if self.value_lock.acquire(False):
             try:
-                if new in self.labels:
-                    self.value = self.values[self.labels.index(new)]
+                if new in self.values:
+                    self.value = self.values[new]
                 else:
                     self.value = None
             finally:
                 self.value_lock.release()
 
 
 class ToggleButtonsWidget(_SelectionWidget):
     _view_name = Unicode('ToggleButtonsView', sync=True)
 
 
 class DropdownWidget(_SelectionWidget):
     _view_name = Unicode('DropdownView', sync=True)
 
 
 class RadioButtonsWidget(_SelectionWidget):
     _view_name = Unicode('RadioButtonsView', sync=True)
     
 
 class SelectWidget(_SelectionWidget):
     _view_name = Unicode('SelectView', sync=True)