Documentation improvements

tk_tools/groups.py

@@ -42,7 +42,7 @@ def __init__(self, parent, num_of_columns: int, headers: list=None,
                 self.headers.append(label)
 
     def add_row(self, data: list):
-        r"""
+        """
         Adds a row of data based on the entered data
 
         :param data: row of data as a list
@@ -51,7 +51,7 @@ def add_row(self, data: list):
         raise NotImplementedError
 
     def _redraw(self):
-        r"""
+        """
         Forgets the current layout and redraws with the most recent information
 
         :return: None
@@ -66,7 +66,7 @@ def _redraw(self):
                 widget.grid(row=i+offset, column=j)
 
     def remove_row(self, row_number: int=-1):
-        r"""
+        """
         Removes a specified row of data
 
         :param row_number: the row to remove (defaults to the last row)
@@ -80,7 +80,7 @@ def remove_row(self, row_number: int=-1):
             widget.destroy()
 
     def clear(self):
-        r"""
+        """
         Removes all elements of the grid
 
         :return: None
@@ -104,7 +104,7 @@ def __init__(self, parent,
         super().__init__(self._parent, num_of_columns, headers, **options)
 
     def add_row(self, data: list):
-        r"""
+        """
         Add a row of data to the current widget
 
         :param data: a row of data
@@ -127,7 +127,7 @@ def add_row(self, data: list):
 
 
 class EntryGrid(Grid):
-    r"""
+    """
     Add a spreadsheet-like grid of entry widgets.
 
     :param parent: the tk parent element of this frame
@@ -140,7 +140,7 @@ def __init__(self, parent,
         super().__init__(parent, num_of_columns, headers, **options)
 
     def add_row(self, data: list=None):
-        r"""
+        """
         Add a row of data to the current widget, add a <Tab> \
         binding to the last element of the last row, and set \
         the focus at the beginning of the next row.
@@ -188,7 +188,7 @@ def add(e):
         self._redraw()
 
     def _read_as_dict(self):
-        r"""
+        """
         Read the data contained in all entries as a list of
         dictionaries with the headers as the dictionary keys
 
@@ -205,7 +205,7 @@ def _read_as_dict(self):
         return data
 
     def _read_as_table(self):
-        r"""
+        """
         Read the data contained in all entries as a list of
         lists containing all of the data
 
@@ -219,7 +219,7 @@ def _read_as_table(self):
         return rows
 
     def read(self, as_dicts=True):
-        r"""
+        """
         Read the data from the entry fields
 
         :param as_dicts: True if list of dicts required, else False
@@ -232,7 +232,7 @@ def read(self, as_dicts=True):
 
 
 class ButtonGrid(Grid):
-    r"""
+    """
     A grid of buttons.
 
     :param parent: the tk parent element of this frame
@@ -244,7 +244,7 @@ def __init__(self, parent, num_of_columns: int, headers: list=None,
         super().__init__(parent, num_of_columns, headers, **options)
 
     def add_row(self, data: list = None):
-        r"""
+        """
         Add a row of data to the current widget
         :param data: a row of data
         :return: None
@@ -270,7 +270,7 @@ def add_row(self, data: list = None):
 
 
 class KeyValueEntry(tk.Frame):
-    r"""
+    """
     Creates a key-value input/output frame.
 
     :param parent: the parent frame
@@ -580,7 +580,7 @@ def _get_calendar(locale, fwday):
 
 
 class Calendar(ttk.Frame):
-    r"""
+    """
     Graphical date selection widget, with callbacks.
 
     :param parent: the parent frame
@@ -726,7 +726,7 @@ def _build_calendar(self):
             self._calendar.item(item, values=fmt_week)
 
     def _show_selection(self, text, bbox):
-        r"""
+        """
         Configure canvas for a new selection.
         """
         x, y, width, height = bbox
@@ -742,7 +742,7 @@ def _show_selection(self, text, bbox):
     # Callbacks
 
     def _pressed(self, evt):
-        r"""
+        """
         Clicked somewhere in the calendar.
         """
         x, y, widget = evt.x, evt.y, evt.widget
@@ -774,7 +774,7 @@ def _pressed(self, evt):
             self.callback()
 
     def add_callback(self, callback: callable):
-        r"""
+        """
         Adds a callback to call when the user clicks on a date
 
         :param callback: a callable function
@@ -783,7 +783,7 @@ def add_callback(self, callback: callable):
         self.callback = callback
 
     def _prev_month(self):
-        r"""
+        """
         Updated calendar to show the previous month.
         """
         self._canvas.place_forget()
@@ -793,7 +793,7 @@ def _prev_month(self):
         self._build_calendar()  # reconstruct calendar
 
     def _next_month(self):
-        r"""
+        """
         Update calendar to show the next month.
         """
         self._canvas.place_forget()
@@ -806,7 +806,7 @@ def _next_month(self):
 
     @property
     def selection(self):
-        r"""
+        """
         Return a datetime representing the current selected date.
         """
         if not self._selection:
@@ -891,7 +891,7 @@ def get(self):
 
 
 class MultiSlotFrame(ttk.Frame):
-    r"""
+    """
     Can hold several removable elements,
     such as a list of files, directories,
     or a checklist.::

tk_tools/tooltips.py

@@ -3,18 +3,30 @@
 
 class ToolTip(object):
     """
-    Create a tooltip for a given widget
+    Add a tooltip to any widget.::
+
+        entry = tk.Entry(root)
+        entry.grid()
+
+        # createst a tooltip
+        tk_tools.ToolTip(entry, '_enter a value between 1 and 10')
+
+    :param widget: the widget on which to hover
+    :param text: the text to display
+    :param time: the time to display the text, in milliseconds
     """
 
-    def __init__(self, widget, text='widget info'):
+    def __init__(self, widget, text='widget info', time: int=2000):
         self._widget = widget
         self._text = text
-        self._widget.bind("<Enter>", self.enter)
-        self._widget.bind("<Leave>", self.close)
+        self._time = time
+
+        self._widget.bind("<Enter>", self._enter)
+        self._widget.bind("<Leave>", self._close)
 
         self._tw = None
 
-    def enter(self, event=None):
+    def _enter(self, event=None):
         x, y, cx, cy = self._widget.bbox("insert")
         x += self._widget.winfo_rootx() + 25
         y += self._widget.winfo_rooty() + 20
@@ -31,6 +43,8 @@ def enter(self, event=None):
 
         label.pack(ipadx=1)
 
-    def close(self, event=None):
+        self._tw.after(self._time, self._tw.destroy)
+
+    def _close(self, event=None):
         if self._tw:
             self._tw.destroy()