jpayne@68: """Tools for displaying tool-tips.
jpayne@68: 
jpayne@68: This includes:
jpayne@68:  * an abstract base-class for different kinds of tooltips
jpayne@68:  * a simple text-only Tooltip class
jpayne@68: """
jpayne@68: from tkinter import *
jpayne@68: 
jpayne@68: 
jpayne@68: class TooltipBase(object):
jpayne@68:     """abstract base class for tooltips"""
jpayne@68: 
jpayne@68:     def __init__(self, anchor_widget):
jpayne@68:         """Create a tooltip.
jpayne@68: 
jpayne@68:         anchor_widget: the widget next to which the tooltip will be shown
jpayne@68: 
jpayne@68:         Note that a widget will only be shown when showtip() is called.
jpayne@68:         """
jpayne@68:         self.anchor_widget = anchor_widget
jpayne@68:         self.tipwindow = None
jpayne@68: 
jpayne@68:     def __del__(self):
jpayne@68:         self.hidetip()
jpayne@68: 
jpayne@68:     def showtip(self):
jpayne@68:         """display the tooltip"""
jpayne@68:         if self.tipwindow:
jpayne@68:             return
jpayne@68:         self.tipwindow = tw = Toplevel(self.anchor_widget)
jpayne@68:         # show no border on the top level window
jpayne@68:         tw.wm_overrideredirect(1)
jpayne@68:         try:
jpayne@68:             # This command is only needed and available on Tk >= 8.4.0 for OSX.
jpayne@68:             # Without it, call tips intrude on the typing process by grabbing
jpayne@68:             # the focus.
jpayne@68:             tw.tk.call("::tk::unsupported::MacWindowStyle", "style", tw._w,
jpayne@68:                        "help", "noActivates")
jpayne@68:         except TclError:
jpayne@68:             pass
jpayne@68: 
jpayne@68:         self.position_window()
jpayne@68:         self.showcontents()
jpayne@68:         self.tipwindow.update_idletasks()  # Needed on MacOS -- see #34275.
jpayne@68:         self.tipwindow.lift()  # work around bug in Tk 8.5.18+ (issue #24570)
jpayne@68: 
jpayne@68:     def position_window(self):
jpayne@68:         """(re)-set the tooltip's screen position"""
jpayne@68:         x, y = self.get_position()
jpayne@68:         root_x = self.anchor_widget.winfo_rootx() + x
jpayne@68:         root_y = self.anchor_widget.winfo_rooty() + y
jpayne@68:         self.tipwindow.wm_geometry("+%d+%d" % (root_x, root_y))
jpayne@68: 
jpayne@68:     def get_position(self):
jpayne@68:         """choose a screen position for the tooltip"""
jpayne@68:         # The tip window must be completely outside the anchor widget;
jpayne@68:         # otherwise when the mouse enters the tip window we get
jpayne@68:         # a leave event and it disappears, and then we get an enter
jpayne@68:         # event and it reappears, and so on forever :-(
jpayne@68:         #
jpayne@68:         # Note: This is a simplistic implementation; sub-classes will likely
jpayne@68:         # want to override this.
jpayne@68:         return 20, self.anchor_widget.winfo_height() + 1
jpayne@68: 
jpayne@68:     def showcontents(self):
jpayne@68:         """content display hook for sub-classes"""
jpayne@68:         # See ToolTip for an example
jpayne@68:         raise NotImplementedError
jpayne@68: 
jpayne@68:     def hidetip(self):
jpayne@68:         """hide the tooltip"""
jpayne@68:         # Note: This is called by __del__, so careful when overriding/extending
jpayne@68:         tw = self.tipwindow
jpayne@68:         self.tipwindow = None
jpayne@68:         if tw:
jpayne@68:             try:
jpayne@68:                 tw.destroy()
jpayne@68:             except TclError:  # pragma: no cover
jpayne@68:                 pass
jpayne@68: 
jpayne@68: 
jpayne@68: class OnHoverTooltipBase(TooltipBase):
jpayne@68:     """abstract base class for tooltips, with delayed on-hover display"""
jpayne@68: 
jpayne@68:     def __init__(self, anchor_widget, hover_delay=1000):
jpayne@68:         """Create a tooltip with a mouse hover delay.
jpayne@68: 
jpayne@68:         anchor_widget: the widget next to which the tooltip will be shown
jpayne@68:         hover_delay: time to delay before showing the tooltip, in milliseconds
jpayne@68: 
jpayne@68:         Note that a widget will only be shown when showtip() is called,
jpayne@68:         e.g. after hovering over the anchor widget with the mouse for enough
jpayne@68:         time.
jpayne@68:         """
jpayne@68:         super(OnHoverTooltipBase, self).__init__(anchor_widget)
jpayne@68:         self.hover_delay = hover_delay
jpayne@68: 
jpayne@68:         self._after_id = None
jpayne@68:         self._id1 = self.anchor_widget.bind("<Enter>", self._show_event)
jpayne@68:         self._id2 = self.anchor_widget.bind("<Leave>", self._hide_event)
jpayne@68:         self._id3 = self.anchor_widget.bind("<Button>", self._hide_event)
jpayne@68: 
jpayne@68:     def __del__(self):
jpayne@68:         try:
jpayne@68:             self.anchor_widget.unbind("<Enter>", self._id1)
jpayne@68:             self.anchor_widget.unbind("<Leave>", self._id2)  # pragma: no cover
jpayne@68:             self.anchor_widget.unbind("<Button>", self._id3) # pragma: no cover
jpayne@68:         except TclError:
jpayne@68:             pass
jpayne@68:         super(OnHoverTooltipBase, self).__del__()
jpayne@68: 
jpayne@68:     def _show_event(self, event=None):
jpayne@68:         """event handler to display the tooltip"""
jpayne@68:         if self.hover_delay:
jpayne@68:             self.schedule()
jpayne@68:         else:
jpayne@68:             self.showtip()
jpayne@68: 
jpayne@68:     def _hide_event(self, event=None):
jpayne@68:         """event handler to hide the tooltip"""
jpayne@68:         self.hidetip()
jpayne@68: 
jpayne@68:     def schedule(self):
jpayne@68:         """schedule the future display of the tooltip"""
jpayne@68:         self.unschedule()
jpayne@68:         self._after_id = self.anchor_widget.after(self.hover_delay,
jpayne@68:                                                   self.showtip)
jpayne@68: 
jpayne@68:     def unschedule(self):
jpayne@68:         """cancel the future display of the tooltip"""
jpayne@68:         after_id = self._after_id
jpayne@68:         self._after_id = None
jpayne@68:         if after_id:
jpayne@68:             self.anchor_widget.after_cancel(after_id)
jpayne@68: 
jpayne@68:     def hidetip(self):
jpayne@68:         """hide the tooltip"""
jpayne@68:         try:
jpayne@68:             self.unschedule()
jpayne@68:         except TclError:  # pragma: no cover
jpayne@68:             pass
jpayne@68:         super(OnHoverTooltipBase, self).hidetip()
jpayne@68: 
jpayne@68: 
jpayne@68: class Hovertip(OnHoverTooltipBase):
jpayne@68:     "A tooltip that pops up when a mouse hovers over an anchor widget."
jpayne@68:     def __init__(self, anchor_widget, text, hover_delay=1000):
jpayne@68:         """Create a text tooltip with a mouse hover delay.
jpayne@68: 
jpayne@68:         anchor_widget: the widget next to which the tooltip will be shown
jpayne@68:         hover_delay: time to delay before showing the tooltip, in milliseconds
jpayne@68: 
jpayne@68:         Note that a widget will only be shown when showtip() is called,
jpayne@68:         e.g. after hovering over the anchor widget with the mouse for enough
jpayne@68:         time.
jpayne@68:         """
jpayne@68:         super(Hovertip, self).__init__(anchor_widget, hover_delay=hover_delay)
jpayne@68:         self.text = text
jpayne@68: 
jpayne@68:     def showcontents(self):
jpayne@68:         label = Label(self.tipwindow, text=self.text, justify=LEFT,
jpayne@68:                       background="#ffffe0", relief=SOLID, borderwidth=1)
jpayne@68:         label.pack()
jpayne@68: 
jpayne@68: 
jpayne@68: def _tooltip(parent):  # htest #
jpayne@68:     top = Toplevel(parent)
jpayne@68:     top.title("Test tooltip")
jpayne@68:     x, y = map(int, parent.geometry().split('+')[1:])
jpayne@68:     top.geometry("+%d+%d" % (x, y + 150))
jpayne@68:     label = Label(top, text="Place your mouse over buttons")
jpayne@68:     label.pack()
jpayne@68:     button1 = Button(top, text="Button 1 -- 1/2 second hover delay")
jpayne@68:     button1.pack()
jpayne@68:     Hovertip(button1, "This is tooltip text for button1.", hover_delay=500)
jpayne@68:     button2 = Button(top, text="Button 2 -- no hover delay")
jpayne@68:     button2.pack()
jpayne@68:     Hovertip(button2, "This is tooltip\ntext for button2.", hover_delay=None)
jpayne@68: 
jpayne@68: 
jpayne@68: if __name__ == '__main__':
jpayne@68:     from unittest import main
jpayne@68:     main('idlelib.idle_test.test_tooltip', verbosity=2, exit=False)
jpayne@68: 
jpayne@68:     from idlelib.idle_test.htest import run
jpayne@68:     run(_tooltip)