9.3. The Tooltips Object

These 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 GtkTooltips object this function returns can be used to create multiple tooltips.
tooltips = GtkTooltips()

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)

The object tooltips is the tooltip you've already created. The first argument is the widget you wish to have this tooltip pop up for; the second, the text you wish it to display. The last argument is a text string that can be used as an identifier when using GtkTipsQuery to implement context sensitive help. For now, you can set it to None or leave it out.

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

Figure 9.3 Tooltips Example

The source code for tooltip.py is:
    1   #!/usr/bin/env python
    3   # example tooltip.py
    5   import gtk
    7   # Create an Arrow widget with the specified parameters
    8   # and pack it into a button
    9   def create_arrow_button(arrow_type, shadow_type):
   10       button = gtk.GtkButton();
   11       arrow = gtk.GtkArrow(arrow_type, shadow_type);
   12       button.add(arrow)
   13       button.show()
   14       arrow.show()
   15       return button
   17   class Tooltips:
   18       def __init__(self):
   19           # Create a new window
   20           window = gtk.GtkWindow(gtk.WINDOW_TOPLEVEL)
   22           window.set_title("Tooltips")
   24           # It's a good idea to do this for all windows.
   25           window.connect("destroy", gtk.mainquit)
   27           # Sets the border width of the window.
   28           window.set_border_width(10)
   30           # Create a box to hold the arrows/buttons
   31           box = gtk.GtkHBox(gtk.FALSE, 0)
   32           box.set_border_width(2)
   33           window.add(box)
   35           # create a tooltips object
   36           tooltips = gtk.GtkTooltips()
   38           # Pack and show all our widgets
   39           box.show()
   41           button = create_arrow_button(gtk.ARROW_UP, gtk.SHADOW_IN)
   42           box.pack_start(button, gtk.FALSE, gtk.FALSE, 3)
   43           tooltips.set_tip(button, "SHADOW_IN")
   45           button = create_arrow_button(gtk.ARROW_DOWN, gtk.SHADOW_OUT)
   46           box.pack_start(button, gtk.FALSE, gtk.FALSE, 3)
   47           tooltips.set_tip(button, "SHADOW_OUT")
   49           button = create_arrow_button(gtk.ARROW_LEFT, gtk.SHADOW_ETCHED_IN)
   50           box.pack_start(button, gtk.FALSE, gtk.FALSE, 3)
   51           tooltips.set_tip(button, "SHADOW_ETCHED_IN")
   53           button = create_arrow_button(gtk.ARROW_RIGHT, gtk.SHADOW_ETCHED_OUT)
   54           box.pack_start(button, gtk.FALSE, gtk.FALSE, 3)
   55           tooltips.set_tip(button, "SHADOW_ETCHED_OUT")
   57           window.show()
   59   def main():
   60       gtk.mainloop()
   61       return 0
   63   if __name__ == "__main__":
   64       Tooltips()
   65       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).
tooltips.set_colors(background, foreground)

Set the foreground and background color of the tooltips.

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