1 2@c %start of fragment 3 4@node GtkTooltips 5@chapter GtkTooltips 6Add tips to your widgets 7 8@section Overview 9Tooltips are the messages that appear next to a widget when the mouse pointer is 10held over it for a short amount of time. They are especially helpful for adding 11more verbose descriptions of things such as buttons in a toolbar. 12 13An individual tooltip belongs to a group of tooltips. A group is created with a 14call to @code{gtk-tooltips-new}. Every tooltip in the group can then be turned 15off with a call to @code{gtk-tooltips-disable} and enabled with 16@code{gtk-tooltips-enable}. 17 18The length of time the user must keep the mouse over a widget before the tip is 19shown, can be altered with @code{gtk-tooltips-set-delay}. This is set on a 'per 20group of tooltips' basis. 21 22To assign a tip to a particular @code{<gtk-widget>}, @code{gtk-tooltips-set-tip} 23is used. 24 25Tooltips can only be set on widgets which have their own X window and receive 26enter and leave events. To check if a widget has its own window use 27@code{gtk-widget-no-window}. To add a tooltip to a widget that doesn't have its 28own window, place the widget inside a @code{<gtk-event-box>} and add a tooltip 29to that instead. 30 31The default appearance of all tooltips in a program is determined by the current 32GTK+ theme that the user has selected. 33 34Information about the tooltip (if any) associated with an arbitrary widget can 35be retrieved using @code{gtk-tooltips-data-get}. 36 37 38 39@example 40 41 GtkWidget *load_button, *save_button, *hbox; 42 GtkTooltips *button_bar_tips; 43 44 button_bar_tips = gtk_tooltips_new (); 45 46 /* Create the buttons and pack them into a GtkHBox */ 47 hbox = gtk_hbox_new (TRUE, 2); 48 49 load_button = gtk_button_new_with_label ("Load a file"); 50 gtk_box_pack_start (GTK_BOX (hbox), load_button, TRUE, TRUE, 2); 51 gtk_widget_show (load_button); 52 53 save_button = gtk_button_new_with_label ("Save a file"); 54 gtk_box_pack_start (GTK_BOX (hbox), save_button, TRUE, TRUE, 2); 55 gtk_widget_show (save_button); 56 gtk_widget_show (hbox); 57 58 /* Add the tips */ 59 gtk_tooltips_set_tip (GTK_TOOLTIPS (button_bar_tips), load_button, 60 "Load a new document into this window", 61 "Requests the filename of a document. 62 This will then be loaded into the current 63 window, replacing the contents of whatever 64 is already loaded."); 65 gtk_tooltips_set_tip (GTK_TOOLTIPS (button_bar_tips), save_button, 66 "Saves the current document to a file", 67 "If you have saved the document previously, 68 then the new version will be saved over the 69 old one. Otherwise, you will be prompted for 70 a filename."); 71@end example 72 73@section Usage 74@include defuns-gtktooltips.xml.texi 75 76@c %end of fragment 77