gi-gtk3-3.0.44: Gtk 3.x bindings

Copyright | Will Thompson and Iñaki García Etxebarria
License | LGPL-2.1
Maintainer | Iñaki García Etxebarria
Safe Haskell | None
Language | Haskell2010

GI.Gtk.Objects.ImageMenuItem

Contents

- Exported types
- Methods
  - getAlwaysShowImage
  - getImage
  - getUseStock
  - new
  - newFromStock
  - newWithLabel
  - newWithMnemonic
  - setAccelGroup
  - setAlwaysShowImage
  - setImage
  - setUseStock
- Properties
  - accelGroup
  - alwaysShowImage
  - image
  - useStock

Description

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

Synopsis

- newtype ImageMenuItem = ImageMenuItem (ManagedPtr ImageMenuItem)
- class (GObject o, IsDescendantOf ImageMenuItem o) => IsImageMenuItem o
- toImageMenuItem :: (MonadIO m, IsImageMenuItem o) => o -> m ImageMenuItem
- imageMenuItemGetAlwaysShowImage :: (HasCallStack, MonadIO m, IsImageMenuItem a) => a -> m Bool
- imageMenuItemGetImage :: (HasCallStack, MonadIO m, IsImageMenuItem a) => a -> m Widget
- imageMenuItemGetUseStock :: (HasCallStack, MonadIO m, IsImageMenuItem a) => a -> m Bool
- imageMenuItemNew :: (HasCallStack, MonadIO m) => m ImageMenuItem
- imageMenuItemNewFromStock :: (HasCallStack, MonadIO m, IsAccelGroup a) => Text -> Maybe a -> m ImageMenuItem
- imageMenuItemNewWithLabel :: (HasCallStack, MonadIO m) => Text -> m ImageMenuItem
- imageMenuItemNewWithMnemonic :: (HasCallStack, MonadIO m) => Text -> m ImageMenuItem
- imageMenuItemSetAccelGroup :: (HasCallStack, MonadIO m, IsImageMenuItem a, IsAccelGroup b) => a -> b -> m ()
- imageMenuItemSetAlwaysShowImage :: (HasCallStack, MonadIO m, IsImageMenuItem a) => a -> Bool -> m ()
- imageMenuItemSetImage :: (HasCallStack, MonadIO m, IsImageMenuItem a, IsWidget b) => a -> Maybe b -> m ()
- imageMenuItemSetUseStock :: (HasCallStack, MonadIO m, IsImageMenuItem a) => a -> Bool -> m ()
- constructImageMenuItemAccelGroup :: (IsImageMenuItem o, MonadIO m, IsAccelGroup a) => a -> m (GValueConstruct o)
- setImageMenuItemAccelGroup :: (MonadIO m, IsImageMenuItem o, IsAccelGroup a) => o -> a -> m ()
- constructImageMenuItemAlwaysShowImage :: (IsImageMenuItem o, MonadIO m) => Bool -> m (GValueConstruct o)
- getImageMenuItemAlwaysShowImage :: (MonadIO m, IsImageMenuItem o) => o -> m Bool
- setImageMenuItemAlwaysShowImage :: (MonadIO m, IsImageMenuItem o) => o -> Bool -> m ()
- clearImageMenuItemImage :: (MonadIO m, IsImageMenuItem o) => o -> m ()
- constructImageMenuItemImage :: (IsImageMenuItem o, MonadIO m, IsWidget a) => a -> m (GValueConstruct o)
- getImageMenuItemImage :: (MonadIO m, IsImageMenuItem o) => o -> m Widget
- setImageMenuItemImage :: (MonadIO m, IsImageMenuItem o, IsWidget a) => o -> a -> m ()
- constructImageMenuItemUseStock :: (IsImageMenuItem o, MonadIO m) => Bool -> m (GValueConstruct o)
- getImageMenuItemUseStock :: (MonadIO m, IsImageMenuItem o) => o -> m Bool
- setImageMenuItemUseStock :: (MonadIO m, IsImageMenuItem o) => o -> Bool -> m ()

# Exported types

newtype ImageMenuItem Source #

Memory-managed wrapper type.

Constructors

ImageMenuItem (ManagedPtr ImageMenuItem) |

#### Instances

Instances details

Eq ImageMenuItem Source # |
Instance details Defined in GI.Gtk.Objects.ImageMenuItem Methods (==) :: ImageMenuItem -> ImageMenuItem -> Bool Source # (/=) :: ImageMenuItem -> ImageMenuItem -> Bool Source #
GObject ImageMenuItem Source # |
Instance details Defined in GI.Gtk.Objects.ImageMenuItem
ManagedPtrNewtype ImageMenuItem Source # |
Instance details Defined in GI.Gtk.Objects.ImageMenuItem Methods toManagedPtr :: ImageMenuItem -> ManagedPtr ImageMenuItem Source #
TypedObject ImageMenuItem Source # |
Instance details Defined in GI.Gtk.Objects.ImageMenuItem Methods glibType :: IO GType Source #
HasParentTypes ImageMenuItem Source # |
Instance details Defined in GI.Gtk.Objects.ImageMenuItem
IsGValue (Maybe ImageMenuItem) Source # | Convert `ImageMenuItem` to and from `GValue`. See `toGValue` and `fromGValue`.
Instance details Defined in GI.Gtk.Objects.ImageMenuItem Methods gvalueGType_ :: IO GType Source # gvalueSet_ :: Ptr GValue -> Maybe ImageMenuItem -> IO () Source # gvalueGet_ :: Ptr GValue -> IO (Maybe ImageMenuItem) Source #
type ParentTypes ImageMenuItem Source # |
Instance details 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 Source #

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

#### Instances

Instances details

(GObject o, IsDescendantOf ImageMenuItem o) => IsImageMenuItem o Source # |
Instance details Defined in GI.Gtk.Objects.ImageMenuItem

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

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

# Methods

### Click to display all available methods, including inherited ones

Expand

#### Methods

activate, add, addAccelerator, addChild, addDeviceEvents, addEvents, addMnemonicLabel, addTickCallback, bindProperty, bindPropertyFull, canActivateAccel, checkResize, childFocus, childGetProperty, childNotify, childNotifyByPspec, childSetProperty, childType, classPath, computeExpand, constructChild, createPangoContext, createPangoLayout, customFinished, customTagEnd, customTagStart, deselect, destroy, destroyed, deviceIsShadowed, doSetRelatedAction, dragBegin, dragBeginWithCoordinates, dragCheckThreshold, dragDestAddImageTargets, dragDestAddTextTargets, dragDestAddUriTargets, dragDestFindTarget, dragDestGetTargetList, dragDestGetTrackMotion, dragDestSet, dragDestSetProxy, dragDestSetTargetList, dragDestSetTrackMotion, dragDestUnset, dragGetData, dragHighlight, dragSourceAddImageTargets, dragSourceAddTextTargets, dragSourceAddUriTargets, dragSourceGetTargetList, dragSourceSet, dragSourceSetIconGicon, dragSourceSetIconName, dragSourceSetIconPixbuf, dragSourceSetIconStock, dragSourceSetTargetList, dragSourceUnset, dragUnhighlight, draw, ensureStyle, errorBell, event, forall, forceFloating, foreach, freezeChildNotify, freezeNotify, getv, grabAdd, grabDefault, grabFocus, grabRemove, hasDefault, hasFocus, hasGrab, hasRcStyle, hasScreen, hasVisibleFocus, hide, hideOnDelete, inDestruction, initTemplate, inputShapeCombineRegion, insertActionGroup, intersect, isAncestor, isComposited, isDrawable, isFloating, isFocus, isSensitive, isToplevel, isVisible, keynavFailed, listAccelClosures, listActionPrefixes, listMnemonicLabels, map, mnemonicActivate, modifyBase, modifyBg, modifyCursor, modifyFg, modifyFont, modifyStyle, modifyText, notify, notifyByPspec, overrideBackgroundColor, overrideColor, overrideCursor, overrideFont, overrideSymbolicColor, parserFinished, path, propagateDraw, queueAllocate, queueComputeExpand, queueDraw, queueDrawArea, queueDrawRegion, queueResize, queueResizeNoRedraw, realize, ref, refSink, regionIntersect, registerWindow, remove, removeAccelerator, removeMnemonicLabel, removeTickCallback, renderIcon, renderIconPixbuf, reparent, resetRcStyles, resetStyle, resizeChildren, runDispose, select, sendExpose, sendFocusChange, shapeCombineRegion, show, showAll, showNow, sizeAllocate, sizeAllocateWithBaseline, sizeRequest, stealData, stealQdata, styleAttach, styleGetProperty, syncActionProperties, thawChildNotify, thawNotify, toggleSizeAllocate, toggleSizeRequest, translateCoordinates, triggerTooltipQuery, unmap, unparent, unrealize, unref, unregisterWindow, unsetFocusChain, unsetStateFlags, watchClosure.

#### Getters

getAccelPath, getAccessible, getActionGroup, getActionName, getActionTargetValue, getAllocatedBaseline, getAllocatedHeight, getAllocatedSize, getAllocatedWidth, getAllocation, getAlwaysShowImage, getAncestor, getAppPaintable, getBorderWidth, getCanDefault, getCanFocus, getChild, getChildRequisition, getChildVisible, getChildren, getClip, getClipboard, getCompositeName, getData, getDeviceEnabled, getDeviceEvents, getDirection, getDisplay, getDoubleBuffered, getEvents, getFocusChain, getFocusChild, getFocusHadjustment, getFocusOnClick, getFocusVadjustment, getFontMap, getFontOptions, getFrameClock, getHalign, getHasTooltip, getHasWindow, getHexpand, getHexpandSet, getImage, getInternalChild, getLabel, getMapped, getMarginBottom, getMarginEnd, getMarginLeft, getMarginRight, getMarginStart, getMarginTop, getModifierMask, getModifierStyle, getName, getNoShowAll, getOpacity, getPangoContext, getParent, getParentWindow, getPath, getPathForChild, getPointer, getPreferredHeight, getPreferredHeightAndBaselineForWidth, getPreferredHeightForWidth, getPreferredSize, getPreferredWidth, getPreferredWidthForHeight, getProperty, getQdata, getRealized, getReceivesDefault, getRelatedAction, getRequestMode, getRequisition, getReserveIndicator, getResizeMode, getRightJustified, getRootWindow, getScaleFactor, getScreen, getSensitive, getSettings, getSizeRequest, getState, getStateFlags, getStyle, getStyleContext, getSubmenu, getSupportMultidevice, getTemplateChild, getTooltipMarkup, getTooltipText, getTooltipWindow, getToplevel, getUseActionAppearance, getUseStock, getUseUnderline, getValign, getValignWithBaseline, getVexpand, getVexpandSet, getVisible, getVisual, getWindow.

#### Setters

setAccelGroup, setAccelPath, setActionName, setActionTargetValue, setAllocation, setAlwaysShowImage, setAppPaintable, setBorderWidth, setBuildableProperty, setCanDefault, setCanFocus, setChildVisible, setClip, setCompositeName, setData, setDataFull, setDetailedActionName, setDeviceEnabled, setDeviceEvents, setDirection, setDoubleBuffered, setEvents, setFocusChain, setFocusChild, setFocusHadjustment, setFocusOnClick, setFocusVadjustment, setFontMap, setFontOptions, setHalign, setHasTooltip, setHasWindow, setHexpand, setHexpandSet, setImage, setLabel, setMapped, setMarginBottom, setMarginEnd, setMarginLeft, setMarginRight, setMarginStart, setMarginTop, setName, setNoShowAll, setOpacity, setParent, setParentWindow, setProperty, setRealized, setReallocateRedraws, setReceivesDefault, setRedrawOnAllocate, setRelatedAction, setReserveIndicator, setResizeMode, setRightJustified, setSensitive, setSizeRequest, setState, setStateFlags, setStyle, setSubmenu, setSupportMultidevice, setTooltipMarkup, setTooltipText, setTooltipWindow, setUseActionAppearance, setUseStock, setUseUnderline, setValign, setVexpand, setVexpandSet, setVisible, setVisual, setWindow.

## getAlwaysShowImage

imageMenuItemGetAlwaysShowImage Source #

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:gtkMenuImages setting and always show the image, if available.

Since: 2.16

## getImage

imageMenuItemGetImage Source #

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 Source #

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 Source #

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 Source #

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 Source #

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 Source #

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 Source #

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 Source #

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:gtkMenuImages 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 Source #

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 Source #

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, MonadIO m, IsAccelGroup a) => a -> m (GValueConstruct o) Source #

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 () Source #

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, MonadIO m) => Bool -> m (GValueConstruct o) Source #

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 Source #

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 () Source #

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 () Source #

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

    clear #image

constructImageMenuItemImage :: (IsImageMenuItem o, MonadIO m, IsWidget a) => a -> m (GValueConstruct o) Source #

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 Source #

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 () Source #

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, MonadIO m) => Bool -> m (GValueConstruct o) Source #

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 Source #

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 () Source #

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

    set imageMenuItem [ #useStock := value ]