Next: , Previous: GtkSizeGroup, Up: Top

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

— Class: <gtk-tooltips>

Derives from <gtk-object>.

This class defines no direct slots.

— Function: gtk-tooltips-new ⇒  (ret <gtk-tooltips>)

Creates an empty group of tooltips. This function initialises a <gtk-tooltips> structure. Without at least one such structure, you can not add tips to your application.

a new <gtk-tooltips> group for you to use.
— Function: gtk-tooltips-enable (self <gtk-tooltips>)
— Method: enable

Allows the user to see your tooltips as they navigate your application.

a <gtk-tooltips>.
— Function: gtk-tooltips-disable (self <gtk-tooltips>)
— Method: disable

Causes all tooltips in tooltips to become inactive. Any widgets that have tips associated with that group will no longer display their tips until they are enabled again with gtk-tooltips-enable.

a <gtk-tooltips>.
— Function: gtk-tooltips-set-tip (self <gtk-tooltips>) (widget <gtk-widget>) (tip_text mchars) (tip_private mchars)
— Method: set-tip

Adds a tooltip containing the message tip-text to the specified <gtk-widget>.

a <gtk-tooltips>.
the <gtk-widget> you wish to associate the tip with.
a string containing the tip itself.
a string of any further information that may be useful if the user gets stuck.
— Function: gtk-tooltips-force-window (self <gtk-tooltips>)
— Method: force-window

Ensures that the window used for displaying the given tooltips is created.

Applications should never have to call this function, since GTK+ takes care of this.

a <gtk-tool-tips>