Merge tooltip into master to replace Balloon with Tooltip

AUTHORS.md

@@ -8,7 +8,7 @@ This file contains a list of all the authors of widgets in this repository. Plea
   * `ScrolledListbox`
   * `FontChooser`, based on an idea by [Nelson Brochado](https://www.github.com/nbro)
   * `FontSelectFrame`
-  * `Balloon`
+  * `Tooltip`
   * `ItemsCanvas`
   * `TimeLine`
 - The Python Team

docs/source/authors.rst

@@ -11,7 +11,7 @@ List of all the authors of widgets in this repository. Please note that this lis
   * :class:`~ttkwidgets.ScrolledListbox`
   * :class:`~ttkwidgets.font.FontChooser`, based on an idea by `Nelson Brochado <https://www.github.com/nbro>`_
   * :class:`~ttkwidgets.font.FontSelectFrame`
-  * :class:`~ttkwidgets.frames.Balloon`
+  * :class:`~ttkwidgets.frames.Tooltip`
   * :class:`~ttkwidgets.ItemsCanvas`
   * :class:`~ttkwidgets.TimeLine`
 

docs/source/ttkwidgets/ttkwidgets.frames.rst

@@ -11,6 +11,6 @@ ttkwidgets.frames
     :nosignatures:
     :toctree: ttkwidgets.frames
 
-    Balloon
+    Tooltip
     ScrolledFrame
     ToggledFrame

docs/source/ttkwidgets/ttkwidgets.frames/ttkwidgets.frames.Balloon.rst → docs/source/ttkwidgets/ttkwidgets.frames/ttkwidgets.frames.Tooltip.rst

@@ -1,10 +1,10 @@
-Balloon
+Tooltip
 =======
 
 .. currentmodule:: ttkwidgets.frames
 
-.. autoclass:: Balloon
+.. autoclass:: Tooltip
    :show-inheritance:
    :members:
 
-   .. automethod:: __init__
+   .. automethod:: __init__

examples/example_balloon.py → examples/example_tooltip.py

@@ -2,13 +2,12 @@
 
 # Copyright (c) RedFantom 2017
 # For license see LICENSE
-from ttkwidgets.frames import Balloon
+from ttkwidgets.frames import Tooltip
 import tkinter as tk
-from tkinter import ttk
 
 
 window = tk.Tk()
 button = tk.Button(window, text="Button", command=window.destroy)
 button.pack()
-balloon = Balloon(button)
+balloon = Tooltip(button)
 window.mainloop()

tests/test_balloon.py

@@ -1,32 +1,39 @@
-# Copyright (c) RedFantom 2017
-# For license see LICENSE
-from ttkwidgets.frames import Balloon
+"""
+Author: RedFantom
+License: GNU GPLv3
+Source: This repository
+"""
+from ttkwidgets.frames import Tooltip
+from ttkwidgets.utilities import parse_geometry_string
 from tests import BaseWidgetTest
 import tkinter as tk
 from time import sleep
 
 
-class TestBalloon(BaseWidgetTest):
+class TestTooltip(BaseWidgetTest):
     def test_balloon_init(self):
-        balloon = Balloon(self.window)
+        balloon = Tooltip(self.window)
         self.window.update()
 
     def test_balloon_kwargs(self):
-        balloon = Balloon(self.window, headertext="Help", text="This is a test for the Balloon widget.", width=300,
-                          timeout=2, background="white")
+        balloon = Tooltip(self.window, headertext="Help", text="This is a test for the Tooltip widget.", width=300,
+                          timeout=2, background="white", showheader=True, offset=(20, 20), static=True)
         self.assertEqual(balloon.cget("headertext"), "Help")
-        self.assertEqual(balloon.cget("text"), "This is a test for the Balloon widget.")
+        self.assertEqual(balloon.cget("text"), "This is a test for the Tooltip widget.")
         self.assertEqual(balloon.cget("width"), 300)
         self.assertEqual(balloon.cget("timeout"), 2)
         self.assertEqual(balloon.cget("background"), "white")
 
-        balloon.config(headertext="New Help", text="This is another test for the Balloon widget.", width=400,
+        balloon.config(headertext="New Help", text="This is another test for the Tooltip widget.", width=400,
                        timeout=3, background="black")
         self.assertEqual(balloon["headertext"], "New Help")
-        self.assertEqual(balloon["text"], "This is another test for the Balloon widget.")
+        self.assertEqual(balloon["text"], "This is another test for the Tooltip widget.")
         self.assertEqual(balloon["width"], 400)
         self.assertEqual(balloon["timeout"], 3)
         self.assertEqual(balloon["background"], "black")
+        self.assertEqual(balloon["showheader"], True)
+        self.assertEqual(balloon["offset"], (20, 20))
+        self.assertEqual(balloon["static"], True)
 
         # Keys for the Frame widget
         balloon.configure(height=40)
@@ -38,8 +45,29 @@ def test_balloon_kwargs(self):
         for key in ["headertext", "text", "width", "timeout", "background"]:
             self.assertIn(key, balloon.keys())
 
+        balloon.config(showheader=False)
+        balloon.show()
+        self.assertFalse(balloon.header_label.winfo_viewable() == 1)
+
+        balloon.config(offset=(0, 0))
+        balloon.show()
+        self.window.update()
+        x1, y1, _, _ = parse_geometry_string(balloon._toplevel.winfo_geometry())
+        balloon.config(offset=(20, 20))
+        balloon._on_leave(None)
+        balloon.show()
+        self.window.update()
+        x2, y2, _, _ = parse_geometry_string(balloon._toplevel.winfo_geometry())
+        self.assertTrue(x2 - x1 == 20 and y2 - y1 == 20)
+
+        balloon.config(static=False)
+        balloon.show()
+        self.window.update()
+        x3, y3, _, _ = parse_geometry_string(balloon._toplevel.winfo_geometry())
+        self.assertFalse(x2 == x3 or y2 == y3)
+
     def test_balloon_show(self):
-        balloon = Balloon(self.window)
+        balloon = Tooltip(self.window)
         self.window.update()
         balloon.show()
         self.window.update()
@@ -51,7 +79,7 @@ def test_balloon_show(self):
         self.assertIs(balloon._toplevel, None)
 
     def test_balloon_events(self):
-        balloon = Balloon(self.window, timeout=0.2)
+        balloon = Tooltip(self.window, timeout=0.2)
         balloon._on_enter(None)
         self.window.update()
         sleep(0.3)
@@ -61,7 +89,6 @@ def test_balloon_events(self):
         self.assertIs(balloon._toplevel, None)
 
     def test_balloon_events_noshow(self):
-        balloon = Balloon(self.window)
+        balloon = Tooltip(self.window)
         balloon._on_enter(None)
         balloon._on_leave(None)
-

ttkwidgets/frames/__init__.py

@@ -2,4 +2,4 @@
 # Available under the license found in LICENSE
 from .scrolledframe import ScrolledFrame
 from .toggledframe import ToggledFrame
-from .balloon import Balloon
+from .tooltip import Tooltip

ttkwidgets/frames/balloon.py → ttkwidgets/frames/tooltip.py

@@ -10,26 +10,35 @@
 from ttkwidgets.utilities import get_assets_directory
 
 
-class Balloon(ttk.Frame):
+class Tooltip(ttk.Frame):
     """Simple help hover balloon."""
 
     def __init__(self, master=None, headertext="Help", text="Some great help is displayed here.", width=200, timeout=1,
-                 background="#fef9cd", **kwargs):
+                 background="#fef9cd", offset=(2, 2), showheader=True, static=False, **kwargs):
         """
-        Create a Balloon.
+        Create a Tooltip
 
-        :param master: widget to bind the Balloon to
+        :param master: widget to bind the Tooltip to
         :type master: widget
         :param headertext: text to show in window header
         :type headertext: str
         :param text: text to show as help text
         :type text: str
         :param width: width of the window
         :type width: int
-        :param timeout: timeout in seconds to wait until the Balloon is shown
+        :param timeout: timeout in seconds to wait until the Tooltip is shown
         :type timeout: float
-        :param background: background color of the Balloon
+        :param background: background color of the Tooltip
         :type background: str
+        :param offset: The offset from the mouse position the Ballon shows up
+        :type offset: Tuple[int, int]
+        :param showheader: Whether to display the header with image
+        :type showheader: bool
+        :param static: Whether to display the tooltip with static
+            position. When the position is set to static, the balloon
+            will always appear an offset from the bottom right corner of
+            the widget.
+        :type static: bool
         :param kwargs: keyword arguments passed on to the :class:`ttk.Frame` initializer
         """
         ttk.Frame.__init__(self, master, **kwargs)
@@ -47,11 +56,21 @@ def __init__(self, master=None, headertext="Help", text="Some great help is disp
         self.__headertext = headertext
         self.__text = text
         self.__width = width
+        self.__offset = offset
+        self.__showheader = showheader
+        self.__static = static
+
         self.master = master
         self._id = None
         self._timeout = timeout
-        self.master.bind("<Enter>", self._on_enter)
-        self.master.bind("<Leave>", self._on_leave)
+
+        self._bind_to_master()
+
+    def _bind_to_master(self):
+        """Bind the Balloon widget to the master widget's events"""
+        self.master.bind("<Enter>", self._on_enter, "add")
+        self.master.bind("<Leave>", self._on_leave, "add")
+        self.master.bind("<ButtonPress>", self._on_leave, "add")
 
     def __getitem__(self, key):
         return self.cget(key)
@@ -62,7 +81,8 @@ def __setitem__(self, key, value):
     def _grid_widgets(self):
         """Place the widgets in the Toplevel."""
         self._canvas.grid(sticky="nswe")
-        self.header_label.grid(row=1, column=1, sticky="nswe", pady=5, padx=5)
+        if self.__showheader is True:
+            self.header_label.grid(row=1, column=1, sticky="nswe", pady=5, padx=5)
         self.text_label.grid(row=3, column=1, sticky="nswe", pady=6, padx=5)
 
     def _on_enter(self, event):
@@ -80,9 +100,10 @@ def _on_leave(self, event):
 
     def show(self):
         """
-        Create the Toplevel widget and its child widgets to show in the spot of the cursor.
+        Create the Toplevel and its children to show near the cursor
 
-        This is the callback for the delayed :obj:`<Enter>` event (see :meth:`~Balloon._on_enter`). 
+        This is the callback for the delayed :obj:`<Enter>` event
+        (see :meth:`~Tooltip._on_enter`).
         """
         self._toplevel = tk.Toplevel(self.master)
         self._canvas = tk.Canvas(self._toplevel, background=self.__background)
@@ -93,11 +114,17 @@ def show(self):
         self._toplevel.attributes("-topmost", True)
         self._toplevel.overrideredirect(True)
         self._grid_widgets()
-        x, y = self.master.winfo_pointerxy()
+        if self.__static is True:
+            x, y = self.master.winfo_rootx(), self.master.winfo_rooty()
+            w, h = self.master.winfo_width(), self.master.winfo_height()
+            x, y = x + w, y + h
+        else:
+            x, y = self.master.winfo_pointerxy()
         self._canvas.update()
         # Update the Geometry of the Toplevel to update its position and size
-        self._toplevel.geometry("{0}x{1}+{2}+{3}".format(self._canvas.winfo_width(), self._canvas.winfo_height(),
-                                                         x + 2, y + 2))
+        self._toplevel.geometry("{0}x{1}+{2}+{3}".format(
+            self._canvas.winfo_width(), self._canvas.winfo_height(),
+            x + self.__offset[0], y + self.__offset[1]))
 
     def cget(self, key):
         """
@@ -107,7 +134,8 @@ def cget(self, key):
         :type key: str
         :return: value of the option
 
-        To get the list of options for this widget, call the method :meth:`~Balloon.keys`.
+        To get the list of options for this widget, call the method
+        :meth:`~Tooltip.keys`.
         """
         if key == "headertext":
             return self.__headertext
@@ -119,21 +147,31 @@ def cget(self, key):
             return self._timeout
         elif key == "background":
             return self.__background
+        elif key == "offset":
+            return self.__offset
+        elif key == "showheader":
+            return self.__showheader
+        elif key == "static":
+            return self.__static
         else:
             return ttk.Frame.cget(self, key)
 
     def config(self, **kwargs):
         """
         Configure resources of the widget.
 
-        To get the list of options for this widget, call the method :meth:`~Balloon.keys`.
-        See :meth:`~Balloon.__init__` for a description of the widget specific option.
+        To get the list of options for this widget, call the method
+        :meth:`~Tooltip.keys`. See :meth:`~Tooltip.__init__` for a
+        description of the widget specific option.
         """
         self.__headertext = kwargs.pop("headertext", self.__headertext)
         self.__text = kwargs.pop("text", self.__text)
         self.__width = kwargs.pop("width", self.__width)
         self._timeout = kwargs.pop("timeout", self._timeout)
         self.__background = kwargs.pop("background", self.__background)
+        self.__offset = kwargs.pop("offset", self.__offset)
+        self.__showheader = kwargs.pop("showheader", self.__showheader)
+        self.__static = kwargs.pop("static", self.__static)
         if self._toplevel:
             self._on_leave(None)
             self.show()
@@ -143,5 +181,5 @@ def config(self, **kwargs):
 
     def keys(self):
         keys = ttk.Frame.keys(self)
-        keys.extend(["headertext", "text", "width", "timeout", "background"])
+        keys.extend(["headertext", "text", "width", "timeout", "background", "offset", "showheader", "static"])
         return keys

ttkwidgets/utilities.py

@@ -1,4 +1,8 @@
-# Copyright (c) RedFantom 2017
+"""
+Author: The ttkwidgets authors
+License: GNU GPLv3
+Source: The ttkwidgets repository
+"""
 import os
 from PIL import Image, ImageTk
 
@@ -9,3 +13,12 @@ def get_assets_directory():
 
 def open_icon(icon_name):
     return ImageTk.PhotoImage(Image.open(os.path.join(get_assets_directory(), icon_name)))
+
+
+def parse_geometry_string(string):
+    """Parse a Tkinter geometry string ('XxY+W+H') into a box tuple"""
+    e = string.split("x")
+    w = int(e[0])
+    e = e[1].split("+")
+    h, x, y = map(int, e)
+    return x, y, w, h