path: root/docs/reference/pygtk-gtkmenu.xml

<?xml version="1.0" standalone="no"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
    "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">

<refentry id="class-gtkmenu">
  <refnamediv>
    <refname>gtk.Menu</refname>
    <refpurpose>a drop down menu widget.</refpurpose>
  </refnamediv>

  <refsect1>
    <title>Synopsis</title>

    <classsynopsis language="python">
      <ooclass><classname>gtk.Menu</classname></ooclass>
      <ooclass><classname><link
linkend="class-gtkmenushell">gtk.MenuShell</link></classname></ooclass>
      <constructorsynopsis language="python">
	<methodname><link
linkend="constructor-gtkmenu">gtk.Menu</link></methodname>
	<methodparam></methodparam>  </constructorsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkmenu--popup">popup</link></methodname>
	<methodparam><parameter
		       role="keyword">parent_menu_shell</parameter></methodparam>
	<methodparam><parameter
		       role="keyword">parent_menu_item</parameter></methodparam>
	<methodparam><parameter
		       role="keyword">func</parameter></methodparam>
	<methodparam><parameter
		       role="keyword">button</parameter></methodparam>
	<methodparam><parameter
		       role="keyword">activate_time</parameter></methodparam>
	<methodparam><parameter
		       role="keyword">data</parameter><initializer>None</initializer></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkmenu--reposition">reposition</link></methodname>
	<methodparam></methodparam>  </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkmenu--popdown">popdown</link></methodname>
	<methodparam></methodparam>  </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkmenu--get-active">get_active</link></methodname>
	<methodparam></methodparam>  </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkmenu--set-active">set_active</link></methodname>
	<methodparam><parameter
		       role="keyword">index</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkmenu--set-accel-group">set_accel_group</link></methodname>
	<methodparam><parameter
		       role="keyword">accel_group</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkmenu--get-accel-group">get_accel_group</link></methodname>
	<methodparam></methodparam>  </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkmenu--set-accel-path">set_accel_path</link></methodname>
	<methodparam><parameter
		       role="keyword">accel_path</parameter></methodparam>
      </methodsynopsis>
      
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtkmenu--get-accel-path">get_accel_path</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>

      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkmenu--attach-to-widget">attach_to_widget</link></methodname>
	<methodparam><parameter
		       role="keyword">attach_widget</parameter></methodparam>
	<methodparam><parameter
		       role="keyword">detach_func</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkmenu--detach">detach</link></methodname>
	<methodparam></methodparam>  </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkmenu--get-attach-widget">get_attach_widget</link></methodname>
	<methodparam></methodparam>  </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkmenu--set-tearoff-state">set_tearoff_state</link></methodname>
	<methodparam><parameter
		       role="keyword">torn_off</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkmenu--get-tearoff-state">get_tearoff_state</link></methodname>
	<methodparam></methodparam>  </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkmenu--set-title">set_title</link></methodname>
	<methodparam><parameter
		       role="keyword">title</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkmenu--get-title">get_title</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkmenu--reorder-child">reorder_child</link></methodname>
	<methodparam><parameter
		       role="keyword">child</parameter></methodparam>
	<methodparam><parameter
		       role="keyword">position</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtkmenu--set-screen">set_screen</link></methodname>
	<methodparam><parameter
		       role="keyword">screen</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtkmenu--attach">attach</link></methodname>
	<methodparam><parameter
		       role="keyword">child</parameter></methodparam>
	<methodparam><parameter
		       role="keyword">left_attach</parameter></methodparam>
	<methodparam><parameter
		       role="keyword">right_attach</parameter></methodparam>
	<methodparam><parameter
		       role="keyword">top_attach</parameter></methodparam>
	<methodparam><parameter
		       role="keyword">bottom_attach</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtkmenu--set-monitor">set_monitor</link></methodname>
	<methodparam><parameter
		       role="keyword">monitor_num</parameter></methodparam>
      </methodsynopsis>
      
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtkmenu--get-monitor">get_monitor</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>

      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkmenu--set-reserve-toggle-size">set_reserve_toggle_size</link></methodname>
        <methodparam><parameter role="keyword">reserve_toggle_size</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkmenu--get-reserve-toggle-size">get_reserve_toggle_size</link></methodname>
        <methodparam></methodparam>
      </methodsynopsis>

    </classsynopsis>

  </refsect1>

  <refsect1>
    <title>Ancestry</title>

<synopsis>+-- <link linkend="class-gobject">gobject.GObject</link>
  +-- <link linkend="class-gtkobject">gtk.Object</link>
    +-- <link linkend="class-gtkwidget">gtk.Widget</link>
      +-- <link linkend="class-gtkcontainer">gtk.Container</link>
        +-- <link linkend="class-gtkmenushell">gtk.MenuShell</link>
          +-- <link linkend="class-gtkmenu">gtk.Menu</link>
</synopsis>

  </refsect1>
  
  <refsect1>
		<title>Implemented Interfaces</title>
		<para>
			<link linkend="class-gtkmenu"><classname>gtk.Menu</classname></link>
			implements 
			<link linkend="class-gtkbuildable"><classname>gtk.Buildable</classname></link>
		</para>
	</refsect1>


  <refsect1 id="properties-gtkmenu">
    <title>gtk.Menu Properties</title>

    <para><link linkend="properties-gtkobject">gtk.Object Properties</link></para>
    <para><link linkend="properties-gtkwidget">gtk.Widget Properties</link></para>
    <para><link linkend="properties-gtkcontainer">gtk.Container Properties</link></para>
    <para><link linkend="properties-gtkmenushell">gtk.MenuShell Properties</link></para>

    <blockquote role="properties">
      <informaltable pgwide="1" frame="none">
	<tgroup cols="3">
	  <colspec column="1" colwidth="1in"/>
	  <colspec column="2" colwidth="1in"/>
	  <colspec column="3" colwidth="4in"/>
	  <tbody>

	    <row valign="top">
	      <entry>"accel-group"</entry>
	      <entry>Read/Write</entry>
	      <entry>The accel group holding accelerators for the menu.
	      Available in GTK+ 2.14.</entry>
	    </row>

	    <row valign="top">
	      <entry>"accel-path"</entry>
	      <entry>Read/Write</entry>
	      <entry>An accel path used to conveniently construct accel paths of
	      child items. Default value: <literal>None</literal>.
	      Available in GTK+ 2.14.</entry>
	    </row>

	    <row valign="top">
	      <entry>"active"</entry>
	      <entry>Read/Write</entry>
	      <entry>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.</entry>
	    </row>

	    <row valign="top">
	      <entry>"attach-widget"</entry>
	      <entry>Read/Write</entry>
	      <entry>The widget the menu is attached to. Setting this property attaches
	      the menu without a GtkMenuDetachFunc. If you need to use a detacher,
	      use <methodname><link linkend="method-gtkmenu--attach-to-widget">gtk.Menu.attach_to_widget</link></methodname>()
	      directly.
	      Available in GTK+ 2.14.</entry>
	    </row>

	    <row valign="top">
	      <entry>"monitor"</entry>
	      <entry>Read/Write</entry>
	      <entry>The monitor the menu will be popped up on.
	      Allowed values: >= -1. Default value: -1.
	      Available in GTK+ 2.14.</entry>
	    </row>

	    <row valign="top">
	      <entry>"reserve-toggle-size"</entry>
	      <entry>Read/Write</entry>
	      <entry>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: <literal>True</literal>
Available in GTK+ 2.18.</entry>
	    </row>

	    <row valign="top">
	      <entry>"tearoff-state"</entry>
	      <entry>Read-Write</entry>
	      <entry>If <literal>True</literal> the menu is torn-off. Default
value: <literal>False</literal>. Available in GTK+ 2.6 and above.</entry>
	    </row>

	    <row valign="top">
	      <entry>"tearoff-title"</entry>
	      <entry>Read-Write</entry>
	      <entry>A title that may be displayed by the window manager
when this menu is torn-off. Default value: "".</entry>
	    </row>

	  </tbody>
	</tgroup>
      </informaltable>
    </blockquote>

  </refsect1>

  <refsect1 id="style-properties-gtkmenu">
    <title>gtk.Menu Style Properties</title>

    <para><link linkend="style-properties-gtkwidget">gtk.Widget Style Properties</link></para>

    <note>
      <para>These properties are available in GTK+ 2.4 and above.</para>
    </note>

    <blockquote role="properties">
      <informaltable pgwide="1" frame="none">
	<tgroup cols="3">
	  <colspec column="1" colwidth="1in"/>
	  <colspec column="2" colwidth="1in"/>
	  <colspec column="3" colwidth="4in"/>
	  <tbody>

      <row valign="top">
	      <entry>"arrow-placement"</entry>
	      <entry>Read</entry>
	      <entry>When the menu is a submenu, position it this number of pixels offset horizontally.
Default value: <literal>gtk.ARROWS_BOTH</literal>.</entry>
Available in GTK+ 2.16 and above.
	    </row>

	    <row valign="top">
	      <entry>"arrow-scaling"</entry>
	      <entry>Read</entry>
	      <entry>Arbitrary constant to scale down the size of the scroll arrow.
Allowed values: [0,1].
Default value: 0.7</entry>
	    </row>

	    <row valign="top">
	      <entry>"double-arrows"</entry>
	      <entry>Read</entry>
	      <entry>When scrolling, always show both arrows.
Default value: <literal>True</literal></entry>
	    </row>

	    <row valign="top">
	      <entry>"horizontal-offset"</entry>
	      <entry>Read</entry>
	      <entry>When the menu is a submenu, position it this number of pixels offset horizontally. Default value: -2.</entry>
	    </row>

      <row valign="top">
        <entry>"horizontal-padding"</entry>
        <entry>Read</entry>
        <entry>Extra space at the left and right edges of the menu</entry>
      </row>

	    <row valign="top">
	      <entry>"vertical-offset"</entry>
	      <entry>Read</entry>
	      <entry>When the menu is a submenu, position it this number of pixels offset vertically. Default value: 0.</entry>
	    </row>

	    <row valign="top">
	      <entry>"vertical-padding"</entry>
	      <entry>Read</entry>
	      <entry>Extra space at the top and bottom of the menu. Allowed values: >= 0. Default value: 1.</entry>
	    </row>

	  </tbody>
	</tgroup>
      </informaltable>
    </blockquote>

  </refsect1>

  <refsect1 id="child-properties-gtkmenu">
    <title>gtk.Menu Child Properties</title>

    <note>
      <para>These properties are available in GTK+ 2.4 and above.</para>
    </note>

    <blockquote role="properties">
      <informaltable pgwide="1" frame="none">
	<tgroup cols="3">
	  <colspec column="1" colwidth="1in"/>
	  <colspec column="2" colwidth="1in"/>
	  <colspec column="3" colwidth="4in"/>
	  <tbody>

	    <row valign="top">
	      <entry>"bottom-attach"</entry>
	      <entry>Read-Write</entry>
	      <entry>The row number to attach the bottom of the child
	      to. Allowed values: >= -1. Default value: -1.</entry>
	    </row>

	    <row valign="top">
	      <entry>"left-attach"</entry>
	      <entry>Read-Write</entry>
	      <entry>The column number to attach the left side of the child
to. Allowed values: >= -1. Default value: -1.</entry>
	    </row>

	    <row valign="top">
	      <entry>"right-attach"</entry>
	      <entry>Read-Write</entry>
	      <entry>The column number to attach the right side of the child
to. Allowed values: >= -1. Default value: -1.</entry>
	    </row>

	    <row valign="top">
	      <entry>"top-attach"</entry>
	      <entry>Read-Write</entry>
	      <entry>The row number to attach the top of the child to. Allowed
values: >= -1. Default value: -1.</entry>
	    </row>

	  </tbody>
	</tgroup>
      </informaltable>
    </blockquote>

  </refsect1>

  <refsect1 id="signal-prototypes-gtkmenu">
    <title>gtk.Menu Signal Prototypes</title>

    <para><link linkend="signal-prototypes-gobject">gobject.GObject Signal Prototypes</link></para>
    <para><link linkend="signal-prototypes-gtkobject">gtk.Object Signal Prototypes</link></para>
    <para><link linkend="signal-prototypes-gtkwidget">gtk.Widget Signal Prototypes</link></para>
    <para><link linkend="signal-prototypes-gtkcontainer">gtk.Container Signal Prototypes</link></para>
    <para><link linkend="signal-prototypes-gtkmenushell">gtk.MenuShell Signal Prototypes</link></para>

    <variablelist>
      <varlistentry>
        <term>"<link linkend="signal-gtkmenu--move-scroll">move-scroll</link>"</term>
        <listitem>
          <methodsynopsis language="python"><methodname>callback</methodname>
            <methodparam><parameter>menu</parameter></methodparam>
            <methodparam><parameter>type</parameter></methodparam>
            <methodparam><parameter>user_param1</parameter></methodparam>
            <methodparam><parameter>...</parameter></methodparam>
          </methodsynopsis>
        </listitem>
      </varlistentry>
    </variablelist>

  </refsect1>

  <refsect1>
    <title>Description</title>

    <para>A <link
linkend="class-gtkmenu"><classname>gtk.Menu</classname></link> is a <link
linkend="class-gtkmenushell"><classname>gtk.MenuShell</classname></link>
that implements a drop down menu consisting of a list of <link
linkend="class-gtkmenuitem"><classname>gtk.MenuItem</classname></link>
objects which can be navigated and activated by the user to perform
application functions. A <link
linkend="class-gtkmenu"><classname>gtk.Menu</classname></link> is most
commonly dropped down by activating a <link
linkend="class-gtkmenuitem"><classname>gtk.MenuItem</classname></link> in a
<link linkend="class-gtkmenubar"><classname>gtk.MenuBar</classname></link>
or popped up by activating a <link
linkend="class-gtkmenuitem"><classname>gtk.MenuItem</classname></link> in
another <link
linkend="class-gtkmenu"><classname>gtk.Menu</classname></link>. A <link
linkend="class-gtkmenu"><classname>gtk.Menu</classname></link> can also be
popped up by activating a <link
linkend="class-gtkoptionmenu"><classname>gtk.OptionMenu</classname></link>.
Other composite widgets such as the <link
linkend="class-gtknotebook"><classname>gtk.Notebook</classname></link> can
pop up a <link
linkend="class-gtkmenu"><classname>gtk.Menu</classname></link> as well.
Applications can display a <link
linkend="class-gtkmenu"><classname>gtk.Menu</classname></link> as a popup
menu by calling the <link
linkend="method-gtkmenu--popup"><methodname>popup</methodname>()</link>
method.</para>

  </refsect1>

  <refsect1 id="constructor-gtkmenu">
    <title>Constructor</title>

    <programlisting><constructorsynopsis language="python">
	<methodname>gtk.Menu</methodname>
	<methodparam></methodparam>  </constructorsynopsis></programlisting>
    <variablelist>
      <varlistentry>
	<term><emphasis>Returns</emphasis>&nbsp;:</term>
	<listitem><simpara>a <link
linkend="class-gtkmenu"><classname>gtk.Menu</classname></link>
widget</simpara></listitem>
      </varlistentry>
    </variablelist>

    <para>Creates a new <link
linkend="class-gtkmenu"><classname>gtk.Menu</classname></link>
widget.</para>

  </refsect1>

  <refsect1>
    <title>Methods</title>

    <refsect2 id="method-gtkmenu--popup">
      <title>gtk.Menu.popup</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>popup</methodname>
	  <methodparam><parameter
			 role="keyword">parent_menu_shell</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">parent_menu_item</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">func</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">button</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">activate_time</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">data</parameter><initializer>None</initializer></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter
role="keyword">parent_menu_shell</parameter>&nbsp;:</term>
	  <listitem><simpara>the menu shell containing the triggering menu
item or <literal>None</literal>.</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter
role="keyword">parent_menu_item</parameter>&nbsp;:</term>
	  <listitem><simpara>the menu item whose activation triggered the
popup or <literal>None</literal>.</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">func</parameter>&nbsp;:</term>
	  <listitem><simpara>a user supplied function used to position the
menu or <literal>None</literal>.</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">button</parameter>&nbsp;:</term>
	  <listitem><simpara>the mouse button which was pressed to initiate
the event. </simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter
role="keyword">activate_time</parameter>&nbsp;:</term>
	  <listitem><simpara>the time at which the activation event
occurred.</simpara></listitem>
	</varlistentry>
 	<varlistentry>
	  <term><parameter
role="keyword">data</parameter>&nbsp;:</term>
	  <listitem><simpara>optional data to be passed to
	  <parameter>func</parameter></simpara></listitem>
	</varlistentry>
     </variablelist>

      <para>The <methodname>popup</methodname>() method displays a menu and
      makes it available for selection. Applications can use this function
      to display context-sensitive menus, and will typically supply
      <literal>None</literal> for the
      <parameter>parent_menu_shell</parameter>,
      <parameter>parent_menu_item</parameter> and
      <parameter>func</parameter> parameters. The default menu positioning
      function will position the menu at the current pointer position. The
      <parameter>button</parameter> and <parameter>activate_time</parameter>
      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".</para>

      <para>The signature of <parameter>func</parameter> is:</para>

      <programlisting>
  def func(menu, user_data):
</programlisting>

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

      <note>
        <para>Prior to PyGTK 2.10 this method did not accept the
        <parameter>data</parameter> parameter and the signature of
        <parameter>func</parameter> was:</para>

        <programlisting>
  def func(menu, user_data):
        </programlisting>
      </note>

    </refsect2>

    <refsect2 id="method-gtkmenu--reposition">
      <title>gtk.Menu.reposition</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>reposition</methodname>
	  <methodparam></methodparam>  </methodsynopsis></programlisting>

      <para>The <methodname>reposition</methodname>() method repositions the
menu on the screen according to the internal position function.</para>

    </refsect2>

    <refsect2 id="method-gtkmenu--popdown">
      <title>gtk.Menu.popdown</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>popdown</methodname>
	  <methodparam></methodparam>  </methodsynopsis></programlisting>

      <para>The <methodname>popdown</methodname>() method removes the menu
from the screen.</para>

    </refsect2>

    <refsect2 id="method-gtkmenu--get-active">
      <title>gtk.Menu.get_active</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_active</methodname>
	  <methodparam></methodparam>  </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>the <link
linkend="class-gtkmenuitem"><classname>gtk.MenuItem</classname></link> that
was last selected in the menu. If a selection has not yet been made, the
first menu item is selected.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>get_active</methodname>() method returns the
selected menu item from the menu. This is used by the <link
linkend="class-gtkoptionmenu"><classname>gtk.OptionMenu</classname></link>.</para>

    </refsect2>

    <refsect2 id="method-gtkmenu--set-active">
      <title>gtk.Menu.set_active</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_active</methodname>
	  <methodparam><parameter
			 role="keyword">index</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">index</parameter>&nbsp;:</term>
	  <listitem><simpara>the index of the menu item to select. Index
values start from 0.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>set_active</methodname>() method selects the
menu item within the menu at the location specified by
<parameter>index</parameter>. This is used by the <link
linkend="class-gtkoptionmenu"><classname>gtk.OptionMenu</classname></link>
and is not useful for applications.</para>

    </refsect2>

    <refsect2 id="method-gtkmenu--set-accel-group">
      <title>gtk.Menu.set_accel_group</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_accel_group</methodname>
	  <methodparam><parameter
			 role="keyword">accel_group</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter
role="keyword">accel_group</parameter>&nbsp;:</term>
	  <listitem><simpara>a <link
linkend="class-gtkaccelgroup"><classname>gtk.AccelGroup</classname></link></simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>set_accel_group</methodname>() method associates
the <link
linkend="class-gtkaccelgroup"><classname>gtk.AccelGroup</classname></link>
specified by <parameter>accel_group</parameter> with the menu. The
accelerator group should also be added to all windows using this menu by
calling the <link
linkend="method-gtkwindow--add-accel-group"><methodname>gtk.Window.add_accel_group</methodname>()</link> 
method.</para>

    </refsect2>

    <refsect2 id="method-gtkmenu--get-accel-group">
      <title>gtk.Menu.get_accel_group</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_accel_group</methodname>
	  <methodparam></methodparam>  </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>the <link
linkend="class-gtkaccelgroup"><classname>gtk.AccelGroup</classname></link>
associated with the menu. </simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>get_accel_group</methodname>() method returns
the <link
linkend="class-gtkaccelgroup"><classname>gtk.AccelGroup</classname></link>
that holds the global accelerators for the menu.</para>

    </refsect2>

    <refsect2 id="method-gtkmenu--set-accel-path">
      <title>gtk.Menu.set_accel_path</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_accel_path</methodname>
	  <methodparam><parameter
			 role="keyword">accel_path</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter
role="keyword">accel_path</parameter>&nbsp;:</term>
	  <listitem><simpara>a valid accelerator path</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>set_accel_path</methodname>() method sets an
accelerator path (specified by <parameter>accel_path</parameter>) for this
menu to be used to construct accelerator paths for its menu items. This is a
convenience method used to avoid calling the <link
linkend="method-gtkmenuitem--set-accel-path"><methodname>gtk.MenuItem.set_accel_path</methodname>()</link> 
method on each menu item that should support runtime user changeable
accelerators. Instead, by just calling <link
linkend="method-gtkmenu--set-accel-path"><methodname>set_accel_path</methodname>()</link> 
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:</para>

      <programlisting>
  menu.set_accel_path("&lt;main&gt;/File")
</programlisting>

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

    </refsect2>

    <refsect2 id="method-gtkmenu--get-accel-path">
      <title>gtk.Menu.get_accel_path</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_accel_path</methodname>
	  <methodparam></methodparam>  </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>the accelerator path set on the menu.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <note>
        <para>This method is available in PyGTK 2.14 and above.</para>
      </note>

      <para>
	The <methodname>get_accel_path</methodname>() method returns
	the accelerator path set on the menu.
      </para>

    </refsect2>

    <refsect2 id="method-gtkmenu--attach-to-widget">
      <title>gtk.Menu.attach_to_widget</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>attach_to_widget</methodname>
	  <methodparam><parameter
			 role="keyword">attach_widget</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">detach_func</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter
role="keyword">attach_widget</parameter>&nbsp;:</term>
	  <listitem><simpara>the widget that the menu will be attached
to.</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter
role="keyword">detach_func</parameter>&nbsp;:</term>
	  <listitem><simpara>the user supplied callback function that will
be called when the menu calls the <link
linkend="method-gtkmenu--detach"><methodname>detach</methodname>()</link>
method.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>attach_to_widget</methodname>() method attaches
the menu to the widget specified by <parameter>attach_widget</parameter> and
provides a callback function specified by <parameter>detach_func</parameter>
that will be invoked when the menu calls the <link
linkend="method-gtkmenu--detach"><methodname>detach</methodname>()</link>
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.</para>

      <para>The signature of <parameter>detach</parameter> is:</para>

      <programlisting>
def detach_cb(menu, widget):
</programlisting>

      <para>where <parameter>menu</parameter> is the
menu being detached and <parameter>widget</parameter> is the
<parameter>attach_widget</parameter>.</para>

      <note>
	<para>For historical reasons, arguments for <parameter>detach</parameter>
	  callback are swapped compared to GTK+ C API.</para>
      </note>

    </refsect2>

    <refsect2 id="method-gtkmenu--detach">
      <title>gtk.Menu.detach</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>detach</methodname>
	  <methodparam></methodparam>  </methodsynopsis></programlisting>

      <para>The <methodname>detach</methodname>() method detaches the menu
from the widget to which it had been attached. See <link
linkend="method-gtkmenu--attach-to-widget"><methodname>attach_to_widget</methodname>()</link>.
</para>

    </refsect2>

    <refsect2 id="method-gtkmenu--get-attach-widget">
      <title>gtk.Menu.get_attach_widget</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_attach_widget</methodname>
	  <methodparam></methodparam>  </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>the widget that the menu is attached
to.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>get_attach_widget</methodname>() method returns
the <link linkend="class-gtkwidget"><classname>gtk.Widget</classname></link>
that the menu is attached to.</para>

    </refsect2>

    <refsect2 id="method-gtkmenu--set-tearoff-state">
      <title>gtk.Menu.set_tearoff_state</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_tearoff_state</methodname>
	  <methodparam><parameter
			 role="keyword">torn_off</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">torn_off</parameter>&nbsp;:</term>
	  <listitem><simpara>If <literal>True</literal>, the menu is
displayed as a tearoff menu.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>set_tearoff_state</methodname>() method sets the
tearoff state of the menu to the value of <parameter>torn_off</parameter>.
If <parameter>torn_off</parameter> is <literal>True</literal> the menu is
displayed as a tearoff menu; if <parameter>torn_off</parameter> is
<literal>False</literal> the menu is displayed as a drop down menu which
persists as long as the menu is active.</para>

    </refsect2>

    <refsect2 id="method-gtkmenu--get-tearoff-state">
      <title>gtk.Menu.get_tearoff_state</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_tearoff_state</methodname>
	  <methodparam></methodparam>  </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara><literal>True</literal> if the menu is
currently torn off.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>get_tearoff_state</methodname>() method returns
whether the menu is torn off. See <link
linkend="method-gtkmenu--set-tearoff-state"><methodname>set_tearoff_state</methodname>()</link>.</para>

    </refsect2>

    <refsect2 id="method-gtkmenu--set-title">
      <title>gtk.Menu.set_title</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_title</methodname>
	  <methodparam><parameter
			 role="keyword">title</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">title</parameter>&nbsp;:</term>
	  <listitem><simpara>a string containing the title for the
menu.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>set_title</methodname>() method sets the title
text (from the value of <parameter>title</parameter>) to be used for the
menu when it is shown as a tearoff menu.</para>

    </refsect2>

    <refsect2 id="method-gtkmenu--get-title">
      <title>gtk.Menu.get_title</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_title</methodname>
	  <methodparam></methodparam>  </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>the title of the menu, or
<literal>None</literal> if the menu has no title set on
it.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>get_title</methodname>() method returns the
title of the menu or <literal>None</literal> of no title is set. See <link
linkend="method-gtkmenu--set-title"><methodname>set_title</methodname>()</link>.</para>

    </refsect2>

    <refsect2 id="method-gtkmenu--reorder-child">
      <title>gtk.Menu.reorder_child</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>reorder_child</methodname>
	  <methodparam><parameter
			 role="keyword">child</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">position</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">child</parameter>&nbsp;:</term>
	  <listitem><simpara>the <link
linkend="class-gtkmenuitem"><classname>gtk.MenuItem</classname></link> to
move.</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">position</parameter>&nbsp;:</term>
	  <listitem><simpara>the new position to place child. Positions are
numbered starting from 0</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>reorder_child</methodname>() method moves the
menuitem specified by <parameter>child</parameter> to a new position within
the menu specified by <parameter>position</parameter>.</para>

    </refsect2>

    <refsect2 id="method-gtkmenu--set-screen">
      <title>gtk.Menu.set_screen</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_screen</methodname>
	  <methodparam><parameter role="keyword">screen</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">screen</parameter>&nbsp;:</term>
	  <listitem><simpara>a <link
	  linkend="class-gdkscreen"><classname>gtk.gdk.Screen</classname></link>,
	  or <literal>None</literal> if the screen should be determined by
	  the widget the menu is attached to.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <note>
	<para>This method is available in PyGTK 2.2 and above.</para>
      </note>

      <para>The <methodname>set_screen</methodname>() method sets the <link
linkend="class-gdkscreen"><classname>gtk.gdk.Screen</classname></link>
specified by <parameter>screen</parameter> on which the menu will be
displayed. If <parameter>screen</parameter> is <literal>None</literal> the
screen is determined by the widget that the menu is attached to.</para>

    </refsect2>

    <refsect2 id="method-gtkmenu--attach">
      <title>gtk.Menu.attach</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>attach</methodname>
	  <methodparam><parameter role="keyword">child</parameter></methodparam>
	  <methodparam><parameter role="keyword">left_attach</parameter></methodparam>
	  <methodparam><parameter role="keyword">right_attach</parameter></methodparam>
	  <methodparam><parameter role="keyword">top_attach</parameter></methodparam>
	  <methodparam><parameter role="keyword">bottom_attach</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">child</parameter>&nbsp;:</term>
	  <listitem><simpara>a <link
	  linkend="class-gtkmenuitem"><classname>gtk.MenuItem</classname></link>.</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter
	  role="keyword">left_attach</parameter>&nbsp;:</term>
	  <listitem><simpara>The column number to attach the left side of
	  the item to.</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter
	  role="keyword">right_attach</parameter>&nbsp;:</term>
	  <listitem><simpara>The column number to attach the right side of
	  the item to.</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter
	  role="keyword">top_attach</parameter>&nbsp;:</term>
	  <listitem><simpara>The row number to attach the top of the item
	  to.</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter
	  role="keyword">bottom_attach</parameter>&nbsp;:</term>
	  <listitem><simpara>The row number to attach the bottom of the item
	  to.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <note>
	<para>This method is available in PyGTK 2.4 and above.</para>
      </note>

      <para>The <methodname>attach</methodname>() method adds a new <link
linkend="class-gtkmenuitem"><classname>gtk.MenuItem</classname></link>
specified by <parameter>child</parameter> to a (table) menu. The number of
'cells' that an item will occupy is specified by
<parameter>left_attach</parameter>, <parameter>right_attach</parameter>,
<parameter>top_attach</parameter> and
<parameter>bottom_attach</parameter>. These each represent the leftmost,
rightmost, uppermost and lower column and row numbers of the table.
(Columns and rows are indexed from zero).</para>

      <para>Note that this function is not related to the <link
linkend="method-gtkmenu--detach"><methodname>detach()</methodname></link>
method.</para>

    </refsect2>

    <refsect2 id="method-gtkmenu--set-monitor">
      <title>gtk.Menu.set_monitor</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_monitor</methodname>
	  <methodparam><parameter role="keyword">monitor_num</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter
	  role="keyword">monitor_num</parameter>&nbsp;:</term>
	  <listitem><simpara>the number of the monitor on which the menu
	  should be popped up</simpara></listitem>
	</varlistentry>
      </variablelist>

      <note>
	<para>This method is available in PyGTK 2.4 and above.</para>
      </note>

      <para>The <methodname>set_monitor</methodname>() method informs
<literal>GTK</literal>+ on which monitor a menu should be popped up.  See
the <link
linkend="method-gdkscreen--get-monitor-geometry"><methodname>gtk.gdk.Screen.get_monitor_geometry()</methodname></link>
method for more information.</para>

      <para>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.</para>

    </refsect2>

    <refsect2 id="method-gtkmenu--get-monitor">
      <title>gtk.Menu.get_monitor</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_monitor</methodname>
	  <methodparam></methodparam>  </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>the number of the monitor on which the menu should
	  be popped up or -1, if no monitor has been set </simpara></listitem>
	</varlistentry>
      </variablelist>

      <note>
        <para>This method is available in PyGTK 2.14 and above.</para>
      </note>

      <para>
	The <methodname>get_monitor</methodname>() method returns
	the number of the monitor on which to show the menu.
      </para>

    </refsect2>

    <refsect2 id="method-gtkmenu--set-reserve-toggle-size">
      <title>gtk.Menu.set_reserve_toggle_size</title>

      <programlisting><methodsynopsis language="python">
        <methodname>set_reserve_toggle_size</methodname>
        <methodparam><parameter role="keyword">reserve_toggle_size</parameter></methodparam>
      </methodsynopsis></programlisting>
      <variablelist>
        <varlistentry>
          <term><parameter role="keyword">reserve_toggle_size</parameter>&nbsp;:</term>
          <listitem><simpara><literal>True</literal> to reserve size for toggles.</simpara></listitem>
        </varlistentry>
      </variablelist>

      <note>
        <para>This method is available in PyGTK 2.22 and above.</para>
      </note>

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

    </refsect2>

    <refsect2 id="method-gtkmenu--get-reserve-toggle-size">
      <title>gtk.Menu.get_reserve_toggle_size</title>

      <programlisting><methodsynopsis language="python">
        <methodname>get_reserve_toggle_size</methodname>
        <methodparam></methodparam>
      </methodsynopsis></programlisting>
      <variablelist>
        <varlistentry>
          <term><emphasis>Returns</emphasis>&nbsp;:</term>
          <listitem><simpara>Whether the menu reserves toggle space.</simpara></listitem>
        </varlistentry>
      </variablelist>

      <note>
        <para>This method is available in PyGTK 2.22 and above.</para>
      </note>

      <para>The <methodname>get_reserve_toggle_size</methodname>() method returns whether the menu
      reserves space for toggles and icons, regardless of their actual presence.</para>

    </refsect2>

  </refsect1>

  <refsect1>
    <title>Signals</title>

    <refsect2 id="signal-gtkmenu--move-scroll">
      <title>The "move_scroll" gtk.Menu Signal</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>callback</methodname>
	  <methodparam><parameter>menu</parameter></methodparam>
	  <methodparam><parameter>type</parameter></methodparam>
	  <methodparam><parameter>user_param1</parameter></methodparam>
	  <methodparam><parameter>...</parameter></methodparam>
	</methodsynopsis></programlisting>

      <variablelist>
	<varlistentry>
	  <term><parameter>menu</parameter>&nbsp;:</term>
	  <listitem><simpara>the menu that received the
signal</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>type</parameter>&nbsp;:</term>
	  <listitem><simpara>the type of scroll that is requested</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>user_param1</parameter>&nbsp;:</term>
          <listitem><simpara>the first user parameter (if any) specified
with the <link
linkend="method-gobject--connect"><methodname>connect</methodname>()</link>
method</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>...</parameter>&nbsp;:</term>
	  <listitem><simpara>additional user parameters (if
any)</simpara></listitem>
	</varlistentry>
      </variablelist>

      <note>
	<para>This signal is available in GTK+ 2.2 and above.</para>
      </note>

      <para>The "move_scroll" signal is emitted when the user attempts to
scroll the menu. <parameter>type</parameter> should be one of the <xref
linkend="gtk-scroll-step-constants"
endterm="gtk-scroll-step-constants-title"></xref>.</para>

    </refsect2>

  </refsect1>

</refentry>