Gtk.AccelLabel

Gtk.AccelLabel — A label which displays an accelerator key on the right of the text

Object Hierarchy:

    GObject
    ╰── GInitiallyUnowned
        ╰── Gtk.Widget
            ╰── Gtk.Misc
                ╰── Gtk.Label
                    ╰── Gtk.AccelLabel

See also:

Gtk.AccelGroup

Functions:

• new (string:str) -> Gtk.Widget
• set_accel_closure (self, accel_closure:GObject.Closure)
• get_accel_widget (self) -> Gtk.Widget
• set_accel_widget (self, accel_widget:Gtk.Widget)
• get_accel_width (self) -> int
• set_accel (self, accelerator_key:int, accelerator_mods:Gdk.ModifierType)
• get_accel (self) -> accelerator_key:int, accelerator_mods:Gdk.ModifierType
• refetch (self) -> bool

Description:

The Gtk.AccelLabel widget is a subclass of GtkLabel 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.AccelLabel displays the accelerators which have been added to a particular widget. This widget is set by calling Gtk.AccelLabel::set_accel_widget().

For example, a Gtk.MenuItem widget may have an accelerator added to emit the activate signal when the Ctl+S key combination is pressed.

A Gtk.AccelLabel is created and added to the GtkMenuItem, and Gtk.AccelLabel::set_accel_widget() is called with the Gtk.MenuItem as the second argument. The Gtk.AccelLabel will now display Ctl+S after its label.

Note that creating a Gtk.MenuItem with Gtk.MenuItem::new_with_label() (or one of the similar functions for Gtk.CheckMenuItem and Gtk.RadioMenuItem) automatically adds a Gtk.AccelLabel to the Gtk.MenuItem and calls Gtk.AccelLabel::set_accel_widget() to set it up for you.

A Gtk.AccelLabel will only display accelerators which have Gtk.AccelFlags.VISIBLE set (see Gtk.AccelFlags).

A Gtk.AccelLabel can display multiple accelerators and even signal names, though it is almost always used to display just one accelerator key.

• Creating a simple menu item with an accelerator key:

    menuitem_open = Gtk.MenuItem(label="Open")
    submenu_file.append(menuitem_open)
    menuitem_open.connect('activate', self.on_menu_open)

    accelgroup = Gtk.AccelGroup()
    self.add_accel_group(accelgroup)        
    menuitem_open.add_accelerator("activate", 
                            accelgroup,
                            Gdk.keyval_from_name("o"),
                            Gdk.ModifierType.CONTROL_MASK,
                            Gtk.AccelFlags.VISIBLE)

Function Details:

new()

new (string:str) -> Gtk.Widget

Creates a new Gtk.AccelLabel.

• Returns: a new Gtk.AccelLabel.

set_accel_closure()

set_accel_closure (self, accel_closure:GObject.Closure)

Sets the closure to be monitored by this accelerator label. The closuremust be connected to an accelerator group; see `Gtk.AccelGroup:connect()`.

get_accel_widget()

get_accel_widget (self) -> Gtk.Widget

Fetches the widget monitored by this accelerator label. SeeGtk.AccelLabel:set_accel_widget().

• Returns: the object monitored by the accelerator label, or None.

set_accel_widget()

set_accel_widget (self, accel_widget:Gtk.Widget)

Sets the widget to be monitored by this accelerator label.

get_accel_width()

get_accel_width (self) -> int

Returns the width needed to display the accelerator key(s).This is used by menus to align all of the Gtk.MenuItem widgets, and shouldn'tbe needed by applications.

• Returns: the width needed to display the accelerator key(s).

set_accel()

set_accel (self, accelerator_key:int, accelerator_mods:Gdk.ModifierType)

Manually sets a keyval and modifier mask as the accelerator renderedby accel_label. If a keyval and modifier are explicitly set then these values areused regardless of any associated accel closure or widget. Providing an accelerator_key of 0 removes the manual setting.

• Since: 3.6

get_accel()

get_accel (self) -> accelerator_key:int, accelerator_mods:Gdk.ModifierType

Gets the keyval and modifier mask set withGtk.AccelLabel:set_accel().

• Since: 3.12

refetch()

refetch (self) -> bool

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

• Returns: always returns FALSE.

Example:

import gi
gi.require_version('Gtk', '3.0')
from gi.repository import Gtk, Gdk

class AccelLabel(Gtk.Window):
    def __init__(self):
        Gtk.Window.__init__(self)
        self.set_title("AccelLabel")
        self.set_default_size(200, -1)
        self.connect("destroy", Gtk.main_quit)

        grid = Gtk.Grid()
        self.add(grid)

        accelgroup = Gtk.AccelGroup()
        self.add_accel_group(accelgroup)

        accellabel = Gtk.AccelLabel("Button accelerator:")
        accellabel.set_hexpand(True)
        grid.attach(accellabel, 0, 0, 2, 1)

        button = Gtk.Button("Save")
        button.add_accelerator("clicked",
                               accelgroup,
                               Gdk.keyval_from_name("s"),
                               Gdk.ModifierType.CONTROL_MASK,
                               Gtk.AccelFlags.VISIBLE)
        button.connect("clicked", self.on_button_clicked)
        accellabel.set_accel_widget(button)
        grid.attach(button, 0, 1, 2, 1)

    def on_button_clicked(self, button):
        print("Save button clicked")

window = AccelLabel()
window.show_all()

Gtk.main()