MenuShellProtocol

public protocol MenuShellProtocol : ContainerProtocol

A GtkMenuShell is the abstract base class used to derive the GtkMenu and GtkMenuBar subclasses.

A GtkMenuShell is a container of GtkMenuItem objects arranged in a list which can be navigated, selected, and activated by the user to perform application functions. A GtkMenuItem can have a submenu associated with it, allowing for nested hierarchical menus.

Terminology

A menu item can be “selected”, this means that it is displayed in the prelight state, and if it has a submenu, that submenu will be popped up.

A menu is “active” when it is visible onscreen and the user is selecting from it. A menubar is not active until the user clicks on one of its menuitems. When a menu is active, passing the mouse over a submenu will pop it up.

There is also is a concept of the current menu and a current menu item. The current menu item is the selected menu item that is furthest down in the hierarchy. (Every active menu shell does not necessarily contain a selected menu item, but if it does, then the parent menu shell must also contain a selected menu item.) The current menu is the menu that contains the current menu item. It will always have a GTK grab and receive all key presses.

The MenuShellProtocol protocol exposes the methods and properties of an underlying GtkMenuShell 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 MenuShell. Alternatively, use MenuShellRef 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 GtkMenuShell instance.

    Declaration

    Swift

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

    Typed pointer to the underlying GtkMenuShell instance.

    Default Implementation

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

    Declaration

    Swift

    var menu_shell_ptr: UnsafeMutablePointer<GtkMenuShell>! { get }
    Show on GitHub

  • Required Initialiser for types conforming to MenuShellProtocol

    Declaration

    Swift

    init(raw: UnsafeMutableRawPointer)
    Show on GitHub

MenuShell Class

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

    Declaration

    Swift

    @discardableResult
@inlinable
func bind<Q, T>(property source_property: MenuShellPropertyName, 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 MenuShell property

    Declaration

    Swift

    @inlinable
func get(property: MenuShellPropertyName) -> 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 MenuShell property. Note that this will only have an effect on properties that are writable and not construct-only!

    Declaration

    Swift

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

    Parameters

    property

    the property to get the value for

    Return Value

    the value of the named property

    Show on GitHub

MenuShell signals

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

    Declaration

    Swift

    @discardableResult
@inlinable
func connect(signal s: MenuShellSignalName, 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 MenuShellSignalName signal

    Declaration

    Swift

    @discardableResult
@inlinable
func connect(signal s: MenuShellSignalName, 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

  • An action signal that activates the current menu item within the menu shell.

    Note

    This represents the underlying activate-current signal

    Declaration

    Swift

    @discardableResult
@inlinable
func onActivateCurrent(flags: ConnectFlags = ConnectFlags(0), handler: @escaping (_ unownedSelf: MenuShellRef, _ forceHide: Bool) -> Void) -> Int

    Parameters

    flags

    Flags
    unownedSelf

    Reference to instance of self
    forceHide

    if true, hide the menu after activating the menu item
    handler

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

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

    Declaration

    Swift

    static var activateCurrentSignal: MenuShellSignalName { get }
    Show on GitHub
  • onCancel(flags:handler:) Extension method

    An action signal which cancels the selection within the menu shell. Causes the GtkMenuShell::selection-done signal to be emitted.

    Note

    This represents the underlying cancel signal

    Declaration

    Swift

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

    Parameters

    flags

    Flags
    unownedSelf

    Reference to instance of self
    handler

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

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

    Declaration

    Swift

    static var cancelSignal: MenuShellSignalName { get }
    Show on GitHub
  • onCycleFocus(flags:handler:) Extension method

    A keybinding signal which moves the focus in the given direction.

    Note

    This represents the underlying cycle-focus signal

    Declaration

    Swift

    @discardableResult
@inlinable
func onCycleFocus(flags: ConnectFlags = ConnectFlags(0), handler: @escaping (_ unownedSelf: MenuShellRef, _ direction: DirectionType) -> Void) -> Int

    Parameters

    flags

    Flags
    unownedSelf

    Reference to instance of self
    direction

    the direction to cycle in
    handler

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

    Typed cycle-focus signal for using the connect(signal:) methods

    Declaration

    Swift

    static var cycleFocusSignal: MenuShellSignalName { get }
    Show on GitHub
  • onDeactivate(flags:handler:) Extension method

    This signal is emitted when a menu shell is deactivated.

    Note

    This represents the underlying deactivate signal

    Declaration

    Swift

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

    Parameters

    flags

    Flags
    unownedSelf

    Reference to instance of self
    handler

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

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

    Declaration

    Swift

    static var deactivateSignal: MenuShellSignalName { get }
    Show on GitHub
  • onInsert(flags:handler:) Extension method

    The insert signal is emitted when a new GtkMenuItem is added to a GtkMenuShell. A separate signal is used instead of GtkContaineradd because of the need for an additional position parameter.

    The inverse of this signal is the GtkContainerremoved signal.

    Note

    This represents the underlying insert signal

    Declaration

    Swift

    @discardableResult
@inlinable
func onInsert(flags: ConnectFlags = ConnectFlags(0), handler: @escaping (_ unownedSelf: MenuShellRef, _ child: WidgetRef, _ position: Int) -> Void) -> Int

    Parameters

    flags

    Flags
    unownedSelf

    Reference to instance of self
    child

    the GtkMenuItem that is being inserted
    position

    the position at which the insert occurs
    handler

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

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

    Declaration

    Swift

    static var insertSignal: MenuShellSignalName { get }
    Show on GitHub

  • An keybinding signal which moves the current menu item in the direction specified by direction.

    Note

    This represents the underlying move-current signal

    Declaration

    Swift

    @discardableResult
@inlinable
func onMoveCurrent(flags: ConnectFlags = ConnectFlags(0), handler: @escaping (_ unownedSelf: MenuShellRef, _ direction: MenuDirectionType) -> Void) -> Int

    Parameters

    flags

    Flags
    unownedSelf

    Reference to instance of self
    direction

    the direction to move
    handler

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

    Typed move-current signal for using the connect(signal:) methods

    Declaration

    Swift

    static var moveCurrentSignal: MenuShellSignalName { get }
    Show on GitHub

  • The move-selected signal is emitted to move the selection to another item.

    Note

    This represents the underlying move-selected signal

    Declaration

    Swift

    @discardableResult
@inlinable
func onMoveSelected(flags: ConnectFlags = ConnectFlags(0), handler: @escaping (_ unownedSelf: MenuShellRef, _ distance: Int) -> Bool) -> Int

    Parameters

    flags

    Flags
    unownedSelf

    Reference to instance of self
    distance

    +1 to move to the next item, -1 to move to the previous
    handler

    true to stop the signal emission, false to continue Run the given callback whenever the moveSelected signal is emitted
    Show on GitHub
  • moveSelectedSignal Extension method

    Typed move-selected signal for using the connect(signal:) methods

    Declaration

    Swift

    static var moveSelectedSignal: MenuShellSignalName { get }
    Show on GitHub

  • This signal is emitted when a selection has been completed within a menu shell.

    Note

    This represents the underlying selection-done signal

    Declaration

    Swift

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

    Parameters

    flags

    Flags
    unownedSelf

    Reference to instance of self
    handler

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

    Typed selection-done signal for using the connect(signal:) methods

    Declaration

    Swift

    static var selectionDoneSignal: MenuShellSignalName { 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::take-focus signal

    Declaration

    Swift

    @discardableResult
@inlinable
func onNotifyTakeFocus(flags: ConnectFlags = ConnectFlags(0), handler: @escaping (_ unownedSelf: MenuShellRef, _ 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 notifyTakeFocus signal is emitted
    Show on GitHub
  • notifyTakeFocusSignal Extension method

    Typed notify::take-focus signal for using the connect(signal:) methods

    Declaration

    Swift

    static var notifyTakeFocusSignal: MenuShellSignalName { get }
    Show on GitHub

MenuShell Class: MenuShellProtocol extension (methods and fields)

  • Activates the menu item within the menu shell.

    Declaration

    Swift

    @inlinable
func activateItem<WidgetT>(menuItem: WidgetT, forceDeactivate: Bool) where WidgetT : WidgetProtocol
    Show on GitHub
  • append(child:) Extension method

    Adds a new GtkMenuItem to the end of the menu shell’s item list.

    Declaration

    Swift

    @inlinable
func append<MenuItemT>(child: MenuItemT) where MenuItemT : MenuItemProtocol
    Show on GitHub

  • Establishes a binding between a GtkMenuShell and a GMenuModel.

    The contents of shell are removed and then refilled with menu items according to model. When model changes, shell is updated. Calling this function twice on shell with different model will cause the first binding to be replaced with a binding to the new model. If model is nil then any previous binding is undone and all children are removed.

    with_separators determines if toplevel items (eg: sections) have separators inserted between them. This is typically desired for menus but doesn’t make sense for menubars.

    If action_namespace is non-nil then the effect is as if all actions mentioned in the model have their names prefixed with the namespace, plus a dot. For example, if the action “quit” is mentioned and action_namespace is “app” then the effective action name is “app.quit”.

    This function uses GtkActionable to define the action name and target values on the created menu items. If you want to use an action group other than “app” and “win”, or if you want to use a GtkMenuShell outside of a GtkApplicationWindow, then you will need to attach your own action group to the widget hierarchy using gtk_widget_insert_action_group(). As an example, if you created a group with a “quit” action and inserted it with the name “mygroup” then you would use the action name “mygroup.quit” in your GMenuModel.

    For most cases you are probably better off using gtk_menu_new_from_model() or gtk_menu_bar_new_from_model() or just directly passing the GMenuModel to gtk_application_set_app_menu() or gtk_application_set_menubar().

    Declaration

    Swift

    @inlinable
func bind(model: GIO.MenuModelRef? = nil, actionNamespace: UnsafePointer<gchar>? = nil, with separators: Bool)
    Show on GitHub

  • Establishes a binding between a GtkMenuShell and a GMenuModel.

    The contents of shell are removed and then refilled with menu items according to model. When model changes, shell is updated. Calling this function twice on shell with different model will cause the first binding to be replaced with a binding to the new model. If model is nil then any previous binding is undone and all children are removed.

    with_separators determines if toplevel items (eg: sections) have separators inserted between them. This is typically desired for menus but doesn’t make sense for menubars.

    If action_namespace is non-nil then the effect is as if all actions mentioned in the model have their names prefixed with the namespace, plus a dot. For example, if the action “quit” is mentioned and action_namespace is “app” then the effective action name is “app.quit”.

    This function uses GtkActionable to define the action name and target values on the created menu items. If you want to use an action group other than “app” and “win”, or if you want to use a GtkMenuShell outside of a GtkApplicationWindow, then you will need to attach your own action group to the widget hierarchy using gtk_widget_insert_action_group(). As an example, if you created a group with a “quit” action and inserted it with the name “mygroup” then you would use the action name “mygroup.quit” in your GMenuModel.

    For most cases you are probably better off using gtk_menu_new_from_model() or gtk_menu_bar_new_from_model() or just directly passing the GMenuModel to gtk_application_set_app_menu() or gtk_application_set_menubar().

    Declaration

    Swift

    @inlinable
func bind<MenuModelT>(model: MenuModelT?, actionNamespace: UnsafePointer<gchar>? = nil, with separators: Bool) where MenuModelT : MenuModelProtocol
    Show on GitHub
  • cancel() Extension method

    Cancels the selection within the menu shell.

    Declaration

    Swift

    @inlinable
func cancel()
    Show on GitHub
  • deactivate() Extension method

    Deactivates the menu shell.

    Typically this results in the menu shell being erased from the screen.

    Declaration

    Swift

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

    Deselects the currently selected item from the menu shell, if any.

    Declaration

    Swift

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

    Gets the parent menu shell.

    The parent menu shell of a submenu is the GtkMenu or GtkMenuBar from which it was opened up.

    Declaration

    Swift

    @inlinable
func getParentShell() -> WidgetRef!
    Show on GitHub
  • getSelectedItem() Extension method

    Gets the currently selected item.

    Declaration

    Swift

    @inlinable
func getSelectedItem() -> WidgetRef!
    Show on GitHub
  • getTakeFocus() Extension method

    Returns true if the menu shell will take the keyboard focus on popup.

    Declaration

    Swift

    @inlinable
func getTakeFocus() -> Bool
    Show on GitHub
  • insert(child:position:) Extension method

    Adds a new GtkMenuItem to the menu shell’s item list at the position indicated by position.

    Declaration

    Swift

    @inlinable
func insert<WidgetT>(child: WidgetT, position: Int) where WidgetT : WidgetProtocol
    Show on GitHub
  • prepend(child:) Extension method

    Adds a new GtkMenuItem to the beginning of the menu shell’s item list.

    Declaration

    Swift

    @inlinable
func prepend<WidgetT>(child: WidgetT) where WidgetT : WidgetProtocol
    Show on GitHub

  • Select the first visible or selectable child of the menu shell; don’t select tearoff items unless the only item is a tearoff item.

    Declaration

    Swift

    @inlinable
func selectFirst(searchSensitive: Bool)
    Show on GitHub
  • selectItem(menuItem:) Extension method

    Selects the menu item from the menu shell.

    Declaration

    Swift

    @inlinable
func selectItem<WidgetT>(menuItem: WidgetT) where WidgetT : WidgetProtocol
    Show on GitHub
  • set(takeFocus:) Extension method

    If take_focus is true (the default) the menu shell will take the keyboard focus so that it will receive all keyboard events which is needed to enable keyboard navigation in menus.

    Setting take_focus to false is useful only for special applications like virtual keyboard implementations which should not take keyboard focus.

    The take_focus state of a menu or menu bar is automatically propagated to submenus whenever a submenu is popped up, so you don’t have to worry about recursively setting it for your entire menu hierarchy. Only when programmatically picking a submenu and popping it up manually, the take_focus property of the submenu needs to be set explicitly.

    Note that setting it to false has side-effects:

    If the focus is in some other app, it keeps the focus and keynav in the menu doesn’t work. Consequently, keynav on the menu will only work if the focus is on some toplevel owned by the onscreen keyboard.

    To avoid confusing the user, menus with take_focus set to false should not display mnemonics or accelerators, since it cannot be guaranteed that they will work.

    See also gdk_keyboard_grab()

    Declaration

    Swift

    @inlinable
func set(takeFocus: Bool)
    Show on GitHub
  • parentShell Extension method

    Gets the parent menu shell.

    The parent menu shell of a submenu is the GtkMenu or GtkMenuBar from which it was opened up.

    Declaration

    Swift

    @inlinable
var parentShell: WidgetRef! { get }
    Show on GitHub
  • selectedItem Extension method

    Gets the currently selected item.

    Declaration

    Swift

    @inlinable
var selectedItem: WidgetRef! { get }
    Show on GitHub
  • takeFocus Extension method

    Returns true if the menu shell will take the keyboard focus on popup.

    Declaration

    Swift

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

    Undocumented

    Declaration

    Swift

    @inlinable
var container: GtkContainer { get }
    Show on GitHub