3.8 Tooltips and Keyboard Control

This section covers tooltips and keyboard operation, two GTK+ features that can make your application more appealing to novices and experts. Although they are not necessary, they can have a subtle effect on your users (just don't expect the users to acknowledge it).

3.8.1 Tooltips

A tooltip is a short description of a widget's purpose that appears when the mouse pointer lingers over the widget for a short period of time. If used properly, tooltips can significantly reduce the amount of time that the user needs to become familiar with an application. A tooltip's exact appearance depends on the current GTK+ theme, but it is normally a small, borderless window with text on a light yellow background.

To outfit a group of widgets with tooltips, create one GtkTooltips ( GTK_TYPE_TOOLTIPS ) object for the group and call this for each widget in the group:

 gtk_tooltips_set_tip(  tip  ,  widget  ,  text  ,  ext  )

The arguments are:

tip ( GtkToolTips * ): The tooltip object for the group.
widget ( GtkWidget * ): The widget that text ( next ) describes.
text ( const gchar * ): A string containing the tooltip text.
ext ( const gchar * ): A more extensive description, meant for older help systems. Use an empty string here.

You should create one tooltip object for each group of widgets because of the way tooltips behave; the user must initially wait for a certain amount of time for the first tooltip to appear, but when the user drags the pointer over to some other widgets in the group afterward, the tooltips for those widgets immediately appear. After the user moves the mouse away from the widget group for a certain amount of time, the tooltips reset to their original delay times.

Note	You can attach a tooltip only to a widget that receives events. Therefore, you can't put a tooltip on something like a label, but that wouldn't make much sense anyhow.

Here are the declarations and startup for a tooltip demonstration program:

 /* -*-coding: utf-8;-*- */ /* tooltips.c -- demonstrate tooltips */ #include <gtk/gtk.h>   << standard event handlers >> int main(int argc, char **argv) {   GtkWindow *window;   GtkButton *cut, *copy, *paste, *other_button;   GtkVButtonBox *box;   GtkTooltips *tips, *other_tips;   /* start GTK+, create window, bind signal handlers */   gtk_init(&argc, &argv);   window = g_object_new(GTK_TYPE_WINDOW,                         "title", "Tooltips Demonstration",                         "default-width", 300,                         "default-height", 100,                         "border-width", 12,                         NULL);   << attach standard signal handlers to window >>

You need some widgets for tooltips, so here are three buttons with stock labels:

 /* create three buttons using stock labels and images */   cut = g_object_new(GTK_TYPE_BUTTON,                      "use-stock", TRUE,                      "label", GTK_STOCK_CUT,                      NULL);   copy = g_object_new(GTK_TYPE_BUTTON,                      "use-stock", TRUE,                      "label", GTK_STOCK_COPY,                      NULL);   paste = g_object_new(GTK_TYPE_BUTTON,                      "use-stock", TRUE,                      "label", GTK_STOCK_PASTE,                      NULL);   /* pack buttons into VButtonBox */   box = g_object_new(GTK_TYPE_VBUTTON_BOX, NULL);   gtk_box_pack_end_defaults(GTK_BOX(box), GTK_WIDGET(cut));   gtk_box_pack_end_defaults(GTK_BOX(box), GTK_WIDGET(copy));   gtk_box_pack_end_defaults(GTK_BOX(box), GTK_WIDGET(paste));

Now you're ready to attach the tooltips to the buttons. Notice that there is only one GtkTooltips object for all three buttons.

 /* create tooltips object, assign to the buttons above */   tips = g_object_new(GTK_TYPE_TOOLTIPS, NULL);   gtk_tooltips_set_tip(tips, GTK_WIDGET(cut),      "Cut selection and place it in clipboard", "");   gtk_tooltips_set_tip(tips, GTK_WIDGET(copy),      "Copy selection to the clipboard", "");   gtk_tooltips_set_tip(tips, GTK_WIDGET(paste),      "Paste clipboard into current location", "");

This program also creates a fourth button with its own tooltip object:

 /* create another button */   other_button = g_object_new(GTK_TYPE_BUTTON,                               "label", "_Other group",                               "use-underline", TRUE,                               NULL);   gtk_box_pack_end_defaults(GTK_BOX(box), GTK_WIDGET(other_button));   /* use a different tooltips object for this button */   other_tips = g_object_new(GTK_TYPE_TOOLTIPS, NULL);   gtk_tooltips_set_tip(other_tips, GTK_WIDGET(other_button),      "This button uses a different Tooltips object", "");   /* pack all boxes, show everything, start GTK+ loop */   gtk_container_add(GTK_CONTAINER(window), GTK_WIDGET(box));   gtk_widget_show_all(GTK_WIDGET(window));   gtk_main();   return 0; }

Figure 3.14 shows a tooltip. When you run this program, see if you can tell the difference between the two tooltip objects. Hover over the Cut button until its tooltip appears; then move the mouse down across the other buttons. Tooltips will immediately pop up when the pointer reaches the Copy and Paste buttons. However, the last button has its own tooltip object and shows nothing until you wait for a while.

Figure 3.14: Tooltips.

There are functions for disabling and reenabling a GtkTooltips object:

 gtk_tooltips_disable(  tooltips_object  ) gtk_tooltips_enable(  tooltips_object  )

You can use this in conjunction with a control panel check button so that the user can disable tooltips.

3.8.2 Keyboard Operation

Functional keyboard operation is important for a comfortable interface ” not just for accessibility, but also for users who prefer keyboard operations for speed. GTK+ has two keyboard operation facilities:

Mnemonics operate dialog boxes and menu items. You can discern them with an underlined character in a widget; when you press the character (possibly in conjunction with the ALT key), GTK+ activates the widget (in the case of buttons or menu items) or focuses on the widget (for anything else). The characters need only to be unique within the dialog or menu.
Accelerators attach arbitrary actions to keystrokes. They are usually valid for the entire application and consist of a regular key and a modifier such as CONTROL, SHIFT, or ALT. Typical accelerators call menus , bring up dialogs, or have some other direct effect.

Mnemonics

You should bind a keystroke to every data entry widget in a window. If the widget has its own label (such as a button), do the following to bind the keystroke:

Place an underscore in front of the mnemonic character in the widget's label property.
Set the widget's use-underline property to TRUE .

However, if the widget requires its own GtkLabel object, perform these steps for that label object and, in addition, set the label's mnemonic-widget property to the target widget.

There are examples throughout this book; Section 3.6 includes a program with several mnemonic labels.

Accelerators

GtkAccelGroup ( GTK_TYPE_ACCEL_GROUP ) objects define global key combinations. This method uses signals; when you press a valid key combination, GTK+ emits a signal with a given object. Therefore, to install an accelerator, you must have an object and handler for the signal.

You really need to know only that GtkAccelGroup objects often represent menu items; as you will see in Section 4.3.1, the system typically makes the key binding for you. However, the following functions are at your disposal if you need to do the work by hand:

void gtk_window_add_accel_group( window , group )

Adds a GtkAccelGroup object group to the GtkWindow window , making the key combinations in the group valid for the window.
void gtk_window_remove_accel_group( window , group )

Removes the binding group from window .
GSList *gtk_accel_groups_from_object( object )

Returns a list containing all accelerator groups in object (this object is normally a window).
void *gtk_widget_add_accelerator( widget , signal , group , key , modifiers , options )

Adds a new key binding along with a signal to group . When you press the key combination defined by key and modifiers , GTK+ emits signal with widget ( signal is the signal's string identifier). You may use an ASCII character such as a for key as well as one of the special keys listed at the end of this section.
- modifier is a bitwise OR of GDK_SHIFT_MASK , GDK_CONTROL_MASK , and/or GDK_MOD1_MASK (this last one is for the ALT key).
- options is a bitwise OR of GTK_ACCEL_VISIBLE (show it in the accelerator label) and GTK_ACCEL_LOCKED (if you don't want to be able to remove the binding from the group later).
gboolean gtk_accelerator_valid( key , modifiers )

Returns TRUE if key and modifiers form a valid key combination.

Some of the many special non-ASCII keys are listed in the following table (look in gdk/gdkkeysyms.h for a full-blown list). KP indicates the numeric keypad.

GDK_BackSpace	GDK_End	GDK_KP_Delete	GDK_KP_8
GDK_Tab	GDK_Print	GDK_KP_Equal	GDK_KP_9
GDK_Return	GDK_Insert	GDK_KP_Multiply	GDK_F1
GDK_Pause	GDK_Break	GDK_KP_Add	GDK_F2
GDK_Scroll_Lock	GDK_Num_Lock	GDK_KP_Subtract	GDK_F3
GDK_Sys_Req	GDK_KP_Enter	GDK_KP_Decimal	GDK_F4
GDK_Escape	GDK_KP_Home	GDK_KP_Divide	GDK_F5
GDK_Delete	GDK_KP_Left	GDK_KP_0	GDK_F6
GDK_Home	GDK_KP_Up	GDK_KP_1	GDK_F7
GDK_Left	GDK_KP_Right	GDK_KP_2	GDK_F8
GDK_Up	GDK_KP_Down	GDK_KP_3	GDK_F9
GDK_Right	GDK_KP_Page_Up	GDK_KP_4	GDK_F10
GDK_Down	GDK_KP_Page_Down	GDK_KP_5	GDK_F11
GDK_Page_Up	GDK_KP_End	GDK_KP_6	GDK_F12
GDK_Page_Down	GDK_KP_Insert	GDK_KP_7