Gtk.ImageMenuItem

g Atk.ImplementorIface Atk.ImplementorIface Gtk.Widget Gtk.Widget Atk.ImplementorIface->Gtk.Widget GObject.GInterface GObject.GInterface GObject.GInterface->Atk.ImplementorIface Gtk.Actionable Gtk.Actionable GObject.GInterface->Gtk.Actionable Gtk.Activatable Gtk.Activatable GObject.GInterface->Gtk.Activatable Gtk.Buildable Gtk.Buildable GObject.GInterface->Gtk.Buildable GObject.InitiallyUnowned GObject.InitiallyUnowned GObject.InitiallyUnowned->Gtk.Widget GObject.Object GObject.Object GObject.Object->GObject.InitiallyUnowned Gtk.MenuItem Gtk.MenuItem Gtk.Actionable->Gtk.MenuItem Gtk.Activatable->Gtk.MenuItem Gtk.Bin Gtk.Bin Gtk.Bin->Gtk.MenuItem Gtk.Buildable->Gtk.Widget Gtk.Container Gtk.Container Gtk.Container->Gtk.Bin Gtk.ImageMenuItem Gtk.ImageMenuItem Gtk.MenuItem->Gtk.ImageMenuItem Gtk.Widget->Gtk.Container

Subclasses:None

Properties

Inherited:Gtk.MenuItem (5), Gtk.Container (3), Gtk.Widget (39), Gtk.Actionable (2), Gtk.Activatable (2)
Name Type Flags Short Description
accel-group Gtk.AccelGroup d/w The Accel Group to use for stock accelerator keys deprecated
always-show-image bool d/r/w/c Whether the image will always be shown deprecated
image Gtk.Widget d/r/w Child widget to appear next to the menu text deprecated
use-stock bool d/r/w/c Whether to use the label text to create a stock menu item deprecated

Style Properties

Inherited:Gtk.MenuItem (6), Gtk.Widget (17)

Fields

Inherited:Gtk.MenuItem (6), Gtk.Container (4), Gtk.Widget (69), GObject.Object (1)
Name Type Access Description
menu_item Gtk.MenuItem r  
priv Gtk.ImageMenuItemPrivate r  

Class Details

class Gtk.ImageMenuItem(*args, **kwargs)
Bases:Gtk.MenuItem
Abstract:No
Structure:Gtk.ImageMenuItemClass

A Gtk.ImageMenuItem is a menu item which has an icon next to the text label.

This is functionally equivalent to:

GtkWidget *box = gtk_box_new (GTK_ORIENTATION_HORIZONTAL, 6);
GtkWidget *icon = gtk_image_new_from_icon_name ("folder-music-symbolic", GTK_ICON_SIZE_MENU);
GtkWidget *label = gtk_label_new ("Music");
GtkWidget *menu_item = gtk_menu_item_new ();

gtk_container_add (GTK_CONTAINER (box), icon);
gtk_container_add (GTK_CONTAINER (box), label);

gtk_container_add (GTK_CONTAINER (menu_item), box);

gtk_widget_show_all (menu_item);

Note that the user may disable display of menu icons using the Gtk.Settings :gtk-menu-images setting, so make sure to still fill in the text label. If you want to ensure that your menu items show an icon you are strongly encouraged to use a Gtk.MenuItem with a Gtk.Image instead.

Gtk.ImageMenuItem has been deprecated since GTK+ 3.10. If you want to display an icon in a menu item, you should use Gtk.MenuItem and pack a Gtk.Box with a Gtk.Image and a Gtk.Label instead. You should also consider using Gtk.Builder and the XML Gio.Menu description for creating menus, by following the ‘GMenu guide [https://developer.gnome.org/GMenu/]’. You should consider using icons in menu items only sparingly, and for “objects” (or “nouns”) elements only, like bookmarks, files, and links; “actions” (or “verbs”) should not have icons.

Furthermore, if you would like to display keyboard accelerator, you must pack the accel label into the box using Gtk.Box.pack_end() and align the label, otherwise the accelerator will not display correctly. The following code snippet adds a keyboard accelerator to the menu item, with a key binding of Ctrl+M:

GtkWidget *box = gtk_box_new (GTK_ORIENTATION_HORIZONTAL, 6);
GtkWidget *icon = gtk_image_new_from_icon_name ("folder-music-symbolic", GTK_ICON_SIZE_MENU);
GtkWidget *label = gtk_accel_label_new ("Music");
GtkWidget *menu_item = gtk_menu_item_new ();
GtkAccelGroup *accel_group = gtk_accel_group_new ();

gtk_container_add (GTK_CONTAINER (box), icon);

gtk_label_set_use_underline (GTK_LABEL (label), TRUE);
gtk_label_set_xalign (GTK_LABEL (label), 0.0);

gtk_widget_add_accelerator (menu_item, "activate", accel_group,
                            GDK_KEY_m, GDK_CONTROL_MASK, GTK_ACCEL_VISIBLE);
gtk_accel_label_set_accel_widget (GTK_ACCEL_LABEL (label), menu_item);

gtk_box_pack_end (GTK_BOX (box), label, TRUE, TRUE, 0);

gtk_container_add (GTK_CONTAINER (menu_item), box);

gtk_widget_show_all (menu_item);
classmethod new()[source]
Returns:a new Gtk.ImageMenuItem
Return type:Gtk.Widget

Creates a new Gtk.ImageMenuItem with an empty label.

Deprecated since version 3.10: Use Gtk.MenuItem.new() instead.

classmethod new_from_stock(stock_id, accel_group)[source]
Parameters:
Returns:

a new Gtk.ImageMenuItem.

Return type:

Gtk.Widget

Creates a new Gtk.ImageMenuItem containing the image and text from a stock item. Some stock ids have preprocessor macros like Gtk.STOCK_OK and Gtk.STOCK_APPLY.

If you want this menu item to have changeable accelerators, then pass in None for accel_group. Next call Gtk.MenuItem.set_accel_path() with an appropriate path for the menu item, use Gtk.stock_lookup() to look up the standard accelerator for the stock item, and if one is found, call Gtk.AccelMap.add_entry() to register it.

Deprecated since version 3.10: Use Gtk.MenuItem.new_with_mnemonic() instead.

classmethod new_with_label(label)[source]
Parameters:label (str) – the text of the menu item.
Returns:a new Gtk.ImageMenuItem.
Return type:Gtk.Widget

Creates a new Gtk.ImageMenuItem containing a label.

Deprecated since version 3.10: Use Gtk.MenuItem.new_with_label() instead.

classmethod new_with_mnemonic(label)[source]
Parameters:label (str) – the text of the menu item, with an underscore in front of the mnemonic character
Returns:a new Gtk.ImageMenuItem
Return type:Gtk.Widget

Creates a new Gtk.ImageMenuItem containing a label. The label will be created using Gtk.Label.new_with_mnemonic(), so underscores in label indicate the mnemonic for the menu item.

Deprecated since version 3.10: Use Gtk.MenuItem.new_with_mnemonic() instead.

get_always_show_image()[source]
Returns:True if the menu item will always show the image
Return type:bool

Returns whether the menu item will ignore the Gtk.Settings :gtk-menu-images setting and always show the image, if available.

New in version 2.16.

Deprecated since version 3.10.

get_image()[source]
Returns:the widget set as image of self
Return type:Gtk.Widget

Gets the widget that is currently set as the image of self. See Gtk.ImageMenuItem.set_image().

Deprecated since version 3.10.

get_use_stock()[source]
Returns:True if the label set in the menuitem is used as a stock id to select the stock item for the item
Return type:bool

Checks whether the label set in the menuitem is used as a stock id to select the stock item for the item.

New in version 2.16.

Deprecated since version 3.10.

set_accel_group(accel_group)[source]
Parameters:accel_group (Gtk.AccelGroup) – the Gtk.AccelGroup

Specifies an accel_group to add the menu items accelerator to (this only applies to stock items so a stock item must already be set, make sure to call Gtk.ImageMenuItem.set_use_stock() and Gtk.MenuItem.set_label() with a valid stock item first).

If you want this menu item to have changeable accelerators then you shouldnt need this (see Gtk.ImageMenuItem.new_from_stock()).

New in version 2.16.

Deprecated since version 3.10.

set_always_show_image(always_show)[source]
Parameters:always_show (bool) – True if the menuitem should always show the image

If True, the menu item will ignore the Gtk.Settings :gtk-menu-images setting and always show the image, if available.

Use this property if the menuitem would be useless or hard to use without the image.

New in version 2.16.

Deprecated since version 3.10.

set_image(image)[source]
Parameters:image (Gtk.Widget or None) – a widget to set as the image for the menu item.

Sets the image of self to the given widget. Note that it depends on the show-menu-images setting whether the image will be displayed or not.

Deprecated since version 3.10.

set_use_stock(use_stock)[source]
Parameters:use_stock (bool) – True if the menuitem should use a stock item

If True, the label set in the menuitem is used as a stock id to select the stock item for the item.

New in version 2.16.

Deprecated since version 3.10.

Property Details

Gtk.ImageMenuItem.props.accel_group
Name:accel-group
Type:Gtk.AccelGroup
Default Value:None
Flags:DEPRECATED, WRITABLE

The Accel Group to use for stock accelerator keys

New in version 2.16.

Deprecated since version 3.10: Use Gtk.Widget.add_accelerator() instead

Gtk.ImageMenuItem.props.always_show_image
Name:always-show-image
Type:bool
Default Value:False
Flags:DEPRECATED, READABLE, WRITABLE, CONSTRUCT

If True, the menu item will always show the image, if available.

Use this property only if the menuitem would be useless or hard to use without the image.

New in version 2.16.

Deprecated since version 3.10: Use a Gtk.MenuItem containing a Gtk.Box with a Gtk.AccelLabel and a Gtk.Image instead

Gtk.ImageMenuItem.props.image
Name:image
Type:Gtk.Widget
Default Value:None
Flags:DEPRECATED, READABLE, WRITABLE

Child widget to appear next to the menu text.

Deprecated since version 3.10: Use a Gtk.MenuItem containing a Gtk.Box with a Gtk.AccelLabel and a Gtk.Image instead

Gtk.ImageMenuItem.props.use_stock
Name:use-stock
Type:bool
Default Value:False
Flags:DEPRECATED, READABLE, WRITABLE, CONSTRUCT

If True, the label set in the menuitem is used as a stock id to select the stock item for the item.

New in version 2.16.

Deprecated since version 3.10: Use a named icon from the Gtk.IconTheme instead