MenuItemProtocol

public protocol MenuItemProtocol : ActionableProtocol, ActivatableProtocol, BinProtocol

The GtkMenuItem 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 GtkBin it can hold any valid child widget, although only a few are really useful.

By default, a GtkMenuItem sets a GtkAccelLabel 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 Language Example):

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 GtkBuildable interface supports adding a submenu by specifying “submenu” as the “type” attribute of a <child> element.

An example of UI definition fragment with submenus:

<object class="GtkMenuItem">
  <child type="submenu">
    <object class="GtkMenu"/>
  </child>
</object>

CSS nodes

(plain Language Example):

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.

The MenuItemProtocol protocol exposes the methods and properties of an underlying GtkMenuItem instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see MenuItem. Alternatively, use MenuItemRef as a lighweight, unowned reference if you already have an instance you just want to use.

Show on GitHub
  • ptr

    Untyped pointer to the underlying GtkMenuItem instance.

    Declaration

    Swift

    var ptr: UnsafeMutableRawPointer! { get }
    Show on GitHub
  • menu_item_ptr Default implementation

    Typed pointer to the underlying GtkMenuItem instance.

    Default Implementation

    Return the stored, untyped pointer as a typed pointer to the GtkMenuItem instance.

    Declaration

    Swift

    var menu_item_ptr: UnsafeMutablePointer<GtkMenuItem>! { get }
    Show on GitHub

  • Required Initialiser for types conforming to MenuItemProtocol

    Declaration

    Swift

    init(raw: UnsafeMutableRawPointer)
    Show on GitHub

MenuItem Class

  • Bind a MenuItemPropertyName source property to a given target object.

    Declaration

    Swift

    @discardableResult
@inlinable
func bind<Q, T>(property source_property: MenuItemPropertyName, to target: T, _ target_property: Q, flags f: BindingFlags = .default, transformFrom transform_from: @escaping GLibObject.ValueTransformer = { $0.transform(destValue: $1) }, transformTo transform_to: @escaping GLibObject.ValueTransformer = { $0.transform(destValue: $1) }) -> BindingRef! where Q : PropertyNameProtocol, T : ObjectProtocol

    Parameters

    source_property

    the source property to bind
    target

    the target object to bind to
    target_property

    the target property to bind to
    flags

    the flags to pass to the Binding
    transform_from

    ValueTransformer to use for forward transformation
    transform_to

    ValueTransformer to use for backwards transformation

    Return Value

    binding reference or nil in case of an error

    Show on GitHub
  • get(property:) Extension method

    Get the value of a MenuItem property

    Declaration

    Swift

    @inlinable
func get(property: MenuItemPropertyName) -> GLibObject.Value

    Parameters

    property

    the property to get the value for

    Return Value

    the value of the named property

    Show on GitHub
  • set(property:value:) Extension method

    Set the value of a MenuItem property. Note that this will only have an effect on properties that are writable and not construct-only!

    Declaration

    Swift

    @inlinable
func set(property: MenuItemPropertyName, value v: GLibObject.Value)

    Parameters

    property

    the property to get the value for

    Return Value

    the value of the named property

    Show on GitHub

MenuItem signals

  • Connect a Swift signal handler to the given, typed MenuItemSignalName signal

    Declaration

    Swift

    @discardableResult
@inlinable
func connect(signal s: MenuItemSignalName, flags f: ConnectFlags = ConnectFlags(0), handler h: @escaping SignalHandler) -> Int

    Parameters

    signal

    The signal to connect
    flags

    The connection flags to use
    data

    A pointer to user data to provide to the callback
    destroyData

    A GClosureNotify C function to destroy the data pointed to by userData
    handler

    The Swift signal handler (function or callback) to invoke on the given signal

    Return Value

    The signal handler ID (always greater than 0 for successful connections)

    Show on GitHub

  • Connect a C signal handler to the given, typed MenuItemSignalName signal

    Declaration

    Swift

    @discardableResult
@inlinable
func connect(signal s: MenuItemSignalName, flags f: ConnectFlags = ConnectFlags(0), data userData: gpointer!, destroyData destructor: GClosureNotify? = nil, signalHandler h: @escaping GCallback) -> Int

    Parameters

    signal

    The signal to connect
    flags

    The connection flags to use
    data

    A pointer to user data to provide to the callback
    destroyData

    A GClosureNotify C function to destroy the data pointed to by userData
    signalHandler

    The C function to be called on the given signal

    Return Value

    The signal handler ID (always greater than 0 for successful connections)

    Show on GitHub
  • toggleSizeRequestSignal Extension method

    Note

    This represents the underlying toggle-size-request signal

    Warning

    a onToggleSizeRequest wrapper for this signal could not be generated because it contains unimplemented features: { (4) gpointer argument is not yet supported }

    Note

    Instead, you can connect toggleSizeRequestSignal using the connect(signal:) methods

    Declaration

    Swift

    static var toggleSizeRequestSignal: MenuItemSignalName { get }

    Parameters

    flags

    Flags
    unownedSelf

    Reference to instance of self
    object

    none
    handler

    The signal handler to call
    Show on GitHub
  • onActivate(flags:handler:) Extension method

    Emitted when the item is activated.

    Note

    This represents the underlying activate signal

    Declaration

    Swift

    @discardableResult
@inlinable
func onActivate(flags: ConnectFlags = ConnectFlags(0), handler: @escaping (_ unownedSelf: MenuItemRef) -> Void) -> Int

    Parameters

    flags

    Flags
    unownedSelf

    Reference to instance of self
    handler

    The signal handler to call Run the given callback whenever the activate signal is emitted
    Show on GitHub
  • activateSignal Extension method

    Typed activate signal for using the connect(signal:) methods

    Declaration

    Swift

    static var activateSignal: MenuItemSignalName { get }
    Show on GitHub

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

    Note

    This represents the underlying activate-item signal

    Declaration

    Swift

    @discardableResult
@inlinable
func onActivateItem(flags: ConnectFlags = ConnectFlags(0), handler: @escaping (_ unownedSelf: MenuItemRef) -> Void) -> Int

    Parameters

    flags

    Flags
    unownedSelf

    Reference to instance of self
    handler

    The signal handler to call Run the given callback whenever the activateItem signal is emitted
    Show on GitHub
  • activateItemSignal Extension method

    Typed activate-item signal for using the connect(signal:) methods

    Declaration

    Swift

    static var activateItemSignal: MenuItemSignalName { get }
    Show on GitHub
  • onDeselect(flags:handler:) Extension method

    Note

    This represents the underlying deselect signal

    Declaration

    Swift

    @discardableResult
@inlinable
func onDeselect(flags: ConnectFlags = ConnectFlags(0), handler: @escaping (_ unownedSelf: MenuItemRef) -> Void) -> Int

    Parameters

    flags

    Flags
    unownedSelf

    Reference to instance of self
    handler

    The signal handler to call Run the given callback whenever the deselect signal is emitted
    Show on GitHub
  • deselectSignal Extension method

    Typed deselect signal for using the connect(signal:) methods

    Declaration

    Swift

    static var deselectSignal: MenuItemSignalName { get }
    Show on GitHub
  • onSelect(flags:handler:) Extension method

    Note

    This represents the underlying select signal

    Declaration

    Swift

    @discardableResult
@inlinable
func onSelect(flags: ConnectFlags = ConnectFlags(0), handler: @escaping (_ unownedSelf: MenuItemRef) -> Void) -> Int

    Parameters

    flags

    Flags
    unownedSelf

    Reference to instance of self
    handler

    The signal handler to call Run the given callback whenever the select signal is emitted
    Show on GitHub
  • selectSignal Extension method

    Typed select signal for using the connect(signal:) methods

    Declaration

    Swift

    static var selectSignal: MenuItemSignalName { get }
    Show on GitHub

  • Note

    This represents the underlying toggle-size-allocate signal

    Declaration

    Swift

    @discardableResult
@inlinable
func onToggleSizeAllocate(flags: ConnectFlags = ConnectFlags(0), handler: @escaping (_ unownedSelf: MenuItemRef, _ object: Int) -> Void) -> Int

    Parameters

    flags

    Flags
    unownedSelf

    Reference to instance of self
    object

    none
    handler

    The signal handler to call Run the given callback whenever the toggleSizeAllocate signal is emitted
    Show on GitHub
  • toggleSizeAllocateSignal Extension method

    Typed toggle-size-allocate signal for using the connect(signal:) methods

    Declaration

    Swift

    static var toggleSizeAllocateSignal: MenuItemSignalName { get }
    Show on GitHub

  • The notify signal is emitted on an object when one of its properties has its value set through g_object_set_property(), g_object_set(), et al.

    Note that getting this signal doesn’t itself guarantee that the value of the property has actually changed. When it is emitted is determined by the derived GObject class. If the implementor did not create the property with G_PARAM_EXPLICIT_NOTIFY, then any call to g_object_set_property() results in notify being emitted, even if the new value is the same as the old. If they did pass G_PARAM_EXPLICIT_NOTIFY, then this signal is emitted only when they explicitly call g_object_notify() or g_object_notify_by_pspec(), and common practice is to do that only when the value has actually changed.

    This signal is typically used to obtain change notification for a single property, by specifying the property name as a detail in the g_signal_connect() call, like this:

    (C Language Example):

    g_signal_connect (text_view->buffer, "notify::paste-target-list",
                  G_CALLBACK (gtk_text_view_target_list_notify),
                  text_view)

    It is important to note that you must use canonical parameter names as detail strings for the notify signal.

    Note

    This represents the underlying notify::accel-path signal

    Declaration

    Swift

    @discardableResult
@inlinable
func onNotifyAccelPath(flags: ConnectFlags = ConnectFlags(0), handler: @escaping (_ unownedSelf: MenuItemRef, _ pspec: ParamSpecRef) -> Void) -> Int

    Parameters

    flags

    Flags
    unownedSelf

    Reference to instance of self
    pspec

    the GParamSpec of the property which changed.
    handler

    The signal handler to call Run the given callback whenever the notifyAccelPath signal is emitted
    Show on GitHub
  • notifyAccelPathSignal Extension method

    Typed notify::accel-path signal for using the connect(signal:) methods

    Declaration

    Swift

    static var notifyAccelPathSignal: MenuItemSignalName { get }
    Show on GitHub

  • The notify signal is emitted on an object when one of its properties has its value set through g_object_set_property(), g_object_set(), et al.

    Note that getting this signal doesn’t itself guarantee that the value of the property has actually changed. When it is emitted is determined by the derived GObject class. If the implementor did not create the property with G_PARAM_EXPLICIT_NOTIFY, then any call to g_object_set_property() results in notify being emitted, even if the new value is the same as the old. If they did pass G_PARAM_EXPLICIT_NOTIFY, then this signal is emitted only when they explicitly call g_object_notify() or g_object_notify_by_pspec(), and common practice is to do that only when the value has actually changed.

    This signal is typically used to obtain change notification for a single property, by specifying the property name as a detail in the g_signal_connect() call, like this:

    (C Language Example):

    g_signal_connect (text_view->buffer, "notify::paste-target-list",
                  G_CALLBACK (gtk_text_view_target_list_notify),
                  text_view)

    It is important to note that you must use canonical parameter names as detail strings for the notify signal.

    Note

    This represents the underlying notify::label signal

    Declaration

    Swift

    @discardableResult
@inlinable
func onNotifyLabel(flags: ConnectFlags = ConnectFlags(0), handler: @escaping (_ unownedSelf: MenuItemRef, _ pspec: ParamSpecRef) -> Void) -> Int

    Parameters

    flags

    Flags
    unownedSelf

    Reference to instance of self
    pspec

    the GParamSpec of the property which changed.
    handler

    The signal handler to call Run the given callback whenever the notifyLabel signal is emitted
    Show on GitHub
  • notifyLabelSignal Extension method

    Typed notify::label signal for using the connect(signal:) methods

    Declaration

    Swift

    static var notifyLabelSignal: MenuItemSignalName { get }
    Show on GitHub

  • The notify signal is emitted on an object when one of its properties has its value set through g_object_set_property(), g_object_set(), et al.

    Note that getting this signal doesn’t itself guarantee that the value of the property has actually changed. When it is emitted is determined by the derived GObject class. If the implementor did not create the property with G_PARAM_EXPLICIT_NOTIFY, then any call to g_object_set_property() results in notify being emitted, even if the new value is the same as the old. If they did pass G_PARAM_EXPLICIT_NOTIFY, then this signal is emitted only when they explicitly call g_object_notify() or g_object_notify_by_pspec(), and common practice is to do that only when the value has actually changed.

    This signal is typically used to obtain change notification for a single property, by specifying the property name as a detail in the g_signal_connect() call, like this:

    (C Language Example):

    g_signal_connect (text_view->buffer, "notify::paste-target-list",
                  G_CALLBACK (gtk_text_view_target_list_notify),
                  text_view)

    It is important to note that you must use canonical parameter names as detail strings for the notify signal.

    Note

    This represents the underlying notify::right-justified signal

    Declaration

    Swift

    @discardableResult
@inlinable
func onNotifyRightJustified(flags: ConnectFlags = ConnectFlags(0), handler: @escaping (_ unownedSelf: MenuItemRef, _ pspec: ParamSpecRef) -> Void) -> Int

    Parameters

    flags

    Flags
    unownedSelf

    Reference to instance of self
    pspec

    the GParamSpec of the property which changed.
    handler

    The signal handler to call Run the given callback whenever the notifyRightJustified signal is emitted
    Show on GitHub
  • notifyRightJustifiedSignal Extension method

    Typed notify::right-justified signal for using the connect(signal:) methods

    Declaration

    Swift

    static var notifyRightJustifiedSignal: MenuItemSignalName { get }
    Show on GitHub

  • The notify signal is emitted on an object when one of its properties has its value set through g_object_set_property(), g_object_set(), et al.

    Note that getting this signal doesn’t itself guarantee that the value of the property has actually changed. When it is emitted is determined by the derived GObject class. If the implementor did not create the property with G_PARAM_EXPLICIT_NOTIFY, then any call to g_object_set_property() results in notify being emitted, even if the new value is the same as the old. If they did pass G_PARAM_EXPLICIT_NOTIFY, then this signal is emitted only when they explicitly call g_object_notify() or g_object_notify_by_pspec(), and common practice is to do that only when the value has actually changed.

    This signal is typically used to obtain change notification for a single property, by specifying the property name as a detail in the g_signal_connect() call, like this:

    (C Language Example):

    g_signal_connect (text_view->buffer, "notify::paste-target-list",
                  G_CALLBACK (gtk_text_view_target_list_notify),
                  text_view)

    It is important to note that you must use canonical parameter names as detail strings for the notify signal.

    Note

    This represents the underlying notify::submenu signal

    Declaration

    Swift

    @discardableResult
@inlinable
func onNotifySubmenu(flags: ConnectFlags = ConnectFlags(0), handler: @escaping (_ unownedSelf: MenuItemRef, _ pspec: ParamSpecRef) -> Void) -> Int

    Parameters

    flags

    Flags
    unownedSelf

    Reference to instance of self
    pspec

    the GParamSpec of the property which changed.
    handler

    The signal handler to call Run the given callback whenever the notifySubmenu signal is emitted
    Show on GitHub
  • notifySubmenuSignal Extension method

    Typed notify::submenu signal for using the connect(signal:) methods

    Declaration

    Swift

    static var notifySubmenuSignal: MenuItemSignalName { get }
    Show on GitHub

  • The notify signal is emitted on an object when one of its properties has its value set through g_object_set_property(), g_object_set(), et al.

    Note that getting this signal doesn’t itself guarantee that the value of the property has actually changed. When it is emitted is determined by the derived GObject class. If the implementor did not create the property with G_PARAM_EXPLICIT_NOTIFY, then any call to g_object_set_property() results in notify being emitted, even if the new value is the same as the old. If they did pass G_PARAM_EXPLICIT_NOTIFY, then this signal is emitted only when they explicitly call g_object_notify() or g_object_notify_by_pspec(), and common practice is to do that only when the value has actually changed.

    This signal is typically used to obtain change notification for a single property, by specifying the property name as a detail in the g_signal_connect() call, like this:

    (C Language Example):

    g_signal_connect (text_view->buffer, "notify::paste-target-list",
                  G_CALLBACK (gtk_text_view_target_list_notify),
                  text_view)

    It is important to note that you must use canonical parameter names as detail strings for the notify signal.

    Note

    This represents the underlying notify::use-underline signal

    Declaration

    Swift

    @discardableResult
@inlinable
func onNotifyUseUnderline(flags: ConnectFlags = ConnectFlags(0), handler: @escaping (_ unownedSelf: MenuItemRef, _ pspec: ParamSpecRef) -> Void) -> Int

    Parameters

    flags

    Flags
    unownedSelf

    Reference to instance of self
    pspec

    the GParamSpec of the property which changed.
    handler

    The signal handler to call Run the given callback whenever the notifyUseUnderline signal is emitted
    Show on GitHub
  • notifyUseUnderlineSignal Extension method

    Typed notify::use-underline signal for using the connect(signal:) methods

    Declaration

    Swift

    static var notifyUseUnderlineSignal: MenuItemSignalName { get }
    Show on GitHub

MenuItem Class: MenuItemProtocol extension (methods and fields)

  • activate() Extension method

    Emits the GtkMenuItem::activate signal on the given item

    Declaration

    Swift

    @inlinable
func activate()
    Show on GitHub
  • deselect() Extension method

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

    Declaration

    Swift

    @inlinable
func deselect()
    Show on GitHub
  • getAccelPath() Extension method

    Retrieve the accelerator path that was previously set on menu_item.

    See gtk_menu_item_set_accel_path() for details.

    Declaration

    Swift

    @inlinable
func getAccelPath() -> String!
    Show on GitHub
  • getLabel() Extension method

    Sets text on the menu_item label

    Declaration

    Swift

    @inlinable
func getLabel() -> String!
    Show on GitHub
  • getReserveIndicator() Extension method

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

    Declaration

    Swift

    @inlinable
func getReserveIndicator() -> Bool
    Show on GitHub
  • getRightJustified() Extension method

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

    get_right_justified is deprecated: See gtk_menu_item_set_right_justified()

    Declaration

    Swift

    @available(*, deprecated)
@inlinable
func getRightJustified() -> Bool
    Show on GitHub
  • getSubmenu() Extension method

    Gets the submenu underneath this menu item, if any. See gtk_menu_item_set_submenu().

    Declaration

    Swift

    @inlinable
func getSubmenu() -> WidgetRef!
    Show on GitHub
  • getUseUnderline() Extension method

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

    Declaration

    Swift

    @inlinable
func getUseUnderline() -> Bool
    Show on GitHub
  • select() Extension method

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

    Declaration

    Swift

    @inlinable
func select()
    Show on GitHub
  • set(accelPath:) Extension method

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

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

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

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

    Declaration

    Swift

    @inlinable
func set(accelPath: UnsafePointer<gchar>? = nil)
    Show on GitHub
  • set(label:) Extension method

    Sets text on the menu_item label

    Declaration

    Swift

    @inlinable
func set(label: UnsafePointer<gchar>!)
    Show on GitHub

  • Sets whether the menu_item 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.

    Declaration

    Swift

    @inlinable
func setReserveIndicator(reserve: Bool)
    Show on GitHub
  • set(rightJustified:) Extension method

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

    set_right_justified is deprecated: If you insist on using it, use gtk_widget_set_hexpand() and gtk_widget_set_halign().

    Declaration

    Swift

    @available(*, deprecated)
@inlinable
func set(rightJustified: Bool)
    Show on GitHub
  • set(submenu:) Extension method

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

    Declaration

    Swift

    @inlinable
func set(submenu: MenuRef? = nil)
    Show on GitHub
  • set(submenu:) Extension method

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

    Declaration

    Swift

    @inlinable
func set<MenuT>(submenu: MenuT?) where MenuT : MenuProtocol
    Show on GitHub
  • set(useUnderline:) Extension method

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

    Declaration

    Swift

    @inlinable
func set(useUnderline setting: Bool)
    Show on GitHub

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

    Declaration

    Swift

    @inlinable
func toggleSizeAllocate(allocation: Int)
    Show on GitHub

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

    Declaration

    Swift

    @inlinable
func toggleSizeRequest(requisition: UnsafeMutablePointer<gint>!)
    Show on GitHub
  • accelPath Extension method

    Retrieve the accelerator path that was previously set on menu_item.

    See gtk_menu_item_set_accel_path() for details.

    Declaration

    Swift

    @inlinable
var accelPath: String! { get nonmutating set }
    Show on GitHub
  • label Extension method

    The text for the child label.

    Declaration

    Swift

    @inlinable
var label: String! { get nonmutating set }
    Show on GitHub
  • reserveIndicator Extension method

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

    Declaration

    Swift

    @inlinable
var reserveIndicator: Bool { get nonmutating set }
    Show on GitHub
  • rightJustified Extension method

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

    get_right_justified is deprecated: See gtk_menu_item_set_right_justified()

    Declaration

    Swift

    @inlinable
var rightJustified: Bool { get nonmutating set }
    Show on GitHub
  • submenu Extension method

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

    Declaration

    Swift

    @inlinable
var submenu: WidgetRef! { get nonmutating set }
    Show on GitHub
  • useUnderline Extension method

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

    Declaration

    Swift

    @inlinable
var useUnderline: Bool { get nonmutating set }
    Show on GitHub
  • bin Extension method

    Undocumented

    Declaration

    Swift

    @inlinable
var bin: GtkBin { get }
    Show on GitHub