gtk.Menu
Prev | The gtk Class Reference | Next

## gtk.Menu

gtk.Menu — a drop down menu widget.

## Synopsis

    class gtk.Menu(gtk.MenuShell):
        gtk.Menu()
        def popup(parent_menu_shell, parent_menu_item, func, button, activate_time, data=None)
        def reposition()
        def popdown()
        def get_active()
        def set_active(index)
        def set_accel_group(accel_group)
        def get_accel_group()
        def set_accel_path(accel_path)
        def get_accel_path()
        def attach_to_widget(attach_widget, detach_func)
        def detach()
        def get_attach_widget()
        def set_tearoff_state(torn_off)
        def get_tearoff_state()
        def set_title(title)
        def get_title()
        def reorder_child(child, position)
        def set_screen(screen)
        def attach(child, left_attach, right_attach, top_attach, bottom_attach)
        def set_monitor(monitor_num)
        def get_monitor()
        def set_reserve_toggle_size(reserve_toggle_size)
        def get_reserve_toggle_size()

## Ancestry

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

## Implemented Interfaces

`gtk.Menu` implements `gtk.Buildable`

## gtk.Menu Properties

gtk.Object Properties

gtk.Widget Properties

gtk.Container Properties

gtk.MenuShell Properties

"accel-group" | Read/Write | The accel group holding accelerators for the menu. Available in GTK+ 2.14.
"accel-path" | Read/Write | An accel path used to conveniently construct accel paths of child items. Default value: `None`. Available in GTK+ 2.14.
"active" | Read/Write | The index of the currently selected menu item, or -1 if no menu item is selected. Allowed values: >= -1. Default value: -1. Available in GTK+ 2.14.
"attach-widget" | Read/Write | The widget the menu is attached to. Setting this property attaches the menu without a GtkMenuDetachFunc. If you need to use a detacher, use `gtk.Menu.attach_to_widget`() directly. Available in GTK+ 2.14.
"monitor" | Read/Write | The monitor the menu will be popped up on. Allowed values: >= -1. Default value: -1. Available in GTK+ 2.14.
"reserve-toggle-size" | Read/Write | Whether the menu reserves space for toggles and icons, regardless of their actual presence. This property should only be changed from its default value for special-purposes such as tabular menus. Regular menus that are connected to a menu bar or context menus should reserve toggle space for consistency. Default value: `True` Available in GTK+ 2.18.
"tearoff-state" | Read-Write | If `True` the menu is torn-off. Default value: `False`. Available in GTK+ 2.6 and above.
"tearoff-title" | Read-Write | A title that may be displayed by the window manager when this menu is torn-off. Default value: "".

## gtk.Menu Style Properties

gtk.Widget Style Properties

### Note

These properties are available in GTK+ 2.4 and above.

"arrow-placement" | Read | When the menu is a submenu, position it this number of pixels offset horizontally. Default value: `gtk.ARROWS_BOTH`.
"arrow-scaling" | Read | Arbitrary constant to scale down the size of the scroll arrow. Allowed values: [0,1]. Default value: 0.7
"double-arrows" | Read | When scrolling, always show both arrows. Default value: `True`
"horizontal-offset" | Read | When the menu is a submenu, position it this number of pixels offset horizontally. Default value: -2.
"horizontal-padding" | Read | Extra space at the left and right edges of the menu
"vertical-offset" | Read | When the menu is a submenu, position it this number of pixels offset vertically. Default value: 0.
"vertical-padding" | Read | Extra space at the top and bottom of the menu. Allowed values: >= 0. Default value: 1.

## gtk.Menu Child Properties

### Note

These properties are available in GTK+ 2.4 and above.

"bottom-attach" | Read-Write | The row number to attach the bottom of the child to. Allowed values: >= -1. Default value: -1.
"left-attach" | Read-Write | The column number to attach the left side of the child to. Allowed values: >= -1. Default value: -1.
"right-attach" | Read-Write | The column number to attach the right side of the child to. Allowed values: >= -1. Default value: -1.
"top-attach" | Read-Write | The row number to attach the top of the child to. Allowed values: >= -1. Default value: -1.

## gtk.Menu Signal Prototypes

gobject.GObject Signal Prototypes

gtk.Object Signal Prototypes

gtk.Widget Signal Prototypes

gtk.Container Signal Prototypes

gtk.MenuShell Signal Prototypes

"move-scroll" | `def callback(`menu`, `type`, `user_param1`, `...`)`

## Description

A `gtk.Menu` is a `gtk.MenuShell` that implements a drop down menu consisting of a list of `gtk.MenuItem` objects which can be navigated and activated by the user to perform application functions. A `gtk.Menu` is most commonly dropped down by activating a `gtk.MenuItem` in a `gtk.MenuBar` or popped up by activating a `gtk.MenuItem` in another `gtk.Menu`. A `gtk.Menu` can also be popped up by activating a `gtk.OptionMenu`. Other composite widgets such as the `gtk.Notebook` can pop up a `gtk.Menu` as well. Applications can display a `gtk.Menu` as a popup menu by calling the `popup`() method.

## Constructor

        gtk.Menu()

Returns : | a `gtk.Menu` widget

Creates a new `gtk.Menu` widget.

## Methods

### gtk.Menu.popup

        def popup(parent_menu_shell, parent_menu_item, func, button, activate_time, data=None)

`parent_menu_shell` : | the menu shell containing the triggering menu item or `None`.
`parent_menu_item` : | the menu item whose activation triggered the popup or `None`.
`func` : | a user supplied function used to position the menu or `None`.
`button` : | the mouse button which was pressed to initiate the event.
`activate_time` : | the time at which the activation event occurred.
`data` : | optional data to be passed to `func`

The `popup`() method displays a menu and makes it available for selection. Applications can use this function to display context-sensitive menus, and will typically supply `None` for the `parent_menu_shell`, `parent_menu_item` and `func` parameters. The default menu positioning function will position the menu at the current pointer position. The `button` and `activate_time` values should be the mouse button that was pressed to trigger the menu popup and the time the button was pressed. These values can usually be retrieved from the "button_press_event".

The signature of `func` is:

      def func(menu, user_data):

where `user_data` is `data` if not `None`. `func` should return a 3-tuple containing the x and y coordinates of the position to draw the menu and a boolean that, if `True`, indicates that the menu should be pushed in to be completely inside the screen instead of just clamped to the size of the screen.

### Note

Prior to PyGTK 2.10 this method did not accept the `data` parameter and the signature of `func` was:

      def func(menu, user_data):

### gtk.Menu.reposition

        def reposition()

The `reposition`() method repositions the menu on the screen according to the internal position function.

### gtk.Menu.popdown

        def popdown()

The `popdown`() method removes the menu from the screen.

### gtk.Menu.get_active

        def get_active()

Returns : | the `gtk.MenuItem` that was last selected in the menu. If a selection has not yet been made, the first menu item is selected.

The `get_active`() method returns the selected menu item from the menu. This is used by the `gtk.OptionMenu`.

### gtk.Menu.set_active

        def set_active(index)

`index` : | the index of the menu item to select. Index values start from 0.

The `set_active`() method selects the menu item within the menu at the location specified by `index`. This is used by the `gtk.OptionMenu` and is not useful for applications.

### gtk.Menu.set_accel_group

        def set_accel_group(accel_group)

`accel_group` : | a `gtk.AccelGroup`

The `set_accel_group`() method associates the `gtk.AccelGroup` specified by `accel_group` with the menu. The accelerator group should also be added to all windows using this menu by calling the `gtk.Window.add_accel_group`() method.

### gtk.Menu.get_accel_group

        def get_accel_group()

Returns : | the `gtk.AccelGroup` associated with the menu.

The `get_accel_group`() method returns the `gtk.AccelGroup` that holds the global accelerators for the menu.

### gtk.Menu.set_accel_path

        def set_accel_path(accel_path)

`accel_path` : | a valid accelerator path

The `set_accel_path`() method sets an accelerator path (specified by `accel_path`) for this menu to be used to construct accelerator paths for its menu items. This is a convenience method used to avoid calling the `gtk.MenuItem.set_accel_path`() method on each menu item that should support runtime user changeable accelerators. Instead, by just calling `set_accel_path`() on their parent, each menu item of this menu, that contains a label describing its purpose, automatically gets an accel path assigned. For example, calling:

      menu.set_accel_path("<main>/File")

for a menu containing menu items "New" and "Exit", will assign its items the accel paths: `"<main>/File/New"` and `"<main>/File/Exit"`. Assigning accel paths to menu items enables the user to change their accelerators at runtime.

### gtk.Menu.get_accel_path

        def get_accel_path()

Returns : | the accelerator path set on the menu.

### Note

This method is available in PyGTK 2.14 and above.

The `get_accel_path`() method returns the accelerator path set on the menu.

### gtk.Menu.attach_to_widget

        def attach_to_widget(attach_widget, detach_func)

`attach_widget` : | the widget that the menu will be attached to.
`detach_func` : | the user supplied callback function that will be called when the menu calls the `detach`() method.

The `attach_to_widget`() method attaches the menu to the widget specified by `attach_widget` and provides a callback function specified by `detach_func` that will be invoked when the menu calls the `detach`() method during its destruction. Attaching a menu to a widget associates the menu with a widget similar to setting a parent. This is mainly used for associating popup menus with a widget and a submenu with a menuitem.

The signature of `detach` is:

    def detach_cb(menu, widget):

where `menu` is the menu being detached and `widget` is the `attach_widget`.

### Note

For historical reasons, arguments for `detach` callback are swapped compared to GTK+ C API.

### gtk.Menu.detach

        def detach()

The `detach`() method detaches the menu from the widget to which it had been attached. See `attach_to_widget`().

### gtk.Menu.get_attach_widget

        def get_attach_widget()

Returns : | the widget that the menu is attached to.

The `get_attach_widget`() method returns the `gtk.Widget` that the menu is attached to.

### gtk.Menu.set_tearoff_state

        def set_tearoff_state(torn_off)

`torn_off` : | If `True`, the menu is displayed as a tearoff menu.

The `set_tearoff_state`() method sets the tearoff state of the menu to the value of `torn_off`. If `torn_off` is `True` the menu is displayed as a tearoff menu; if `torn_off` is `False` the menu is displayed as a drop down menu which persists as long as the menu is active.

### gtk.Menu.get_tearoff_state

        def get_tearoff_state()

Returns : | `True` if the menu is currently torn off.

The `get_tearoff_state`() method returns whether the menu is torn off. See `set_tearoff_state`().

### gtk.Menu.set_title

        def set_title(title)

`title` : | a string containing the title for the menu.

The `set_title`() method sets the title text (from the value of `title`) to be used for the menu when it is shown as a tearoff menu.

### gtk.Menu.get_title

        def get_title()

Returns : | the title of the menu, or `None` if the menu has no title set on it.

The `get_title`() method returns the title of the menu or `None` of no title is set. See `set_title`().

### gtk.Menu.reorder_child

        def reorder_child(child, position)

`child` : | the `gtk.MenuItem` to move.
`position` : | the new position to place child. Positions are numbered starting from 0

The `reorder_child`() method moves the menuitem specified by `child` to a new position within the menu specified by `position`.

### gtk.Menu.set_screen

        def set_screen(screen)

`screen` : | a `gtk.gdk.Screen`, or `None` if the screen should be determined by the widget the menu is attached to.

### Note

This method is available in PyGTK 2.2 and above.

The `set_screen`() method sets the `gtk.gdk.Screen` specified by `screen` on which the menu will be displayed. If `screen` is `None` the screen is determined by the widget that the menu is attached to.

### gtk.Menu.attach

        def attach(child, left_attach, right_attach, top_attach, bottom_attach)

`child` : | a `gtk.MenuItem`.
`left_attach` : | The column number to attach the left side of the item to.
`right_attach` : | The column number to attach the right side of the item to.
`top_attach` : | The row number to attach the top of the item to.
`bottom_attach` : | The row number to attach the bottom of the item to.

### Note

This method is available in PyGTK 2.4 and above.

The `attach`() method adds a new `gtk.MenuItem` specified by `child` to a (table) menu. The number of 'cells' that an item will occupy is specified by `left_attach`, `right_attach`, `top_attach` and `bottom_attach`. These each represent the leftmost, rightmost, uppermost and lower column and row numbers of the table. (Columns and rows are indexed from zero).

Note that this function is not related to the `detach()` method.

### gtk.Menu.set_monitor

        def set_monitor(monitor_num)

`monitor_num` : | the number of the monitor on which the menu should be popped up

### Note

This method is available in PyGTK 2.4 and above.

The `set_monitor`() method informs `GTK`+ on which monitor a menu should be popped up. See the `gtk.gdk.Screen.get_monitor_geometry()` method for more information.

This method should be called from a menu positioning function if the menu should not appear on the same monitor as the pointer. This information can't be reliably inferred from the coordinates returned by a menu positioning function, since, for very long menus, these coordinates may extend beyond the monitor boundaries or even the screen boundaries.

### gtk.Menu.get_monitor

        def get_monitor()

Returns : | the number of the monitor on which the menu should be popped up or -1, if no monitor has been set

### Note

This method is available in PyGTK 2.14 and above.

The `get_monitor`() method returns the number of the monitor on which to show the menu.

### gtk.Menu.set_reserve_toggle_size

        def set_reserve_toggle_size(reserve_toggle_size)

`reserve_toggle_size` : | `True` to reserve size for toggles.

### Note

This method is available in PyGTK 2.22 and above.

The `set_reserve_toggle_size`() method sets whether the menu should reserve space for drawing toggles or icons, regardless of their actual presence.

### gtk.Menu.get_reserve_toggle_size

        def get_reserve_toggle_size()

Returns : | Whether the menu reserves toggle space.

### Note

This method is available in PyGTK 2.22 and above.

The `get_reserve_toggle_size`() method returns whether the menu reserves space for toggles and icons, regardless of their actual presence.

## Signals

### The "move_scroll" gtk.Menu Signal

        def callback(menu, type, user_param1, ...)

`menu` : | the menu that received the signal
`type` : | the type of scroll that is requested
`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.2 and above.

The "move_scroll" signal is emitted when the user attempts to scroll the menu. `type` should be one of the GTK Scroll Step Constants.

Prev | Up | Next
gtk.ListStore | Home | gtk.MenuBar