org.gnome.gtk

## Class ImageMenuItem

- Object
- - org.freedesktop.bindings.Pointer
  - - org.freedesktop.bindings.Proxy
    - - org.gnome.glib.Object
      - - org.gnome.gtk.Widget
        - - org.gnome.gtk.Container
          - - org.gnome.gtk.Bin
            - - org.gnome.gtk.MenuItem
              - - org.gnome.gtk.ImageMenuItem

- All Implemented Interfaces:
    Activatable

      public class ImageMenuItem
      extends MenuItem

  A MenuItem which displays an icon Image to the left of the Label text. This is used almost exclusively to add the MenuItems with common behaviour from the family of Stock icons, for example "File->Quit" and "Edit->Copy", so that the icons used are consistent with the rest of the GNOME Desktop. Indeed, it is somewhat discouraged to create ImageMenuItems with your own icons as too many icons can distract visually from the fact that the stock ones allow the eye to quickly recognize expected UI elements.

  See Action's `createMenuItem()`; you frequently need to do a UI activity from more than one place and Action will (among other things) generate the ImageMenuItem for a given Stock item. See also Button's `setImage()` for a discussion of the relationship between Images and Label text.

  Since:
    4.0.5
  Author:
    Andrew Cowie

- - ### Nested Class Summary

    - ### Nested classes/interfaces inherited from class org.gnome.gtk.MenuItem

      `MenuItem.Activate`

    - ### Nested classes/interfaces inherited from class org.gnome.gtk.Widget

      `Widget.ButtonPressEvent, Widget.ButtonReleaseEvent, Widget.Destroy, Widget.Draw, Widget.EnterNotifyEvent, Widget.FocusInEvent, Widget.FocusOutEvent, Widget.Hide, Widget.KeyPressEvent, Widget.KeyReleaseEvent, Widget.LeaveNotifyEvent, Widget.MapEvent, Widget.MotionNotifyEvent, Widget.PopupMenu, Widget.ScrollEvent, Widget.SizeAllocate, Widget.UnmapEvent, Widget.VisibilityNotifyEvent`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `ImageMenuItem(Image image, String label)` Create a MenuItem displaying an image next to text.
    `ImageMenuItem(Image image, String label, MenuItem.Activate handler)` Create a MenuItem displaying an image next to text, and hook up an `MenuItem.Activate` handler at the same time.
    `ImageMenuItem(Stock stock)` Create a MenuItem displaying a stock icon image.
    `ImageMenuItem(Stock stock, MenuItem.Activate handler)` Convenience constructor, allowing you to create a MenuItem displaying a stock icon while simultaneously hooking up the handler which will take its `MenuItem.Activate` signals.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `setAccelerator(AcceleratorGroup group)` Activate the key binding that comes with the stock configuration, for the case that this ImageMenuItem was constructed using a Stock item.
    `void` | `setAlwaysShowImage(boolean setting)` Force the icon accompanying this ImageMenuItem to always be shown, overriding the setting inherited from GtkSettings and GNOME.
    `void` | `setImage(Image image)` Set the Image that will be used as an icon beside the text in the ImageMenuItem.

    - ### Methods inherited from class org.gnome.gtk.MenuItem

      `connect, getRelatedAction, getSubmenu, setAccelerator, setRelatedAction, setSubmenu`

    - ### Methods inherited from class org.gnome.gtk.Bin

      `getChild`

    - ### Methods inherited from class org.gnome.gtk.Container

      `add, getChildren, remove, setBorderWidth`

    - ### Methods inherited from class org.gnome.gtk.Widget

      `activate, addEvents, connect, connect, connect, connect, connect, connect, connect, connect, connect, connect, connect, connect, connect, connect, connect, connect, connect, connect, destroy, getAllocatedHeight, getAllocatedWidth, getAllocation, getCanDefault, getCanFocus, getHasFocus, getName, getParent, getPreferredHeightForWidthMinimum, getPreferredHeightForWidthNatural, getPreferredHeightMinimum, getPreferredHeightNatural, getPreferredWidthForHeightMinimum, getPreferredWidthForHeightNatural, getPreferredWidthMinimum, getPreferredWidthNatural, getRequestMode, getRequisition, getSensitive, getStyleContext, getToplevel, getWindow, grabAdd, grabDefault, grabFocus, grabRemove, hide, isSensitive, overrideBackground, overrideColor, overrideFont, queueDraw, queueDrawArea, realize, setAlignHorizontal, setAlignVertical, setCanDefault, setCanFocus, setEvents, setExpandHorizontal, setExpandVertical, setName, setSensitive, setSizeRequest, setTooltipMarkup, setTooltipText, show, showAll`

    - ### Methods inherited from class org.freedesktop.bindings.Pointer

      `toString`

    - ### Methods inherited from class Object

      `equals, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- - ### Constructor Detail

    - #### ImageMenuItem

          public ImageMenuItem(Image image,
                       String label)

      Create a MenuItem displaying an image next to text. When you have a custom visual that is appropriate to show beside the label of a given MenuItem, you can use this to construct it.

      Don't use an empty string as a label! Users can turn off display of icons in menus, and if they do you'll end up with a MenuItem with "nothing" in it.

      There is also a constructor which allows you to connect an `MenuItem.Activate` handler in-line, see `here`.

      Since:
        4.0.6

    - #### ImageMenuItem

          public ImageMenuItem(Image image,
                       String label,
                       MenuItem.Activate handler)

      Create a MenuItem displaying an image next to text, and hook up an `MenuItem.Activate` handler at the same time.
      Since:
        4.0.6

    - #### ImageMenuItem

          public ImageMenuItem(Stock stock)

      Create a MenuItem displaying a stock icon image.

    - #### ImageMenuItem

          public ImageMenuItem(Stock stock,
                       MenuItem.Activate handler)

      Convenience constructor, allowing you to create a MenuItem displaying a stock icon while simultaneously hooking up the handler which will take its `MenuItem.Activate` signals.

  - ### Method Detail

    - #### setAccelerator

          public void setAccelerator(AcceleratorGroup group)

      Activate the key binding that comes with the stock configuration, for the case that this ImageMenuItem was constructed using a Stock item.
      Since:
        4.0.16

    - #### setAlwaysShowImage

          public void setAlwaysShowImage(boolean setting)

      Force the icon accompanying this ImageMenuItem to always be shown, overriding the setting inherited from GtkSettings and GNOME.

      As at GNOME 2.28, the default was changed by the `control-center` hackers to not show menu and button icons. This is very inconvenient, so you'll find yourself needing to call this frequently.

      Since:
        4.0.14

    - #### setImage

          public void setImage(Image image)

      Set the Image that will be used as an icon beside the text in the ImageMenuItem.

      Be aware that there are system wide settings which allow a user to turn off icons appearing in menus. Since there is always a chance that the "image" Widget being added will be hidden, don't create an ImageMenuItem with an empty label.

      Since:
        4.0.6