GtkTooltips

GTK+ Reference Manual
<<< Previous Page	Home	Up	Next Page >>>

Description

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.

Note: Tooltips can only be set on widgets which have their own X window. To check if a widget has its own window use 'GTK_WIDGET_NO_WINDOW (widget)'. 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 1. 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.");

Details

struct GtkTooltips

struct GtkTooltips;

Holds information about a group of tooltips. Fields should be changed using the functions provided, rather than directly accessing the struct's members.

struct GtkTooltipsData

struct GtkTooltipsData
{
  GtkTooltips *tooltips;
  GtkWidget *widget;
  gchar *tip_text;
  gchar *tip_private;
  GdkFont *font;
  gint width;
  GList *row;
};

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?)

gtk_tooltips_new ()

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.

gtk_tooltips_enable ()

void        gtk_tooltips_enable             (GtkTooltips *tooltips);

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

tooltips : a GtkTooltips.

gtk_tooltips_disable ()

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.

gtk_tooltips_set_delay ()

void        gtk_tooltips_set_delay          (GtkTooltips *tooltips,
                                             guint delay);

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).

gtk_tooltips_set_tip ()

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.

gtk_tooltips_set_colors ()

void        gtk_tooltips_set_colors         (GtkTooltips *tooltips,
                                             GdkColor *background,
                                             GdkColor *foreground);

This function is unimplemented because tooltip colors are instead determined by the theme.

`tooltips` :	a GtkTooltip
`background` :	a GdkColor that your tooltip text will be shown in.
`foreground` :	a GdkColor that your tooltip backgrounds will be shown in.

gtk_tooltips_data_get ()

GtkTooltipsData* gtk_tooltips_data_get      (GtkWidget *widget);

Retrieves any GtkTooltipsData previously associated with the given widget.

`widget` :	a GtkWidget.
Returns :	a GtkTooltipsData struct, or NULL if the widget has no tooltip.

gtk_tooltips_force_window ()

void        gtk_tooltips_force_window       (GtkTooltips *tooltips);

Soon as I play with this, I'll report what it does.

tooltips :