Adding SmartListBox, with docstrings, docs, and examples. Bumping version.

slightlynybbled · slightlynybbled · commit 8bb376bffebe · 2020-05-29T12:44:17.000-04:00
diff --git a/docs/smart_widgets.rst b/docs/smart_widgets.rst
@@ -21,6 +21,12 @@ Smart widgets consist of existing widgets with improved API.  In most cases, the
 .. autoclass:: widgets.SmartCheckbutton
     :members:
 
+``SmartListBox``
+--------------------
+
+.. autoclass:: widgets.SmartListBox
+    :members:
+
 ``BinaryLabel``
 --------------------
 
diff --git a/examples/smart_listbox.py b/examples/smart_listbox.py
@@ -0,0 +1,23 @@
+import tkinter as tk
+import tk_tools
+
+
+if __name__ == '__main__':
+    root = tk.Tk()
+
+    tk.Label(root, text="The variable value: ").grid(row=0, column=0)
+    value_label = tk.Label(root, text="")
+    value_label.grid(row=0, column=1)
+
+    def callback(values):
+        string = ''.join(values)
+        value_label.config(text=string)
+
+    # specify a callback, then specify the normal spinbox options (such as "from_", "to", and "increment"
+    tk.Label(root, text='selectmode="browse"').grid(row=1, column=0)
+    tk_tools.SmartListBox(root, on_select_callback=callback, selectmode='browse',
+                          options=['1', '2', '3']).grid(row=2, column=0)
+    tk.Label(root, text='selectmode="multiple"').grid(row=1, column=0)
+    tk_tools.SmartListBox(root, on_select_callback=callback, selectmode='multiple',
+                          options=['a', 'b', 'c']).grid(row=4, column=0)
+    root.mainloop()
diff --git a/tk_tools/__init__.py b/tk_tools/__init__.py
@@ -3,7 +3,7 @@
     KeyValueEntry, ButtonGrid, Calendar, MultiSlotFrame, \
     SevenSegment, SevenSegmentDigits
 from tk_tools.widgets import SmartOptionMenu, SmartSpinBox, \
-    SmartCheckbutton, BinaryLabel, ByteLabel
+    SmartCheckbutton, SmartListBox, BinaryLabel, ByteLabel
 from tk_tools.tooltips import ToolTip
 
 from tk_tools.version import __version__
@@ -12,8 +12,8 @@
 __all__ = [
     'RotaryScale', 'Gauge', 'Graph', 'Led',
     'EntryGrid', 'LabelGrid', 'ButtonGrid', 'KeyValueEntry',
-    'SmartOptionMenu', 'SmartSpinBox',
-    'SmartCheckbutton', 'Calendar', 'MultiSlotFrame',
+    'SmartOptionMenu', 'SmartSpinBox', 'SmartCheckbutton',
+    'SmartListBox', 'Calendar', 'MultiSlotFrame',
     'SevenSegment', 'SevenSegmentDigits',
     'BinaryLabel', 'ByteLabel', 'ToolTip',
     '__version__'
diff --git a/tk_tools/version.py b/tk_tools/version.py
@@ -1 +1 @@
-__version__ = '0.12.1'
+__version__ = '0.13.0'
diff --git a/tk_tools/widgets.py b/tk_tools/widgets.py
@@ -1,6 +1,8 @@
+import logging
 import tkinter as tk
 import tkinter.ttk as ttk
-import logging
+from typing import List
+
 
 logger = logging.getLogger(__name__)
 
@@ -180,6 +182,105 @@ def internal_callback(*args):
             self._var.trace('w', internal_callback)
 
 
+class SmartListBox(SmartWidget):
+    """
+    Easy-to-use List Box.  Takes most options that work with
+    a normal CheckButton. Attempts to call your callback
+    function - if assigned - whenever there is a change to
+    the list box selections.::
+
+        # create the smart spinbox and grid
+        scb = SmartListBox(root, options=['one', 'two', 'three'])
+        scb.grid()
+
+        # define a callback function that retrieves
+        # the currently selected option
+        def callback():
+            print(scb.get_selected())
+
+        # add the callback function to the checkbutton
+        scb.add_callback(callback)
+
+    :param parent: the tk parent frame
+    :param options: any options that are valid for tkinter.Checkbutton
+    :param on_select_callback: python callable
+    :param selectmode: the selector mode (supports "browse" and "multiple")
+    """
+    def __init__(self, parent, options: List[str],
+                 width: int = 12, height: int = 5,
+                 on_select_callback: callable = None,
+                 selectmode: str = 'browse'):
+        super().__init__(parent=parent)
+
+        self._on_select_callback = on_select_callback
+        self._values = {}
+
+        r = 0
+        self._lb = tk.Listbox(self, width=width, height=height, selectmode=selectmode, exportselection=0)
+        self._lb.grid(row=r, column=0, sticky='ew')
+        [self._lb.insert('end', option) for option in options]
+        self._lb.bind('<<ListboxSelect>>', lambda _: self._on_select())
+
+        r += 1
+        clear_label = tk.Label(self, text='clear', fg='blue')
+        clear_label.grid(row=r, column=0, sticky='ew')
+        clear_label.bind('<Button-1>', lambda _: self._clear_selected())
+
+    def _on_select(self):
+        self.after(200, self.__on_select)
+
+    def _clear_selected(self):
+        for i in self._lb.curselection():
+            self._lb.selection_clear(i, 'end')
+
+        while len(self._values):
+            self._values.popitem()
+
+        if self._on_select_callback is not None:
+            self._on_select_callback()
+
+    def __on_select(self):
+        value = self._lb.get('active')
+
+        if self._lb.cget('selectmode') == 'multiple':
+            if value in self._values.keys():
+                self._values.pop(value)
+            else:
+                self._values[value] = True
+        else:
+            while len(self._values):
+                self._values.popitem()
+            self._values[value] = True
+
+        if self._on_select_callback is not None:
+            values = list(self._values.keys())
+            try:
+                self._on_select_callback(values)
+            except TypeError:
+                self._on_select_callback()
+
+    def add_callback(self, callback: callable):
+        """
+        Associates a callback function when the user makes a selection.
+
+        :param callback: a callable function
+        """
+        self._on_select_callback = callback
+
+    def get_selected(self):
+        return list(self._values.keys())
+
+    def select(self, value):
+        options = self._lb.get(0, 'end')
+        if value not in options:
+            raise ValueError('Not a valid selection')
+
+        option = options.index(value)
+
+        self._lb.activate(option)
+        self._values[value] = True
+
+
 class BinaryLabel(ttk.Label):
     """
     Displays a value binary. Provides methods for

Original file line number	Diff line number	Diff line change
`@@ -1 +1 @@`
`1`		`-__version__ = '0.12.1'`
	`1`	`+__version__ = '0.13.0'`