9.3. The Tooltips Object

Tooltips are the little text strings that pop up when you leave your pointer over a button or other widget for a few seconds.

Widgets that do not receive events (widgets that do not have their own window) will not work with tooltips.

The first call you will use creates a new tooltip. You only need to do this once for a set of tooltips as the gtk.Tooltips object this function returns can be used to create multiple tooltips.

  tooltips = gtk.Tooltips()

Once you have created a new tooltip, and the widget you wish to use it on, simply use this call to set it:

  tooltips.set_tip(widget, tip_text, tip_private=None)

The object tooltips is the tooltip you've already created. The first argument (widget) is the widget you wish to have this tooltip pop up for; the second (tip_text), the text you wish it to display. The last argument (tip_private) is a text string that can be used as an identifier.

The tooltip.py example program modifies the arrow.py program to add a tooltip for each button. Figure 9.3, “Tooltips Example” illustrates the resulting display with the tooltip for the second arrow button displayed:

Figure 9.3. Tooltips Example

Tooltips Example

The source code for tooltip.py is:

    1	#!/usr/bin/env python
    3	# example tooltip.py
    5	import pygtk
    6	pygtk.require('2.0')
    7	import gtk
    9	# Create an Arrow widget with the specified parameters
   10	# and pack it into a button
   11	def create_arrow_button(arrow_type, shadow_type):
   12	    button = gtk.Button()
   13	    arrow = gtk.Arrow(arrow_type, shadow_type)
   14	    button.add(arrow)
   15	    button.show()
   16	    arrow.show()
   17	    return button
   19	class Tooltips:
   20	    def __init__(self):
   21	        # Create a new window
   22	        window = gtk.Window(gtk.WINDOW_TOPLEVEL)
   24	        window.set_title("Tooltips")
   26	        # It's a good idea to do this for all windows.
   27	        window.connect("destroy", lambda w: gtk.main_quit())
   29	        # Sets the border width of the window.
   30	        window.set_border_width(10)
   32	        # Create a box to hold the arrows/buttons
   33	        box = gtk.HBox(False, 0)
   34	        box.set_border_width(2)
   35	        window.add(box)
   37	        # create a tooltips object
   38	        self.tooltips = gtk.Tooltips()
   40	        # Pack and show all our widgets
   41	        box.show()
   43	        button = create_arrow_button(gtk.ARROW_UP, gtk.SHADOW_IN)
   44	        box.pack_start(button, False, False, 3)
   45	        self.tooltips.set_tip(button, "SHADOW_IN")
   47	        button = create_arrow_button(gtk.ARROW_DOWN, gtk.SHADOW_OUT)
   48	        box.pack_start(button, False, False, 3)
   49	        self.tooltips.set_tip(button, "SHADOW_OUT")
   51	        button = create_arrow_button(gtk.ARROW_LEFT, gtk.SHADOW_ETCHED_IN)
   52	        box.pack_start(button, False, False, 3)
   53	        self.tooltips.set_tip(button, "SHADOW_ETCHED_IN")
   55	        button = create_arrow_button(gtk.ARROW_RIGHT, gtk.SHADOW_ETCHED_OUT)
   56	        box.pack_start(button, False, False, 3)
   57	        self.tooltips.set_tip(button, "SHADOW_ETCHED_OUT")
   59	        window.show()
   61	def main():
   62	    gtk.main()
   63	    return 0
   65	if __name__ == "__main__":
   66	    tt = Tooltips()
   67	    main()

There are other methods that can be used with tooltips. I will just list them with a brief description of what they do.


Enable a disabled set of tooltips.


Disable an enabled set of tooltips.


Sets how many milliseconds you have to hold your pointer over the widget before the tooltip will pop up. The default is 500 milliseconds (half a second).

And that's all the methods associated with tooltips. More than you'll ever want to know :-)