GI.Gtk.Objects.MenuItem

The MenuItem widget and the derived widgets are the only valid children for menus. Their function is to correctly handle highlighting, alignment, events and submenus.

As a GtkMenuItem derives from Bin it can hold any valid child widget, although only a few are really useful.

By default, a GtkMenuItem sets a AccelLabel as its child. GtkMenuItem has direct functions to set the label and its mnemonic. For more advanced label settings, you can fetch the child widget from the GtkBin.

An example for setting markup and accelerator on a MenuItem:

C code

GtkWidget *menu_item = gtk_menu_item_new_with_label ("Example Menu Item");

GtkWidget *child = gtk_bin_get_child (GTK_BIN (menu_item));
gtk_label_set_markup (GTK_LABEL (child), "<i>new label</i> with <b>markup</b>");
gtk_accel_label_set_accel (GTK_ACCEL_LABEL (child), GDK_KEY_1, 0);

GtkMenuItem as GtkBuildable

The GtkMenuItem implementation of the Buildable interface supports adding a submenu by specifying “submenu” as the “type” attribute of a <child> element.

An example of UI definition fragment with submenus: > >class="GtkMenuItem" > type="submenu" > class="GtkMenu"/ > /child >/object

CSS nodes

plain code

menuitem
├── <child>
╰── [arrow.right]

GtkMenuItem has a single CSS node with name menuitem. If the menuitem has a submenu, it gets another CSS node with name arrow, which has the .left or .right style class.

Exported types

newtype MenuItem

Memory-managed wrapper type.

Constructors

MenuItem (ManagedPtr MenuItem)

Instances

GObject MenuItem

Defined in GI.Gtk.Objects.MenuItem

Methods

gobjectType :: IO GType

HasParentTypes MenuItem

Defined in GI.Gtk.Objects.MenuItem

type ParentTypes MenuItem

Defined in GI.Gtk.Objects.MenuItem

type ParentTypes MenuItem = Bin ': (Container ': (Widget ': (Object ': (ImplementorIface ': (Actionable ': (Activatable ': (Buildable ': ([] :: [Type]))))))))

class (GObject o, IsDescendantOf MenuItem o) => IsMenuItem o

Type class for types which can be safely cast to MenuItem, for instance with toMenuItem.

Instances

(GObject o, IsDescendantOf MenuItem o) => IsMenuItem o

Defined in GI.Gtk.Objects.MenuItem

toMenuItem :: (MonadIO m, IsMenuItem o) => o -> m MenuItem

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

noMenuItem :: Maybe MenuItem

A convenience alias for Nothing :: Maybe MenuItem.

Methods

activate

menuItemActivate

Arguments

:: (HasCallStack, MonadIO m, IsMenuItem a)

=> a

menuItem: the menu item

-> m ()

Emits the MenuItem::activate signal on the given item

deselect

menuItemDeselect

Arguments

:: (HasCallStack, MonadIO m, IsMenuItem a)

=> a

menuItem: the menu item

-> m ()

Emits the MenuItem::deselect signal on the given item.

getAccelPath

menuItemGetAccelPath

Arguments

:: (HasCallStack, MonadIO m, IsMenuItem a)

=> a

menuItem: a valid MenuItem

-> m (Maybe Text)

Returns: the accelerator path corresponding to this menu item’s functionality, or Nothing if not set

Retrieve the accelerator path that was previously set on menuItem.

See menuItemSetAccelPath for details.

Since: 2.14

getLabel

menuItemGetLabel

Arguments

:: (HasCallStack, MonadIO m, IsMenuItem a)

=> a

menuItem: a MenuItem

-> m Text

Returns: The text in the menuItem label. This is the internal string used by the label, and must not be modified.

Sets text on the menuItem label

Since: 2.16

getReserveIndicator

menuItemGetReserveIndicator

Arguments

:: (HasCallStack, MonadIO m, IsMenuItem a)

=> a

menuItem: a MenuItem

-> m Bool

Returns: True if menuItem always reserves space for the submenu indicator

Returns whether the menuItem reserves space for the submenu indicator, regardless if it has a submenu or not.

Since: 3.0

getRightJustified

menuItemGetRightJustified

Arguments

:: (HasCallStack, MonadIO m, IsMenuItem a)

=> a

menuItem: a MenuItem

-> m Bool

Returns: True if the menu item will appear at the far right if added to a menu bar.

Deprecated: (Since version 3.2)See menuItemSetRightJustified

Gets whether the menu item appears justified at the right side of the menu bar.

getSubmenu

menuItemGetSubmenu

Arguments

:: (HasCallStack, MonadIO m, IsMenuItem a)

=> a

menuItem: a MenuItem

-> m (Maybe Widget)

Returns: submenu for this menu item, or Nothing if none

Gets the submenu underneath this menu item, if any. See menuItemSetSubmenu.

getUseUnderline

menuItemGetUseUnderline

Arguments

:: (HasCallStack, MonadIO m, IsMenuItem a)

=> a

menuItem: a MenuItem

-> m Bool

Returns: True if an embedded underline in the label indicates the mnemonic accelerator key.

Checks if an underline in the text indicates the next character should be used for the mnemonic accelerator key.

Since: 2.16

new

menuItemNew

Arguments

:: (HasCallStack, MonadIO m)

=> m MenuItem

Returns: the newly created MenuItem

Creates a new MenuItem.

newWithLabel

menuItemNewWithLabel

Arguments

:: (HasCallStack, MonadIO m)

=> Text

label: the text for the label

-> m MenuItem

Returns: the newly created MenuItem

Creates a new MenuItem whose child is a Label.

newWithMnemonic

menuItemNewWithMnemonic

Arguments

:: (HasCallStack, MonadIO m)

=> Text

label: The text of the button, with an underscore in front of the mnemonic character

-> m MenuItem

Returns: a new MenuItem

Creates a new MenuItem containing a label.

The label will be created using labelNewWithMnemonic, so underscores in label indicate the mnemonic for the menu item.

select

menuItemSelect

Arguments

:: (HasCallStack, MonadIO m, IsMenuItem a)

=> a

menuItem: the menu item

-> m ()

Emits the MenuItem::select signal on the given item.

setAccelPath

menuItemSetAccelPath

Arguments

:: (HasCallStack, MonadIO m, IsMenuItem a)

=> a

menuItem: a valid MenuItem

-> Maybe Text

accelPath: accelerator path, corresponding to this menu item’s functionality, or Nothing to unset the current path.

-> m ()

Set the accelerator path on menuItem, through which runtime changes of the menu item’s accelerator caused by the user can be identified and saved to persistent storage (see accelMapSave on this). To set up a default accelerator for this menu item, call accelMapAddEntry with the same accelPath. See also accelMapAddEntry on the specifics of accelerator paths, and menuSetAccelPath for a more convenient variant of this function.

This function is basically a convenience wrapper that handles calling widgetSetAccelPath with the appropriate accelerator group for the menu item.

Note that you do need to set an accelerator on the parent menu with menuSetAccelGroup for this to work.

Note that accelPath string will be stored in a GQuark. Therefore, if you pass a static string, you can save some memory by interning it first with internStaticString.

setLabel

menuItemSetLabel

Arguments

:: (HasCallStack, MonadIO m, IsMenuItem a)

=> a

menuItem: a MenuItem

-> Text

label: the text you want to set

-> m ()

Sets text on the menuItem label

Since: 2.16

setReserveIndicator

menuItemSetReserveIndicator

Arguments

:: (HasCallStack, MonadIO m, IsMenuItem a)

=> a

menuItem: a MenuItem

-> Bool

reserve: the new value

-> m ()

Sets whether the menuItem should reserve space for the submenu indicator, regardless if it actually has a submenu or not.

There should be little need for applications to call this functions.

Since: 3.0

setRightJustified

menuItemSetRightJustified

Arguments

:: (HasCallStack, MonadIO m, IsMenuItem a)

=> a

menuItem: a MenuItem.

-> Bool

rightJustified: if True the menu item will appear at the far right if added to a menu bar

-> m ()

Deprecated: (Since version 3.2)If you insist on using it, use widgetSetHexpand and widgetSetHalign.

Sets whether the menu item appears justified at the right side of a menu bar. This was traditionally done for “Help” menu items, but is now considered a bad idea. (If the widget layout is reversed for a right-to-left language like Hebrew or Arabic, right-justified-menu-items appear at the left.)

setSubmenu

menuItemSetSubmenu

Arguments

:: (HasCallStack, MonadIO m, IsMenuItem a, IsMenu b)

=> a

menuItem: a MenuItem

-> Maybe b

submenu: the submenu, or Nothing

-> m ()

Sets or replaces the menu item’s submenu, or removes it when a Nothing submenu is passed.

setUseUnderline

menuItemSetUseUnderline

Arguments

:: (HasCallStack, MonadIO m, IsMenuItem a)

=> a

menuItem: a MenuItem

-> Bool

setting: True if underlines in the text indicate mnemonics

-> m ()

If true, an underline in the text indicates the next character should be used for the mnemonic accelerator key.

Since: 2.16

toggleSizeAllocate

menuItemToggleSizeAllocate

Arguments

:: (HasCallStack, MonadIO m, IsMenuItem a)

=> a

menuItem: the menu item.

-> Int32

allocation: the allocation to use as signal data.

-> m ()

Emits the MenuItem::toggle-size-allocate signal on the given item.

toggleSizeRequest

menuItemToggleSizeRequest

Arguments

:: (HasCallStack, MonadIO m, IsMenuItem a)

=> a

menuItem: the menu item

-> Int32

requisition: the requisition to use as signal data.

-> m Int32

Emits the MenuItem::toggle-size-request signal on the given item.

Properties

accelPath

Sets the accelerator path of the menu item, through which runtime changes of the menu item's accelerator caused by the user can be identified and saved to persistant storage.

Since: 2.14

clearMenuItemAccelPath :: (MonadIO m, IsMenuItem o) => o -> m ()

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

clear #accelPath

constructMenuItemAccelPath :: IsMenuItem o => Text -> IO (GValueConstruct o)

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

getMenuItemAccelPath :: (MonadIO m, IsMenuItem o) => o -> m (Maybe Text)

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

get menuItem #accelPath

setMenuItemAccelPath :: (MonadIO m, IsMenuItem o) => o -> Text -> m ()

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

set menuItem [ #accelPath := value ]

label

The text for the child label.

Since: 2.16

constructMenuItemLabel :: IsMenuItem o => Text -> IO (GValueConstruct o)

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

getMenuItemLabel :: (MonadIO m, IsMenuItem o) => o -> m Text

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

get menuItem #label

setMenuItemLabel :: (MonadIO m, IsMenuItem o) => o -> Text -> m ()

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

set menuItem [ #label := value ]

rightJustified

Sets whether the menu item appears justified at the right side of a menu bar.

Since: 2.14

constructMenuItemRightJustified :: IsMenuItem o => Bool -> IO (GValueConstruct o)

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

getMenuItemRightJustified :: (MonadIO m, IsMenuItem o) => o -> m Bool

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

get menuItem #rightJustified

setMenuItemRightJustified :: (MonadIO m, IsMenuItem o) => o -> Bool -> m ()

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

set menuItem [ #rightJustified := value ]

submenu

The submenu attached to the menu item, or Nothing if it has none.

Since: 2.12

clearMenuItemSubmenu :: (MonadIO m, IsMenuItem o) => o -> m ()

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

clear #submenu

constructMenuItemSubmenu :: (IsMenuItem o, IsMenu a) => a -> IO (GValueConstruct o)

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

getMenuItemSubmenu :: (MonadIO m, IsMenuItem o) => o -> m (Maybe Menu)

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

get menuItem #submenu

setMenuItemSubmenu :: (MonadIO m, IsMenuItem o, IsMenu a) => o -> a -> m ()

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

set menuItem [ #submenu := value ]

useUnderline

True if underlines in the text indicate mnemonics.

Since: 2.16

constructMenuItemUseUnderline :: IsMenuItem o => Bool -> IO (GValueConstruct o)

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

getMenuItemUseUnderline :: (MonadIO m, IsMenuItem o) => o -> m Bool

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

get menuItem #useUnderline

setMenuItemUseUnderline :: (MonadIO m, IsMenuItem o) => o -> Bool -> m ()

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

set menuItem [ #useUnderline := value ]

Signals

activate

type C_MenuItemActivateCallback = Ptr () -> Ptr () -> IO ()

Type for the callback on the (unwrapped) C side.

type MenuItemActivateCallback = IO ()

Emitted when the item is activated.

afterMenuItemActivate :: (IsMenuItem a, MonadIO m) => a -> MenuItemActivateCallback -> m SignalHandlerId

Connect a signal handler for the “activate” signal, to be run after the default handler. When overloading is enabled, this is equivalent to

after menuItem #activate callback

genClosure_MenuItemActivate :: MonadIO m => MenuItemActivateCallback -> m (GClosure C_MenuItemActivateCallback)

Wrap the callback into a GClosure.

mk_MenuItemActivateCallback :: C_MenuItemActivateCallback -> IO (FunPtr C_MenuItemActivateCallback)

Generate a function pointer callable from C code, from a C_MenuItemActivateCallback.

noMenuItemActivateCallback :: Maybe MenuItemActivateCallback

A convenience synonym for Nothing :: Maybe MenuItemActivateCallback.

onMenuItemActivate :: (IsMenuItem a, MonadIO m) => a -> MenuItemActivateCallback -> m SignalHandlerId

Connect a signal handler for the “activate” signal, to be run before the default handler. When overloading is enabled, this is equivalent to

on menuItem #activate callback

wrap_MenuItemActivateCallback :: MenuItemActivateCallback -> C_MenuItemActivateCallback

Wrap a MenuItemActivateCallback into a C_MenuItemActivateCallback.

activateItem

type C_MenuItemActivateItemCallback = Ptr () -> Ptr () -> IO ()

Type for the callback on the (unwrapped) C side.

type MenuItemActivateItemCallback = IO ()

Emitted when the item is activated, but also if the menu item has a submenu. For normal applications, the relevant signal is MenuItem::activate.

afterMenuItemActivateItem :: (IsMenuItem a, MonadIO m) => a -> MenuItemActivateItemCallback -> m SignalHandlerId

Connect a signal handler for the “activate-item” signal, to be run after the default handler. When overloading is enabled, this is equivalent to

after menuItem #activateItem callback

genClosure_MenuItemActivateItem :: MonadIO m => MenuItemActivateItemCallback -> m (GClosure C_MenuItemActivateItemCallback)

Wrap the callback into a GClosure.

mk_MenuItemActivateItemCallback :: C_MenuItemActivateItemCallback -> IO (FunPtr C_MenuItemActivateItemCallback)

Generate a function pointer callable from C code, from a C_MenuItemActivateItemCallback.

noMenuItemActivateItemCallback :: Maybe MenuItemActivateItemCallback

A convenience synonym for Nothing :: Maybe MenuItemActivateItemCallback.

onMenuItemActivateItem :: (IsMenuItem a, MonadIO m) => a -> MenuItemActivateItemCallback -> m SignalHandlerId

Connect a signal handler for the “activate-item” signal, to be run before the default handler. When overloading is enabled, this is equivalent to

on menuItem #activateItem callback

wrap_MenuItemActivateItemCallback :: MenuItemActivateItemCallback -> C_MenuItemActivateItemCallback

Wrap a MenuItemActivateItemCallback into a C_MenuItemActivateItemCallback.

deselect

type C_MenuItemDeselectCallback = Ptr () -> Ptr () -> IO ()

Type for the callback on the (unwrapped) C side.

type MenuItemDeselectCallback = IO ()

No description available in the introspection data.

afterMenuItemDeselect :: (IsMenuItem a, MonadIO m) => a -> MenuItemDeselectCallback -> m SignalHandlerId

Connect a signal handler for the “deselect” signal, to be run after the default handler. When overloading is enabled, this is equivalent to

after menuItem #deselect callback

genClosure_MenuItemDeselect :: MonadIO m => MenuItemDeselectCallback -> m (GClosure C_MenuItemDeselectCallback)

Wrap the callback into a GClosure.

mk_MenuItemDeselectCallback :: C_MenuItemDeselectCallback -> IO (FunPtr C_MenuItemDeselectCallback)

Generate a function pointer callable from C code, from a C_MenuItemDeselectCallback.

noMenuItemDeselectCallback :: Maybe MenuItemDeselectCallback

A convenience synonym for Nothing :: Maybe MenuItemDeselectCallback.

onMenuItemDeselect :: (IsMenuItem a, MonadIO m) => a -> MenuItemDeselectCallback -> m SignalHandlerId

Connect a signal handler for the “deselect” signal, to be run before the default handler. When overloading is enabled, this is equivalent to

on menuItem #deselect callback

wrap_MenuItemDeselectCallback :: MenuItemDeselectCallback -> C_MenuItemDeselectCallback

Wrap a MenuItemDeselectCallback into a C_MenuItemDeselectCallback.

select

type C_MenuItemSelectCallback = Ptr () -> Ptr () -> IO ()

Type for the callback on the (unwrapped) C side.

type MenuItemSelectCallback = IO ()

No description available in the introspection data.

afterMenuItemSelect :: (IsMenuItem a, MonadIO m) => a -> MenuItemSelectCallback -> m SignalHandlerId

Connect a signal handler for the “select” signal, to be run after the default handler. When overloading is enabled, this is equivalent to

after menuItem #select callback

genClosure_MenuItemSelect :: MonadIO m => MenuItemSelectCallback -> m (GClosure C_MenuItemSelectCallback)

Wrap the callback into a GClosure.

mk_MenuItemSelectCallback :: C_MenuItemSelectCallback -> IO (FunPtr C_MenuItemSelectCallback)

Generate a function pointer callable from C code, from a C_MenuItemSelectCallback.

noMenuItemSelectCallback :: Maybe MenuItemSelectCallback

A convenience synonym for Nothing :: Maybe MenuItemSelectCallback.

onMenuItemSelect :: (IsMenuItem a, MonadIO m) => a -> MenuItemSelectCallback -> m SignalHandlerId

Connect a signal handler for the “select” signal, to be run before the default handler. When overloading is enabled, this is equivalent to

on menuItem #select callback

wrap_MenuItemSelectCallback :: MenuItemSelectCallback -> C_MenuItemSelectCallback

Wrap a MenuItemSelectCallback into a C_MenuItemSelectCallback.

toggleSizeAllocate

type C_MenuItemToggleSizeAllocateCallback = Ptr () -> Int32 -> Ptr () -> IO ()

Type for the callback on the (unwrapped) C side.

type MenuItemToggleSizeAllocateCallback = Int32 -> IO ()

No description available in the introspection data.

afterMenuItemToggleSizeAllocate :: (IsMenuItem a, MonadIO m) => a -> MenuItemToggleSizeAllocateCallback -> m SignalHandlerId

Connect a signal handler for the “toggle-size-allocate” signal, to be run after the default handler. When overloading is enabled, this is equivalent to

after menuItem #toggleSizeAllocate callback

genClosure_MenuItemToggleSizeAllocate :: MonadIO m => MenuItemToggleSizeAllocateCallback -> m (GClosure C_MenuItemToggleSizeAllocateCallback)

Wrap the callback into a GClosure.

mk_MenuItemToggleSizeAllocateCallback :: C_MenuItemToggleSizeAllocateCallback -> IO (FunPtr C_MenuItemToggleSizeAllocateCallback)

Generate a function pointer callable from C code, from a C_MenuItemToggleSizeAllocateCallback.

noMenuItemToggleSizeAllocateCallback :: Maybe MenuItemToggleSizeAllocateCallback

A convenience synonym for Nothing :: Maybe MenuItemToggleSizeAllocateCallback.

onMenuItemToggleSizeAllocate :: (IsMenuItem a, MonadIO m) => a -> MenuItemToggleSizeAllocateCallback -> m SignalHandlerId

Connect a signal handler for the “toggle-size-allocate” signal, to be run before the default handler. When overloading is enabled, this is equivalent to

on menuItem #toggleSizeAllocate callback

wrap_MenuItemToggleSizeAllocateCallback :: MenuItemToggleSizeAllocateCallback -> C_MenuItemToggleSizeAllocateCallback

Wrap a MenuItemToggleSizeAllocateCallback into a C_MenuItemToggleSizeAllocateCallback.

toggleSizeRequest

type C_MenuItemToggleSizeRequestCallback = Ptr () -> Ptr () -> Ptr () -> IO ()

Type for the callback on the (unwrapped) C side.

type MenuItemToggleSizeRequestCallback = Ptr () -> IO ()

No description available in the introspection data.

afterMenuItemToggleSizeRequest :: (IsMenuItem a, MonadIO m) => a -> MenuItemToggleSizeRequestCallback -> m SignalHandlerId

Connect a signal handler for the “toggle-size-request” signal, to be run after the default handler. When overloading is enabled, this is equivalent to

after menuItem #toggleSizeRequest callback

genClosure_MenuItemToggleSizeRequest :: MonadIO m => MenuItemToggleSizeRequestCallback -> m (GClosure C_MenuItemToggleSizeRequestCallback)

Wrap the callback into a GClosure.

mk_MenuItemToggleSizeRequestCallback :: C_MenuItemToggleSizeRequestCallback -> IO (FunPtr C_MenuItemToggleSizeRequestCallback)

Generate a function pointer callable from C code, from a C_MenuItemToggleSizeRequestCallback.

noMenuItemToggleSizeRequestCallback :: Maybe MenuItemToggleSizeRequestCallback

A convenience synonym for Nothing :: Maybe MenuItemToggleSizeRequestCallback.

onMenuItemToggleSizeRequest :: (IsMenuItem a, MonadIO m) => a -> MenuItemToggleSizeRequestCallback -> m SignalHandlerId

Connect a signal handler for the “toggle-size-request” signal, to be run before the default handler. When overloading is enabled, this is equivalent to

on menuItem #toggleSizeRequest callback

wrap_MenuItemToggleSizeRequestCallback :: MenuItemToggleSizeRequestCallback -> C_MenuItemToggleSizeRequestCallback

Wrap a MenuItemToggleSizeRequestCallback into a C_MenuItemToggleSizeRequestCallback.