
@c %start of fragment

@node GtkAccelLabel
@chapter GtkAccelLabel
A label which displays an accelerator key on the right of the text

@section Overview
The @code{<gtk-accel-label>} widget is a subclass of @code{<gtk-label>} that
also displays an accelerator key on the right of the label text, e.g. 'Ctl+S'.
It is commonly used in menus to show the keyboard short-cuts for commands.

The accelerator key to display is not set explicitly. Instead, the
@code{<gtk-accel-label>} displays the accelerators which have been added to a
particular widget. This widget is set by calling
@code{gtk-accel-label-set-accel-widget}.

For example, a @code{<gtk-menu-item>} widget may have an accelerator added to
emit the "activate" signal when the 'Ctl+S' key combination is pressed. A
@code{<gtk-accel-label>} is created and added to the @code{<gtk-menu-item>}, and
@code{gtk-accel-label-set-accel-widget} is called with the
@code{<gtk-menu-item>} as the second argument. The @code{<gtk-accel-label>} will
now display 'Ctl+S' after its label.

Note that creating a @code{<gtk-menu-item>} with
@code{gtk-menu-item-new-with-label} (or one of the similar functions for
@code{<gtk-check-menu-item>} and @code{<gtk-radio-menu-item>}) automatically
adds a @code{<gtk-accel-label>} to the @code{<gtk-menu-item>} and calls
@code{gtk-accel-label-set-accel-widget} to set it up for you.

A @code{<gtk-accel-label>} will only display accelerators which have
@samp{GTK_ACCEL_VISIBLE} set (see @code{<gtk-accel-flags>}). A
@code{<gtk-accel-label>} can display multiple accelerators and even signal
names, though it is almost always used to display just one accelerator key.

@example 

  GtkWidget *save_item;
  GtkAccelGroup *accel_group;

  /* Create a GtkAccelGroup and add it to the window. */
  accel_group = gtk_accel_group_new ();
  gtk_window_add_accel_group (GTK_WINDOW (window), accel_group);

  /* Create the menu item using the convenience function. */
  save_item = gtk_menu_item_new_with_label ("Save");
  gtk_widget_show (save_item);
  gtk_container_add (GTK_CONTAINER (menu), save_item);

  /* Now add the accelerator to the GtkMenuItem. Note that since we called
     gtk_menu_item_new_with_label() to create the GtkMenuItem the
     GtkAccelLabel is automatically set up to display the GtkMenuItem
     accelerators. We just need to make sure we use GTK_ACCEL_VISIBLE here. */
  gtk_widget_add_accelerator (save_item, "activate", accel_group,
                              GDK_s, GDK_CONTROL_MASK, GTK_ACCEL_VISIBLE);
@end example

@section Usage
@include defuns-gtkaccellabel.xml.texi

@c %end of fragment
