Next: , Previous: GtkMenuItem, Up: Top

59 GtkMenuShell

A base class for menu objects

59.1 Overview

A <gtk-menu-shell> is the abstract base class used to derive the <gtk-menu> and <gtk-menu-bar> subclasses.

A <gtk-menu-shell> is a container of <gtk-menu-item> objects arranged in a list which can be navigated, selected, and activated by the user to perform application functions. A <gtk-menu-item> can have a submenu associated with it, allowing for nested hierarchical menus.

59.2 Usage

— Class: <gtk-menu-shell>

Derives from <gtk-container>.

This class defines the following slots:

take-focus
A boolean that determines whether the menu grabs the keyboard focus
— Signal on <gtk-menu-shell>: deactivate

This signal is emitted when a menu shell is deactivated.

— Signal on <gtk-menu-shell>: selection-done

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

— Signal on <gtk-menu-shell>: move-current (arg0 <gtk-menu-direction-type>)

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

— Signal on <gtk-menu-shell>: activate-current (arg0 <gboolean>)

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

— Signal on <gtk-menu-shell>: cancel

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

— Signal on <gtk-menu-shell>: cycle-focus (arg0 <gtk-direction-type>)
— Signal on <gtk-menu-shell>: move-selected (arg0 <gint>) ⇒ <gboolean>

undocumented

— Function: gtk-menu-shell-append (self <gtk-menu-shell>) (child <gtk-widget>)
— Method: append

Adds a new <gtk-menu-item> to the end of the menu shell's item list.

menu-shell
a <gtk-menu-shell>.
child
The <gtk-menu-item> to add.
— Function: gtk-menu-shell-prepend (self <gtk-menu-shell>) (child <gtk-widget>)
— Method: prepend

Adds a new <gtk-menu-item> to the beginning of the menu shell's item list.

menu-shell
a <gtk-menu-shell>.
child
The <gtk-menu-item> to add.
— Function: gtk-menu-shell-insert (self <gtk-menu-shell>) (child <gtk-widget>) (position int)
— Method: insert

Adds a new <gtk-menu-item> to the menu shell's item list at the position indicated by position.

menu-shell
a <gtk-menu-shell>.
child
The <gtk-menu-item> to add.
position
The position in the item list where child is added. Positions are numbered from 0 to n-1.
— Function: gtk-menu-shell-deactivate (self <gtk-menu-shell>)
— Method: deactivate

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

menu-shell
a <gtk-menu-shell>.
— Function: gtk-menu-shell-select-item (self <gtk-menu-shell>) (menu_item <gtk-widget>)
— Method: select-item

Selects the menu item from the menu shell.

menu-shell
a <gtk-menu-shell>.
menu-item
The <gtk-menu-item> to select.
— Function: gtk-menu-shell-select-first (self <gtk-menu-shell>) (search_sensitive bool)
— Method: select-first

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

menu-shell
a <gtk-menu-shell>
search-sensitive
if ‘#t’, search for the first selectable menu item, otherwise select nothing if the first item isn't sensitive. This should be ‘#f’ if the menu is being popped up initially.

Since 2.2

— Function: gtk-menu-shell-deselect (self <gtk-menu-shell>)
— Method: deselect

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

menu-shell
a <gtk-menu-shell>.
— Function: gtk-menu-shell-activate-item (self <gtk-menu-shell>) (menu_item <gtk-widget>) (force_deactivate bool)
— Method: activate-item

Activates the menu item within the menu shell.

menu-shell
a <gtk-menu-shell>.
menu-item
The <gtk-menu-item> to activate.
force-deactivate
If TRUE, force the deactivation of the menu shell after the menu item is activated.
— Function: gtk-menu-shell-cancel (self <gtk-menu-shell>)
— Method: cancel

Cancels the selection within the menu shell.

menu-shell
a <gtk-menu-shell>

Since 2.4

— Function: gtk-menu-shell-set-take-focus (self <gtk-menu-shell>) (take_focus bool)
— Method: set-take-focus

If take-focus is ‘#t’ (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 ‘#f’ 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 explicitely.

Note that setting it to ‘#f’ 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 ‘#f’ should not display mnemonics or accelerators, since it cannot be guaranteed that they will work.

See also gdk-keyboard-grab

menu-shell
a <gtk-menu-shell>
take-focus
‘#t’ if the menu shell should take the keyboard focus on popup.

Since 2.8

— Function: gtk-menu-shell-get-take-focus (self <gtk-menu-shell>) ⇒  (ret bool)
— Method: get-take-focus

Returns ‘#t’ if the menu shell will take the keyboard focus on popup.

menu-shell
a <gtk-menu-shell>
ret
‘#t’ if the menu shell will take the keyboard focus on popup.

Since 2.8