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