Next: , Previous: GtkAssistant, Up: Top

9 GtkAccelLabel

A label which displays an accelerator key on the right of the text

9.1 Overview

The <gtk-accel-label> widget is a subclass of <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 <gtk-accel-label> displays the accelerators which have been added to a particular widget. This widget is set by calling gtk-accel-label-set-accel-widget.

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

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

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

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

9.2 Usage

— Class: <gtk-accel-label>

Derives from <gtk-label>.

This class defines the following slots:

The closure to be monitored for accelerator changes
The widget to be monitored for accelerator changes
— Function: gtk-accel-label-new (string mchars) ⇒  (ret <gtk-widget>)

Creates a new <gtk-accel-label>.

the label string. Must be non-‘#f’.
a new <gtk-accel-label>.
— Function: gtk-accel-label-set-accel-closure (self <gtk-accel-label>) (accel_closure <gclosure>)
— Method: set-accel-closure

Sets the closure to be monitored by this accelerator label. The closure must be connected to an accelerator group; see gtk-accel-group-connect.

a <gtk-accel-label>
the closure to monitor for accelerator changes.
— Function: gtk-accel-label-get-accel-widget (self <gtk-accel-label>) ⇒  (ret <gtk-widget>)
— Method: get-accel-widget

Fetches the widget monitored by this accelerator label. See gtk-accel-label-set-accel-widget.

a <gtk-accel-label>
the object monitored by the accelerator label, or ‘#f’.
— Function: gtk-accel-label-set-accel-widget (self <gtk-accel-label>) (accel_widget <gtk-widget>)
— Method: set-accel-widget

Sets the widget to be monitored by this accelerator label.

a <gtk-accel-label>
the widget to be monitored.
— Function: gtk-accel-label-get-accel-width (self <gtk-accel-label>) ⇒  (ret unsigned-int)
— Method: get-accel-width

Returns the width needed to display the accelerator key(s). This is used by menus to align all of the <gtk-menu-item> widgets, and shouldn't be needed by applications.

a <gtk-accel-label>.
the width needed to display the accelerator key(s).
— Function: gtk-accel-label-refetch (self <gtk-accel-label>) ⇒  (ret bool)
— Method: refetch

Recreates the string representing the accelerator keys. This should not be needed since the string is automatically updated whenever accelerators are added or removed from the associated widget.

a <gtk-accel-label>.
always returns ‘#f’.