1
2@c %start of fragment
3
4@node GtkAccelLabel
5@chapter GtkAccelLabel
6A label which displays an accelerator key on the right of the text
7
8@section Overview
9The @code{<gtk-accel-label>} widget is a subclass of @code{<gtk-label>} that
10also displays an accelerator key on the right of the label text, e.g. 'Ctl+S'.
11It is commonly used in menus to show the keyboard short-cuts for commands.
12
13The accelerator key to display is not set explicitly. Instead, the
14@code{<gtk-accel-label>} displays the accelerators which have been added to a
15particular widget. This widget is set by calling
16@code{gtk-accel-label-set-accel-widget}.
17
18For example, a @code{<gtk-menu-item>} widget may have an accelerator added to
19emit the "activate" signal when the 'Ctl+S' key combination is pressed. A
20@code{<gtk-accel-label>} is created and added to the @code{<gtk-menu-item>}, and
21@code{gtk-accel-label-set-accel-widget} is called with the
22@code{<gtk-menu-item>} as the second argument. The @code{<gtk-accel-label>} will
23now display 'Ctl+S' after its label.
24
25Note that creating a @code{<gtk-menu-item>} with
26@code{gtk-menu-item-new-with-label} (or one of the similar functions for
27@code{<gtk-check-menu-item>} and @code{<gtk-radio-menu-item>}) automatically
28adds a @code{<gtk-accel-label>} to the @code{<gtk-menu-item>} and calls
29@code{gtk-accel-label-set-accel-widget} to set it up for you.
30
31A @code{<gtk-accel-label>} will only display accelerators which have
32@samp{GTK_ACCEL_VISIBLE} set (see @code{<gtk-accel-flags>}). A
33@code{<gtk-accel-label>} can display multiple accelerators and even signal
34names, though it is almost always used to display just one accelerator key.
35
36@example
37
38  GtkWidget *save_item;
39  GtkAccelGroup *accel_group;
40
41  /* Create a GtkAccelGroup and add it to the window. */
42  accel_group = gtk_accel_group_new ();
43  gtk_window_add_accel_group (GTK_WINDOW (window), accel_group);
44
45  /* Create the menu item using the convenience function. */
46  save_item = gtk_menu_item_new_with_label ("Save");
47  gtk_widget_show (save_item);
48  gtk_container_add (GTK_CONTAINER (menu), save_item);
49
50  /* Now add the accelerator to the GtkMenuItem. Note that since we called
51     gtk_menu_item_new_with_label() to create the GtkMenuItem the
52     GtkAccelLabel is automatically set up to display the GtkMenuItem
53     accelerators. We just need to make sure we use GTK_ACCEL_VISIBLE here. */
54  gtk_widget_add_accelerator (save_item, "activate", accel_group,
55                              GDK_s, GDK_CONTROL_MASK, GTK_ACCEL_VISIBLE);
56@end example
57
58@section Usage
59@include defuns-gtkaccellabel.xml.texi
60
61@c %end of fragment
62