123 GtkTooltips

Add tips to your widgets

123.1 Overview

Tooltips are the messages that appear next to a widget when the mouse pointer is held over it for a short amount of time. They are especially helpful for adding more verbose descriptions of things such as buttons in a toolbar.

An individual tooltip belongs to a group of tooltips. A group is created with a call to gtk-tooltips-new. Every tooltip in the group can then be turned off with a call to gtk-tooltips-disable and enabled with gtk-tooltips-enable.

The length of time the user must keep the mouse over a widget before the tip is shown, can be altered with gtk-tooltips-set-delay. This is set on a 'per group of tooltips' basis.

To assign a tip to a particular <gtk-widget>, gtk-tooltips-set-tip is used.

Tooltips can only be set on widgets which have their own X window and receive enter and leave events. To check if a widget has its own window use gtk-widget-no-window. To add a tooltip to a widget that doesn't have its own window, place the widget inside a <gtk-event-box> and add a tooltip to that instead.

The default appearance of all tooltips in a program is determined by the current GTK+ theme that the user has selected.

Information about the tooltip (if any) associated with an arbitrary widget can be retrieved using gtk-tooltips-data-get.

     
        GtkWidget *load_button, *save_button, *hbox;
        GtkTooltips *button_bar_tips;
     
        button_bar_tips = gtk_tooltips_new ();
     
        /* Create the buttons and pack them into a GtkHBox */
        hbox = gtk_hbox_new (TRUE, 2);
     
        load_button = gtk_button_new_with_label ("Load a file");
        gtk_box_pack_start (GTK_BOX (hbox), load_button, TRUE, TRUE, 2);
        gtk_widget_show (load_button);
     
        save_button = gtk_button_new_with_label ("Save a file");
        gtk_box_pack_start (GTK_BOX (hbox), save_button, TRUE, TRUE, 2);
        gtk_widget_show (save_button);
        gtk_widget_show (hbox);
     
        /* Add the tips */
        gtk_tooltips_set_tip (GTK_TOOLTIPS (button_bar_tips), load_button,
     				 "Load a new document into this window",
     				 "Requests the filename of a document.
     				  This will then be loaded into the current
     				  window, replacing the contents of whatever
     				  is already loaded.");
        gtk_tooltips_set_tip (GTK_TOOLTIPS (button_bar_tips), save_button,
     				 "Saves the current document to a file",
     				 "If you have saved the document previously,
     				  then the new version will be saved over the
     				  old one. Otherwise, you will be prompted for
     				  a filename.");

123.2 Usage