GtkImageMenuItem: GTK+ 3 Reference Manual

GtkImageMenuItem

GtkImageMenuItem — A deprecated widget for a menu item with an icon

Functions

void	gtk_image_menu_item_set_image ()
GtkWidget *	gtk_image_menu_item_get_image ()
GtkWidget *	gtk_image_menu_item_new ()
GtkWidget *	gtk_image_menu_item_new_from_stock ()
GtkWidget *	gtk_image_menu_item_new_with_label ()
GtkWidget *	gtk_image_menu_item_new_with_mnemonic ()
gboolean	gtk_image_menu_item_get_use_stock ()
void	gtk_image_menu_item_set_use_stock ()
gboolean	gtk_image_menu_item_get_always_show_image ()
void	gtk_image_menu_item_set_always_show_image ()
void	gtk_image_menu_item_set_accel_group ()

Properties

GtkAccelGroup *	accel-group	Write
gboolean	always-show-image	Read / Write / Construct
GtkWidget *	image	Read / Write
gboolean	use-stock	Read / Write / Construct

Types and Values

struct	GtkImageMenuItem
struct	GtkImageMenuItemClass

Object Hierarchy

    GObject
    ╰── GInitiallyUnowned
        ╰── GtkWidget
            ╰── GtkContainer
                ╰── GtkBin
                    ╰── GtkMenuItem
                        ╰── GtkImageMenuItem

Implemented Interfaces

GtkImageMenuItem implements AtkImplementorIface, GtkBuildable, GtkActivatable and GtkActionable.

Includes

#include <gtk/gtk.h>

Description

A GtkImageMenuItem 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-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 GtkMenuItem with a GtkImage instead.

GtkImageMenuItem has been deprecated since GTK+ 3.10. If you want to display an icon in a menu item, you should use GtkMenuItem and pack a GtkBox with a GtkImage and a GtkLabel instead. You should also consider using GtkBuilder and the XML GMenu description for creating menus, by following the GMenu guide. 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);

Functions

gtk_image_menu_item_set_image ()

void
gtk_image_menu_item_set_image (GtkImageMenuItem *image_menu_item,
                               GtkWidget *image);

gtk_image_menu_item_set_image has been deprecated since version 3.10 and should not be used in newly-written code.

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

Parameters

image_menu_item	a GtkImageMenuItem.
image	a widget to set as the image for the menu item.	[allow-none]

gtk_image_menu_item_get_image ()

GtkWidget *
gtk_image_menu_item_get_image (GtkImageMenuItem *image_menu_item);

gtk_image_menu_item_get_image has been deprecated since version 3.10 and should not be used in newly-written code.

Gets the widget that is currently set as the image of image_menu_item . See gtk_image_menu_item_set_image().

Parameters

image_menu_item

a GtkImageMenuItem

Returns

the widget set as image of image_menu_item .

[transfer none]

gtk_image_menu_item_new ()

GtkWidget *
gtk_image_menu_item_new (void);

gtk_image_menu_item_new has been deprecated since version 3.10 and should not be used in newly-written code.

Use gtk_menu_item_new() instead.

Creates a new GtkImageMenuItem with an empty label.

Returns

a new GtkImageMenuItem

gtk_image_menu_item_new_from_stock ()

GtkWidget *
gtk_image_menu_item_new_from_stock (const gchar *stock_id,
                                    GtkAccelGroup *accel_group);

gtk_image_menu_item_new_from_stock has been deprecated since version 3.10 and should not be used in newly-written code.

Use gtk_menu_item_new_with_mnemonic() instead.

Creates a new GtkImageMenuItem 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 NULL for accel_group. Next call gtk_menu_item_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_accel_map_add_entry() to register it.

Parameters

stock_id	the name of the stock item.
accel_group	the GtkAccelGroup to add the menu items accelerator to, or `NULL`.	[allow-none]

Returns

a new GtkImageMenuItem.

gtk_image_menu_item_new_with_label ()

GtkWidget *
gtk_image_menu_item_new_with_label (const gchar *label);

gtk_image_menu_item_new_with_label has been deprecated since version 3.10 and should not be used in newly-written code.

Use gtk_menu_item_new_with_label() instead.

Creates a new GtkImageMenuItem containing a label.

Parameters

label

the text of the menu item.

Returns

a new GtkImageMenuItem.

gtk_image_menu_item_new_with_mnemonic ()

GtkWidget *
gtk_image_menu_item_new_with_mnemonic (const gchar *label);

gtk_image_menu_item_new_with_mnemonic has been deprecated since version 3.10 and should not be used in newly-written code.

Use gtk_menu_item_new_with_mnemonic() instead.

Creates a new GtkImageMenuItem 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.

Parameters

label

the text of the menu item, with an underscore in front of the mnemonic character

Returns

a new GtkImageMenuItem

gtk_image_menu_item_get_use_stock ()

gboolean
gtk_image_menu_item_get_use_stock (GtkImageMenuItem *image_menu_item);

gtk_image_menu_item_get_use_stock has been deprecated since version 3.10 and should not be used in newly-written code.

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

Parameters

image_menu_item

a GtkImageMenuItem

Returns

TRUE if the label set in the menuitem is used as a stock id to select the stock item for the item

Since: 2.16

gtk_image_menu_item_set_use_stock ()

void
gtk_image_menu_item_set_use_stock (GtkImageMenuItem *image_menu_item,
                                   gboolean use_stock);

gtk_image_menu_item_set_use_stock has been deprecated since version 3.10 and should not be used in newly-written code.

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

Parameters

image_menu_item	a GtkImageMenuItem
use_stock	`TRUE` if the menuitem should use a stock item

Since: 2.16

gtk_image_menu_item_get_always_show_image ()

gboolean
gtk_image_menu_item_get_always_show_image
                               (GtkImageMenuItem *image_menu_item);

gtk_image_menu_item_get_always_show_image has been deprecated since version 3.10 and should not be used in newly-written code.

Returns whether the menu item will ignore the “gtk-menu-images” setting and always show the image, if available.

Parameters

image_menu_item

a GtkImageMenuItem

Returns

TRUE if the menu item will always show the image

Since: 2.16

gtk_image_menu_item_set_always_show_image ()

void
gtk_image_menu_item_set_always_show_image
                               (GtkImageMenuItem *image_menu_item,
                                gboolean always_show);

gtk_image_menu_item_set_always_show_image has been deprecated since version 3.10 and should not be used in newly-written code.

If TRUE, the menu item will ignore the “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.

Parameters

image_menu_item	a GtkImageMenuItem
always_show	`TRUE` if the menuitem should always show the image

Since: 2.16

gtk_image_menu_item_set_accel_group ()

void
gtk_image_menu_item_set_accel_group (GtkImageMenuItem *image_menu_item,
                                     GtkAccelGroup *accel_group);

gtk_image_menu_item_set_accel_group has been deprecated since version 3.10 and should not be used in newly-written code.

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_image_menu_item_set_use_stock() and gtk_menu_item_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_image_menu_item_new_from_stock()).

Parameters

image_menu_item	a GtkImageMenuItem
accel_group	the GtkAccelGroup

Since: 2.16

Types and Values

struct GtkImageMenuItem

struct GtkImageMenuItem;

struct GtkImageMenuItemClass

struct GtkImageMenuItemClass {
  GtkMenuItemClass parent_class;
};

Members

Property Details

The `“accel-group”` property

  “accel-group”              GtkAccelGroup *

The Accel Group to use for stock accelerator keys

GtkImageMenuItem:accel-group has been deprecated since version 3.10 and should not be used in newly-written code.

Use gtk_widget_add_accelerator() instead

Flags: Write

Since: 2.16

The `“always-show-image”` property

  “always-show-image”        gboolean

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.

GtkImageMenuItem:always-show-image has been deprecated since version 3.10 and should not be used in newly-written code.

Use a GtkMenuItem containing a GtkBox with a GtkAccelLabel and a GtkImage instead

Flags: Read / Write / Construct

Default value: FALSE

Since: 2.16

The `“image”` property

  “image”                    GtkWidget *

Child widget to appear next to the menu text.

GtkImageMenuItem:image has been deprecated since version 3.10 and should not be used in newly-written code.

Use a GtkMenuItem containing a GtkBox with a GtkAccelLabel and a GtkImage instead

Flags: Read / Write

The `“use-stock”` property

  “use-stock”                gboolean

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

GtkImageMenuItem:use-stock has been deprecated since version 3.10 and should not be used in newly-written code.

Use a named icon from the GtkIconTheme instead

Flags: Read / Write / Construct

Default value: FALSE

Since: 2.16