|  |  |  | GTK+ Reference Manual |  | 
|---|
| GtkTooltipsGtkTooltips — Add tips to your widgets | 
#include <gtk/gtk.h>
            GtkTooltips;
            GtkTooltipsData;
GtkTooltips* gtk_tooltips_new               (void);
void        gtk_tooltips_enable             (GtkTooltips *tooltips);
void        gtk_tooltips_disable            (GtkTooltips *tooltips);
void        gtk_tooltips_set_delay          (GtkTooltips *tooltips,
                                             guint delay);
void        gtk_tooltips_set_tip            (GtkTooltips *tooltips,
                                             GtkWidget *widget,
                                             const gchar *tip_text,
                                             const gchar *tip_private);
GtkTooltipsData* gtk_tooltips_data_get      (GtkWidget *widget);
void        gtk_tooltips_force_window       (GtkTooltips *tooltips);
gboolean    gtk_tooltips_get_info_from_tip_window
                                            (GtkWindow *tip_window,
                                             GtkTooltips **tooltips,
                                             GtkWidget **current_widget);
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 GtkWidget, 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 GtkEventBox 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().
Example 2. Adding tooltips to buttons.
   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."); 
typedef struct _GtkTooltips GtkTooltips;
Holds information about a group of tooltips. Fields should be changed using the functions provided, rather than directly accessing the struct's members.
typedef struct {
  GtkTooltips *tooltips;
  GtkWidget *widget;
  gchar *tip_text;
  gchar *tip_private;
} GtkTooltipsData;
tooltips is the GtkTooltips group that this tooltip belongs to. widget is the GtkWidget that this tooltip data is associated with. tip_text is a string containing the tooltip message itself.
tip_private is a string that is not shown as the default tooltip. Instead, this message may be more informative and go towards forming a context-sensitive help system for your application. (FIXME: how to actually "switch on" private tips?)
GtkTooltips* gtk_tooltips_new (void);
Creates an empty group of tooltips. This function initialises a GtkTooltips structure. Without at least one such structure, you can not add tips to your application.
| Returns : | a new GtkTooltips group for you to use. | 
void gtk_tooltips_enable (GtkTooltips *tooltips);
Allows the user to see your tooltips as they navigate your application.
| tooltips: | a GtkTooltips. | 
void gtk_tooltips_disable (GtkTooltips *tooltips);
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().
| tooltips: | a GtkTooltips. | 
void gtk_tooltips_set_delay (GtkTooltips *tooltips, guint delay);
gtk_tooltips_set_delay is deprecated and should not be used in newly-written code.
Sets the time between the user moving the mouse over a widget and the widget's tooltip appearing.
| tooltips: | a GtkTooltips. | 
| delay: | an integer value representing seconds (FIXME: double-check this). | 
void gtk_tooltips_set_tip (GtkTooltips *tooltips, GtkWidget *widget, const gchar *tip_text, const gchar *tip_private);
Adds a tooltip containing the message tip_text to the specified GtkWidget. 
| tooltips: | a GtkTooltips. | 
| widget: | the GtkWidget you wish to associate the tip with. | 
| tip_text: | a string containing the tip itself. | 
| tip_private: | a string of any further information that may be useful if the user gets stuck. | 
GtkTooltipsData* gtk_tooltips_data_get (GtkWidget *widget);
Retrieves any GtkTooltipsData previously associated with the given widget.
| widget: | a GtkWidget. | 
| Returns : | a GtkTooltipsData struct, or NULLif the widget has no tooltip. | 
void gtk_tooltips_force_window (GtkTooltips *tooltips);
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.
| tooltips: | a GtkToolTips | 
gboolean gtk_tooltips_get_info_from_tip_window (GtkWindow *tip_window, GtkTooltips **tooltips, GtkWidget **current_widget);
Determines the tooltips and the widget they belong to from the window in which they are displayed.
This function is mostly intended for use by accessibility technologies; applications should have little use for it.
| tip_window: | a GtkWindow | 
| tooltips: | the return location for the tooltips which are displayed 
   in tip_window, orNULL | 
| current_widget: | the return location for the widget whose tooltips 
   are displayed, or NULL | 
| Returns : | TRUEiftip_windowis displaying tooltips, otherwiseFALSE. | 
Since 2.4
| GtkToolbar | Create groups of widgets with their own tooltips. | 
| GtkTipsQuery | Query tooltips to create context-sensitive help. | 
| << GtkSizeGroup | GtkViewport >> |