manpagez: man pages & more
html files: gtk2
Home | html | info | man

GtkTooltips

GtkTooltips — Add tips to your widgets

Types and Values

Object Hierarchy

    GObject
    ╰── GInitiallyUnowned
        ╰── GtkObject
            ╰── GtkTooltips

Includes

#include <gtk/gtk.h>

Description

GtkTooltips has been deprecated in GTK+ 2.12, in favor of the new GtkTooltip API.

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 51. Adding tooltips to buttons.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
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.");


Functions

gtk_tooltips_new ()

GtkTooltips *
gtk_tooltips_new (void);

gtk_tooltips_new has been deprecated since version 2.12 and should not be used in newly-written code.

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

gtk_tooltips_enable has been deprecated since version 2.12 and should not be used in newly-written code.

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

Parameters

tooltips

a GtkTooltips.

 

gtk_tooltips_disable ()

void
gtk_tooltips_disable (GtkTooltips *tooltips);

gtk_tooltips_disable has been deprecated since version 2.12 and should not be used in newly-written code.

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

Parameters

tooltips

a GtkTooltips.

 

gtk_tooltips_set_delay ()

void
gtk_tooltips_set_delay (GtkTooltips *tooltips,
                        guint delay);

gtk_tooltips_set_delay has been deprecated since version 2.12 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.

Parameters

tooltips

a GtkTooltips.

 

delay

an integer value representing milliseconds.

 

gtk_tooltips_set_tip ()

void
gtk_tooltips_set_tip (GtkTooltips *tooltips,
                      GtkWidget *widget,
                      const gchar *tip_text,
                      const gchar *tip_private);

gtk_tooltips_set_tip has been deprecated since version 2.12 and should not be used in newly-written code.

Adds a tooltip containing the message tip_text to the specified GtkWidget.

Parameters

tooltips

a GtkTooltips.

 

widget

the GtkWidget you wish to associate the tip with.

 

tip_text

a string containing the tip itself.

[allow-none]

tip_private

a string of any further information that may be useful if the user gets stuck.

[allow-none]

gtk_tooltips_data_get ()

GtkTooltipsData *
gtk_tooltips_data_get (GtkWidget *widget);

gtk_tooltips_data_get has been deprecated since version 2.12 and should not be used in newly-written code.

Retrieves any GtkTooltipsData previously associated with the given widget.

Parameters

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

gtk_tooltips_force_window has been deprecated since version 2.12 and should not be used in newly-written code.

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.

Parameters

tooltips

a GtkToolTips

 

gtk_tooltips_get_info_from_tip_window ()

gboolean
gtk_tooltips_get_info_from_tip_window (GtkWindow *tip_window,
                                       GtkTooltips **tooltips,
                                       GtkWidget **current_widget);

gtk_tooltips_get_info_from_tip_window has been deprecated since version 2.12 and should not be used in newly-written code.

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.

Parameters

tip_window

a GtkWindow

 

tooltips

the return location for the tooltips which are displayed in tip_window , or NULL

 

current_widget

the return location for the widget whose tooltips are displayed, or NULL

 

Returns

TRUE if tip_window is displaying tooltips, otherwise FALSE.

Since: 2.4

Types and Values

struct GtkTooltips

struct GtkTooltips;

GtkTooltips is deprecated and should not be used in newly-written code.

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;
};

GtkTooltipsData has been deprecated since version 2.12 and should not be used in newly-written code.

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

See Also

GtkToolbar

Create groups of widgets with their own tooltips.

GtkTipsQuery

Query tooltips to create context-sensitive help.

© manpagez.com 2000-2024
Individual documents may contain additional copyright information.