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/WriteThe accel group holding accelerators for the menu. Available in GTK+ 2.14.
"accel-path"Read/WriteAn accel path used to conveniently construct accel paths of child items. Default value: None. Available in GTK+ 2.14.
"active"Read/WriteThe 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/WriteThe 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/WriteThe monitor the menu will be popped up on. Allowed values: >= -1. Default value: -1. Available in GTK+ 2.14.
"reserve-toggle-size"Read/WriteWhether 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-WriteIf True the menu is torn-off. Default value: False. Available in GTK+ 2.6 and above.
"tearoff-title"Read-WriteA 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"ReadWhen the menu is a submenu, position it this number of pixels offset horizontally. Default value: gtk.ARROWS_BOTH.
"arrow-scaling"ReadArbitrary constant to scale down the size of the scroll arrow. Allowed values: [0,1]. Default value: 0.7
"double-arrows"ReadWhen scrolling, always show both arrows. Default value: True
"horizontal-offset"ReadWhen the menu is a submenu, position it this number of pixels offset horizontally. Default value: -2.
"horizontal-padding"ReadExtra space at the left and right edges of the menu
"vertical-offset"ReadWhen the menu is a submenu, position it this number of pixels offset vertically. Default value: 0.
"vertical-padding"ReadExtra 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-WriteThe row number to attach the bottom of the child to. Allowed values: >= -1. Default value: -1.
"left-attach"Read-WriteThe column number to attach the left side of the child to. Allowed values: >= -1. Default value: -1.
"right-attach"Read-WriteThe column number to attach the right side of the child to. Allowed values: >= -1. Default value: -1.
"top-attach"Read-WriteThe 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.