GI.Gtk.Objects.ImageMenuItem

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

This is functionally equivalent to:

C code

 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 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 MenuItem with a Image instead.

ImageMenuItem has been deprecated since GTK+ 3.10. If you want to display an icon in a menu item, you should use MenuItem and pack a Box with a Image and a Label instead. You should also consider using Builder and the XML 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 boxPackEnd 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:

C code

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

Exported types

newtype ImageMenuItem

Memory-managed wrapper type.

Constructors

ImageMenuItem (ManagedPtr ImageMenuItem)

Instances

Eq ImageMenuItem

Defined in GI.Gtk.Objects.ImageMenuItem

Methods

(==) :: ImageMenuItem -> ImageMenuItem -> Bool

(/=) :: ImageMenuItem -> ImageMenuItem -> Bool

IsGValue ImageMenuItem

Convert ImageMenuItem to and from GValue with toGValue and fromGValue.

Defined in GI.Gtk.Objects.ImageMenuItem

Methods

toGValue :: ImageMenuItem -> IO GValue

fromGValue :: GValue -> IO ImageMenuItem

GObject ImageMenuItem

Defined in GI.Gtk.Objects.ImageMenuItem

Methods

gobjectType :: IO GType

HasParentTypes ImageMenuItem

Defined in GI.Gtk.Objects.ImageMenuItem

type ParentTypes ImageMenuItem

Defined in GI.Gtk.Objects.ImageMenuItem

type ParentTypes ImageMenuItem = '[MenuItem, Bin, Container, Widget, Object, ImplementorIface, Actionable, Activatable, Buildable]

class (GObject o, IsDescendantOf ImageMenuItem o) => IsImageMenuItem o

Type class for types which can be safely cast to ImageMenuItem, for instance with toImageMenuItem.

Instances

(GObject o, IsDescendantOf ImageMenuItem o) => IsImageMenuItem o

Defined in GI.Gtk.Objects.ImageMenuItem

toImageMenuItem :: (MonadIO m, IsImageMenuItem o) => o -> m ImageMenuItem

Cast to ImageMenuItem, for types for which this is known to be safe. For general casts, use castTo.

noImageMenuItem :: Maybe ImageMenuItem

A convenience alias for Nothing :: Maybe ImageMenuItem.

Methods

Overloaded methods

getAlwaysShowImage

imageMenuItemGetAlwaysShowImage

Arguments

:: (HasCallStack, MonadIO m, IsImageMenuItem a)

=> a

imageMenuItem: a ImageMenuItem

-> m Bool

Returns: True if the menu item will always show the image

Deprecated: (Since version 3.10)

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

Since: 2.16

getImage

imageMenuItemGetImage

Arguments

:: (HasCallStack, MonadIO m, IsImageMenuItem a)

=> a

imageMenuItem: a ImageMenuItem

-> m Widget

Returns: the widget set as image of imageMenuItem

Deprecated: (Since version 3.10)

Gets the widget that is currently set as the image of imageMenuItem. See imageMenuItemSetImage.

getUseStock

imageMenuItemGetUseStock

Arguments

:: (HasCallStack, MonadIO m, IsImageMenuItem a)

=> a

imageMenuItem: a ImageMenuItem

-> m Bool

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

Deprecated: (Since version 3.10)

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

Since: 2.16

new

imageMenuItemNew

Arguments

:: (HasCallStack, MonadIO m)

=> m ImageMenuItem

Returns: a new ImageMenuItem

Deprecated: (Since version 3.10)Use menuItemNew instead.

Creates a new ImageMenuItem with an empty label.

newFromStock

imageMenuItemNewFromStock

Arguments

:: (HasCallStack, MonadIO m, IsAccelGroup a)

=> Text

stockId: the name of the stock item.

-> Maybe a

accelGroup: the AccelGroup to add the menu items accelerator to, or Nothing.

-> m ImageMenuItem

Returns: a new ImageMenuItem.

Deprecated: (Since version 3.10)Use menuItemNewWithMnemonic instead.

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

If you want this menu item to have changeable accelerators, then pass in Nothing for accel_group. Next call menuItemSetAccelPath with an appropriate path for the menu item, use stockLookup to look up the standard accelerator for the stock item, and if one is found, call accelMapAddEntry to register it.

newWithLabel

imageMenuItemNewWithLabel

Arguments

:: (HasCallStack, MonadIO m)

=> Text

label: the text of the menu item.

-> m ImageMenuItem

Returns: a new ImageMenuItem.

Deprecated: (Since version 3.10)Use menuItemNewWithLabel instead.

Creates a new ImageMenuItem containing a label.

newWithMnemonic

imageMenuItemNewWithMnemonic

Arguments

:: (HasCallStack, MonadIO m)

=> Text

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

-> m ImageMenuItem

Returns: a new ImageMenuItem

Deprecated: (Since version 3.10)Use menuItemNewWithMnemonic instead.

Creates a new ImageMenuItem containing a label. The label will be created using labelNewWithMnemonic, so underscores in label indicate the mnemonic for the menu item.

setAccelGroup

imageMenuItemSetAccelGroup

Arguments

:: (HasCallStack, MonadIO m, IsImageMenuItem a, IsAccelGroup b)

=> a

imageMenuItem: a ImageMenuItem

-> b

accelGroup: the AccelGroup

-> m ()

Deprecated: (Since version 3.10)

Specifies an accelGroup 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 imageMenuItemSetUseStock and menuItemSetLabel with a valid stock item first).

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

Since: 2.16

setAlwaysShowImage

imageMenuItemSetAlwaysShowImage

Arguments

:: (HasCallStack, MonadIO m, IsImageMenuItem a)

=> a

imageMenuItem: a ImageMenuItem

-> Bool

alwaysShow: True if the menuitem should always show the image

-> m ()

Deprecated: (Since version 3.10)

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

Since: 2.16

setImage

imageMenuItemSetImage

Arguments

:: (HasCallStack, MonadIO m, IsImageMenuItem a, IsWidget b)

=> a

imageMenuItem: a ImageMenuItem.

-> Maybe b

image: a widget to set as the image for the menu item.

-> m ()

Deprecated: (Since version 3.10)

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

setUseStock

imageMenuItemSetUseStock

Arguments

:: (HasCallStack, MonadIO m, IsImageMenuItem a)

=> a

imageMenuItem: a ImageMenuItem

-> Bool

useStock: True if the menuitem should use a stock item

-> m ()

Deprecated: (Since version 3.10)

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

Since: 2.16

Properties

accelGroup

The Accel Group to use for stock accelerator keys

Since: 2.16

constructImageMenuItemAccelGroup :: (IsImageMenuItem o, IsAccelGroup a) => a -> IO (GValueConstruct o)

Construct a GValueConstruct with valid value for the “accel-group” property. This is rarely needed directly, but it is used by new.

setImageMenuItemAccelGroup :: (MonadIO m, IsImageMenuItem o, IsAccelGroup a) => o -> a -> m ()

Set the value of the “accel-group” property. When overloading is enabled, this is equivalent to

set imageMenuItem [ #accelGroup := value ]

alwaysShowImage

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.

Since: 2.16

constructImageMenuItemAlwaysShowImage :: IsImageMenuItem o => Bool -> IO (GValueConstruct o)

Construct a GValueConstruct with valid value for the “always-show-image” property. This is rarely needed directly, but it is used by new.

getImageMenuItemAlwaysShowImage :: (MonadIO m, IsImageMenuItem o) => o -> m Bool

Get the value of the “always-show-image” property. When overloading is enabled, this is equivalent to

get imageMenuItem #alwaysShowImage

setImageMenuItemAlwaysShowImage :: (MonadIO m, IsImageMenuItem o) => o -> Bool -> m ()

Set the value of the “always-show-image” property. When overloading is enabled, this is equivalent to

set imageMenuItem [ #alwaysShowImage := value ]

image

Child widget to appear next to the menu text.

clearImageMenuItemImage :: (MonadIO m, IsImageMenuItem o) => o -> m ()

Set the value of the “image” property to Nothing. When overloading is enabled, this is equivalent to

clear #image

constructImageMenuItemImage :: (IsImageMenuItem o, IsWidget a) => a -> IO (GValueConstruct o)

Construct a GValueConstruct with valid value for the “image” property. This is rarely needed directly, but it is used by new.

getImageMenuItemImage :: (MonadIO m, IsImageMenuItem o) => o -> m Widget

Get the value of the “image” property. When overloading is enabled, this is equivalent to

get imageMenuItem #image

setImageMenuItemImage :: (MonadIO m, IsImageMenuItem o, IsWidget a) => o -> a -> m ()

Set the value of the “image” property. When overloading is enabled, this is equivalent to

set imageMenuItem [ #image := value ]

useStock

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

Since: 2.16

constructImageMenuItemUseStock :: IsImageMenuItem o => Bool -> IO (GValueConstruct o)

Construct a GValueConstruct with valid value for the “use-stock” property. This is rarely needed directly, but it is used by new.

getImageMenuItemUseStock :: (MonadIO m, IsImageMenuItem o) => o -> m Bool

Get the value of the “use-stock” property. When overloading is enabled, this is equivalent to

get imageMenuItem #useStock

setImageMenuItemUseStock :: (MonadIO m, IsImageMenuItem o) => o -> Bool -> m ()

Set the value of the “use-stock” property. When overloading is enabled, this is equivalent to

set imageMenuItem [ #useStock := value ]