gtk.MenuShell
Prev | The gtk Class Reference | Next

## gtk.MenuShell

gtk.MenuShell — a base class for menu objects.

## Synopsis

    class gtk.MenuShell(gtk.Container):
        def append(child)
        def prepend(child)
        def insert(child, position)
        def deactivate()
        def select_item(menu_item)
        def deselect()
        def activate_item(menu_item, force_deactivate)
        def select_first(search_sensitive)
        def cancel()
        def set_take_focus(take_focus)
        def get_take_focus()

## Ancestry

    +-- gobject.GObject
      +-- gtk.Object
        +-- gtk.Widget
          +-- gtk.Container
            +-- gtk.MenuShell

## Implemented Interfaces

`gtk.MenuShell` implements `gtk.Buildable`

## gtk.MenuShell Properties

gtk.Object Properties

gtk.Widget Properties

gtk.Container Properties

"take-focus" | Read-Write | If `True` the menu and its submenus grab the keyboard focus on popup. Default value: `True`. Available in GTK+ 2.8 and above.

## gtk.MenuShell Style Properties

gtk.Widget Style Properties

## gtk.MenuShell Signal Prototypes

gobject.GObject Signal Prototypes

gtk.Object Signal Prototypes

gtk.Widget Signal Prototypes

gtk.Container Signal Prototypes

"activate-current" | `def callback(`menushell`, `force_hide`, `user_param1`, `...`)`
"cancel" | `def callback(`menushell`, `user_param1`, `...`)`
"cycle-focus" | `def callback(`menushell`, `direction`, `user_param1`, `...`)`
"deactivate" | `def callback(`menushell`, `user_param1`, `...`)`
"move-current" | `def callback(`menushell`, `direction`, `user_param1`, `...`)`
"move-selected" | `def callback(`menushell`, `distance`, `user_param1`, `...`)`
"selection-done" | `def callback(`menushell`, `user_param1`, `...`)`

## Description

A `gtk.MenuShell` is the abstract base class used to derive the `gtk.Menu` and `gtk.MenuBar` subclasses. A `gtk.MenuShell` is a container of `gtk.MenuItem` objects arranged in a list which can be navigated, selected, and activated by the user to perform application functions. A `gtk.MenuItem` can have a submenu associated with it, allowing for nested hierarchical menus.

## Methods

### gtk.MenuShell.append

        def append(child)

`child` : | The `gtk.MenuItem` to add.

The `append`() method adds a new `gtk.MenuItem` specified by `child` to the end of the menu shell's item list.

### gtk.MenuShell.prepend

        def prepend(child)

`child` : | The `gtk.MenuItem` to add.

The `prepend`() method adds a new `gtk.MenuItem` specified by `child` to the beginning of the menu shell's item list.

### gtk.MenuShell.insert

        def insert(child, position)

`child` : | The `gtk.MenuItem` to add.
`position` : | The position in the item list where child should be added. Positions are numbered starting from 0.

The `insert`() method adds a new `gtk.MenuItem` specified by `child` to the menu shell's item list at the position specified by `position`.

### gtk.MenuShell.deactivate

        def deactivate()

The `deactivate`() method deactivates the menu shell. Typically this results in the menu shell being removed from the screen.

### gtk.MenuShell.select_item

        def select_item(menu_item)

`menu_item` : | The `gtk.MenuItem` to select.

The `select_item`() method selects the menu item specified by `menu_item` from the menu shell.

### gtk.MenuShell.deselect

        def deselect()

The `deselect`() method deselects the currently selected item from the menu shell, if any.

### gtk.MenuShell.activate_item

        def activate_item(menu_item, force_deactivate)

`menu_item` : | The `gtk.MenuItem` to activate.
`force_deactivate` : | If `True`, force the deactivation of the menu shell after the menu item is activated.

The `activate_item`() method activates the menu item specified by`menu_item`. If `force_deactivate` is `True` the menushell is forcibly deactivated after`menu_item` is activated.

### gtk.MenuShell.select_first

        def select_first(search_sensitive)

`search_sensitive` : | if `True`, search for the first selectable menu item, otherwise select nothing if the first item isn't sensitive.

### Note

This method is available in PyGTK 2.2 and above.

The `select_first`() method selects the first visible or selectable child of the menu shell if `search_sensitive` is `True`. Don't select tearoff items unless the only item is a tearoff item. If `search_sensitive` is `False` select nothing if the first item isn't sensitive. `search_sensitive` should be `False` if the menu is being popped up initially.

### gtk.MenuShell.cancel

        def cancel()

### Note

This method is available in PyGTK 2.4 and above.

The `cancel`() method cancels the selection within the menu shell.

### gtk.MenuShell.set_take_focus

        def set_take_focus(take_focus)

`take_focus` : | if `True`, the menu shell should take the keyboard focus on popup.

### Note

This method is available in PyGTK 2.8 and above.

The `set_take_focus`() method sets the "take-focus" property to the value of `take_focus`. If `take_focus` is `True` the menu shell will take the keyboard focus so that it will receive all keyboard events to enable keyboard navigation in menus.

Setting the "take-focus" property 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, should the "take-focus" property of the submenu 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 keyboard navigation in the menu doesn't work. Consequently, keyboard navigation 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 the "take-focus" property set to `False` should not display mnemonics or accelerators, since they may not work.

Also see the `gtk.gdk.keyboard_grab`() function for more information.

### gtk.MenuShell.get_take_focus

        def get_take_focus()

Returns : | `True` if the men shell will take keyboard foucs on popup.

### Note

This method is available in PyGTK 2.8 and above.

The `get_take_focus`() method returns the value of the "take-focus" property. See the `set_take_focus`() method for more information.

## Signals

### The "activate-current" gtk.MenuShell Signal

        def callback(menushell, force_hide, user_param1, ...)

`menushell` : | the menushell that received the signal
`force_hide` : | if True, hide the menu after activating the menu item.
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)

The "activate-current" signal is emitted to activate the current menu item in the menushell.

### The "cancel" gtk.MenuShell Signal

        def callback(menushell, user_param1, ...)

`menushell` : | the menushell that received the signal
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)

The "cancel" signal is emitted to cancel the selection in the menushell. Also causes the "selection-done" signal to be emitted.

### The "cycle-focus" gtk.MenuShell Signal

        def callback(menushell, user_param1, ...)

`menushell` : | the menushell that received the signal
`direction` : | the direction to cycle the focus; one of: `gtk.DIR_TAB_FORWARD`, `gtk.DIR_TAB_BACKWARD`, `gtk.DIR_UP`, `gtk.DIR_DOWN`, `gtk.DIR_LEFT` or `gtk.DIR_RIGHT`
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)

The "cycle-focus" signal is emitted when an action occurs requesting the focus move to the next menubar.

### The "deactivate" gtk.MenuShell Signal

        def callback(menushell, user_param1, ...)

`menushell` : | the menushell that received the signal
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)

The "deactivate" signal is emitted when the menushell is deactivated.

### The "move-current" gtk.MenuShell Signal

        def callback(menushell, direction, user_param1, ...)

`menushell` : | the menushell that received the signal
`direction` : | the direction to move; one of: `gtk.MENU_DIR_PARENT`, `gtk.MENU_DIR_CHILD`, `gtk.MENU_DIR_NEXT` or `gtk.MENU_DIR_PREV`
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)

The "move-current" signal is emitted when the current menu item is to be moved in the direction specified by `direction` which is one of:

`gtk.MENU_DIR_PARENT` | To the parent menu shell.
`gtk.MENU_DIR_CHILD` | To the submenu, if any, associated with the item.
`gtk.MENU_DIR_NEXT` | To the next menu item.
`gtk.MENU_DIR_PREV` | To the previous menu item.

### The "move-selected" gtk.MenuShell Signal

        def callback(menushell, distance, user_param1, ...)

`menushell` : | the menushell that received the signal
`distance` : | +1 to move to the next item, -1 to move to the previous
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)

### Note

This signal is available in GTK+ 2.12 and above.

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

### The "selection-done" gtk.MenuShell Signal

        def callback(menushell, user_param1, ...)

`menushell` : | the menushell that received the signal
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)

The "selection-done" signal is emitted when a selection has been completed within a menu shell.

Prev | Up | Next
gtk.MenuItem | Home | gtk.MenuToolButton