<?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-gtkuimanager">
  <refnamediv>
    <refname>gtk.UIManager</refname>

    <refpurpose>construct menus and toolbars from an XML
    description (new in PyGTK 2.4)</refpurpose>
  </refnamediv>

  <refsect1>
    <title>Synopsis</title>

    <classsynopsis language="python">
      <ooclass><classname>gtk.UIManager</classname></ooclass>
      <ooclass><classname><link linkend="class-gobject">gobject.GObject</link></classname></ooclass>
      <constructorsynopsis language="python">
	<methodname><link linkend="constructor-gtkuimanager">gtk.UIManager</link></methodname>
	<methodparam></methodparam>
      </constructorsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtkuimanager--set-add-tearoffs">set_add_tearoffs</link></methodname>
	<methodparam><parameter role="keyword">add_tearoffs</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtkuimanager--get-add-tearoffs">get_add_tearoffs</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtkuimanager--insert-action-group">insert_action_group</link></methodname>
	<methodparam><parameter role="keyword">action_group</parameter></methodparam>
	<methodparam><parameter role="keyword">pos</parameter><initializer>-1</initializer></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtkuimanager--remove-action-group">remove_action_group</link></methodname>
	<methodparam><parameter role="keyword">action_group</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtkuimanager--get-action-groups">get_action_groups</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtkuimanager--get-accel-group">get_accel_group</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtkuimanager--get-widget">get_widget</link></methodname>
	<methodparam><parameter role="keyword">path</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtkuimanager--get-toplevels">get_toplevels</link></methodname>
	<methodparam><parameter role="keyword">types</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtkuimanager--get-action">get_action</link></methodname>
	<methodparam><parameter role="keyword">path</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtkuimanager--add-ui-from-string">add_ui_from_string</link></methodname>
	<methodparam><parameter role="keyword">buffer</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtkuimanager--add-ui-from-file">add_ui_from_file</link></methodname>
	<methodparam><parameter role="keyword">filename</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtkuimanager--add-ui">add_ui</link></methodname>
	<methodparam><parameter role="keyword">merge_id</parameter></methodparam>
	<methodparam><parameter role="keyword">path</parameter></methodparam>
	<methodparam><parameter role="keyword">name</parameter></methodparam>
	<methodparam><parameter role="keyword">action</parameter></methodparam>
	<methodparam><parameter role="keyword">type</parameter></methodparam>
	<methodparam><parameter role="keyword">top</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtkuimanager--remove-ui">remove_ui</link></methodname>
	<methodparam><parameter role="keyword">merge_id</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtkuimanager--get-ui">get_ui</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtkuimanager--ensure-update">ensure_update</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtkuimanager--new-merge-id">new_merge_id</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
    </classsynopsis>

  </refsect1>

  <refsect1>
    <title>Ancestry</title>

<synopsis>+-- <link linkend="class-gobject">gobject.GObject</link>
  +-- <link linkend="class-gtkuimanager">gtk.UIManager</link>
</synopsis>

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

  <refsect1 id="properties-gtkuimanager">
    <title>gtk.UIManager Properties</title>

    <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>"add-tearoffs"</entry>
	      <entry>Read-Write</entry>

	      <entry>If <literal>True</literal>, regular menus have tearoff
menu items. Note that this only affects regular menus. Generated popup menus
never have tearoff menu items. Available in <literal>GTK+</literal> 2.4 and
above.</entry>
	    </row>

	    <row valign="top">
	      <entry>"ui"</entry>
	      <entry>Read-Write</entry>
	      <entry>An XML string describing the merged UI.</entry>
	    </row>

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

  </refsect1>

  <refsect1 id="signal-prototypes-gtkuimanager">
    <title>gtk.UIManager Signal Prototypes</title>

    <para><link linkend="signal-prototypes-gobject">gobject.GObject Signal Prototypes</link></para>

    <variablelist>
      <varlistentry>
        <term>"<link linkend="signal-gtkuimanager--actions-changed">actions-changed</link>"</term>
        <listitem>
          <methodsynopsis language="python"><methodname>callback</methodname>
            <methodparam><parameter>uimanager</parameter></methodparam>
            <methodparam><parameter>user_param1</parameter></methodparam>
            <methodparam><parameter>...</parameter></methodparam>
          </methodsynopsis>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>"<link linkend="signal-gtkuimanager--add-widget">add-widget</link>"</term>
        <listitem>
          <methodsynopsis language="python"><methodname>callback</methodname>
            <methodparam><parameter>uimanager</parameter></methodparam>
            <methodparam><parameter>widget</parameter></methodparam>
            <methodparam><parameter>user_param1</parameter></methodparam>
            <methodparam><parameter>...</parameter></methodparam>
          </methodsynopsis>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>"<link linkend="signal-gtkuimanager--connect-proxy">connect-proxy</link>"</term>
        <listitem>
          <methodsynopsis language="python"><methodname>callback</methodname>
            <methodparam><parameter>uimanager</parameter></methodparam>
            <methodparam><parameter>action</parameter></methodparam>
            <methodparam><parameter>widget</parameter></methodparam>
            <methodparam><parameter>user_param1</parameter></methodparam>
            <methodparam><parameter>...</parameter></methodparam>
          </methodsynopsis>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>"<link linkend="signal-gtkuimanager--disconnect-proxy">disconnect-proxy</link>"</term>
        <listitem>
          <methodsynopsis language="python"><methodname>callback</methodname>
            <methodparam><parameter>uimanager</parameter></methodparam>
            <methodparam><parameter>action</parameter></methodparam>
            <methodparam><parameter>widget</parameter></methodparam>
            <methodparam><parameter>user_param1</parameter></methodparam>
            <methodparam><parameter>...</parameter></methodparam>
          </methodsynopsis>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>"<link linkend="signal-gtkuimanager--post-activate">post-activate</link>"</term>
        <listitem>
          <methodsynopsis language="python"><methodname>callback</methodname>
            <methodparam><parameter>uimanager</parameter></methodparam>
            <methodparam><parameter>action</parameter></methodparam>
            <methodparam><parameter>user_param1</parameter></methodparam>
            <methodparam><parameter>...</parameter></methodparam>
          </methodsynopsis>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>"<link linkend="signal-gtkuimanager--pre-activate">pre-activate</link>"</term>
        <listitem>
          <methodsynopsis language="python"><methodname>callback</methodname>
            <methodparam><parameter>uimanager</parameter></methodparam>
            <methodparam><parameter>action</parameter></methodparam>
            <methodparam><parameter>user_param1</parameter></methodparam>
            <methodparam><parameter>...</parameter></methodparam>
          </methodsynopsis>
        </listitem>
      </varlistentry>
    </variablelist>

  </refsect1>

  <refsect1>
    <title>Description</title>

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

    <para>A <link
linkend="class-gtkuimanager"><classname>gtk.UIManager</classname></link>
constructs a user interface (menus and toolbars) from one or more UI
definitions, which reference actions from one or more action groups.</para>

    <refsect2 id="XML-UI">
      <title>UI Definitions</title>

      <para>The UI definitions are specified in an XML format which can be
roughly described by the following DTD.</para>

      <programlisting>
&lt;!ELEMENT ui          (menubar|toolbar|popup|accelerator)* &gt;
&lt;!ELEMENT menubar     (menuitem|separator|placeholder|menu)* &gt;
&lt;!ELEMENT menu        (menuitem|separator|placeholder|menu)* &gt;
&lt;!ELEMENT popup       (menuitem|separator|placeholder|menu)* &gt;
&lt;!ELEMENT toolbar     (toolitem|separator|placeholder)* &gt;
&lt;!ELEMENT placeholder (menuitem|toolitem|separator|placeholder|menu)* &gt;
&lt;!ELEMENT menuitem     EMPTY &gt;
&lt;!ELEMENT toolitem     EMPTY &gt;
&lt;!ELEMENT separator    EMPTY &gt;
&lt;!ELEMENT accelerator  EMPTY &gt;
&lt;!ATTLIST menubar      name               #IMPLIED &gt;
&lt;!ATTLIST toolbar      name               #IMPLIED &gt;
&lt;!ATTLIST popup        name               #IMPLIED &gt;
&lt;!ATTLIST placeholder  name               #IMPLIED &gt;
&lt;!ATTLIST menu         name               #IMPLIED
                       action             #REQUIRED
                       position (top|bot) #IMPLIED &gt;
&lt;!ATTLIST menuitem     name               #IMPLIED
                       action             #REQUIRED
                       position (top|bot) #IMPLIED &gt;
&lt;!ATTLIST toolitem     name               #IMPLIED
                       action             #REQUIRED
                       position (top|bot) #IMPLIED &gt;
&lt;!ATTLIST accelerator  name               #IMPLIED
                       action             #REQUIRED &gt;
</programlisting>

      <para>There are some additional restrictions beyond those specified in
the DTD, e.g. every toolitem must have a toolbar in its ancestry and every
menuitem must have a menubar or popup in its ancestry. Since a GMarkup
parser is used to parse the UI description, it must not only be valid XML,
but valid GMarkup. If a name is not specified, it defaults to the action. If
an action is not specified either, the element name is used.</para>

      <example>
	<title>A UI definition</title>

	<programlisting>
&lt;ui&gt;
  &lt;menubar&gt;
    &lt;menu name="FileMenu" action="FileMenuAction"&gt;
      &lt;menuitem name="New" action="New2Action" /&gt;
      &lt;placeholder name="FileMenuAdditions" /&gt;
    &lt;/menu&gt;
    &lt;menu name="JustifyMenu" action="JustifyMenuAction"&gt;
      &lt;menuitem name="Left" action="justify-left"/&gt;
      &lt;menuitem name="Centre" action="justify-center"/&gt;
      &lt;menuitem name="Right" action="justify-right"/&gt;
      &lt;menuitem name="Fill" action="justify-fill"/&gt;
    &lt;/menu&gt;
  &lt;/menubar&gt;
  &lt;toolbar action="toolbar1"&gt;
    &lt;placeholder name="JustifyToolItems"&gt;
      &lt;separator/&gt;
      &lt;toolitem name="Left" action="justify-left"/&gt;
      &lt;toolitem name="Centre" action="justify-center"/&gt;
      &lt;toolitem name="Right" action="justify-right"/&gt;
      &lt;toolitem name="Fill" action="justify-fill"/&gt;
      &lt;separator/&gt;
    &lt;/placeholder&gt;
  &lt;/toolbar&gt;
&lt;/ui&gt;
</programlisting>
      </example>

      <para>The constructed widget hierarchy is very similar to the element
tree of the XML, with the exception that placeholders are merged into their
parents. The correspondence of XML elements to widgets should be almost
obvious:</para>

      <variablelist>
	<varlistentry>
	  <term>menubar</term>
	  <listitem>
	    <simpara>a <link
	    linkend="class-gtkmenubar"><classname>gtk.MenuBar</classname></link></simpara>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term>toolbar</term>
	  <listitem>
	    <simpara>a <link
	    linkend="class-gtktoolbar"><classname>gtk.Toolbar</classname></link></simpara>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term>popup</term>
	  <listitem>
	    <simpara>a toplevel <link
	    linkend="class-gtkmenu"><classname>gtk.Menu</classname></link></simpara>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term>menu</term>
	  <listitem>
	    <simpara>a <link
	    linkend="class-gtkmenu"><classname>gtk.Menu</classname></link>
	    attached to a menuitem</simpara>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term>menuitem</term>
	  <listitem>
	    <simpara>a <link
	    linkend="class-gtkmenuitem"><classname>gtk.MenuItem</classname></link>
	    subclass, the exact type depends on the action</simpara>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term>toolitem</term>
	  <listitem>
	    <simpara>a <link
	    linkend="class-gtktoolitem"><classname>gtk.ToolItem</classname></link>
	    subclass, the exact type depends on the action</simpara>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term>separator</term>
	  <listitem>
	    <simpara>a <link
	    linkend="class-gtkseparatormenuitem"><classname>gtk.SeparatorMenuItem</classname></link>
	    or <link
	    linkend="class-gtkseparatortoolitem"><classname>gtk.SeparatorToolItem</classname></link></simpara>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term>accelerator</term>
	  <listitem>
	    <simpara>a keyboard accelerator</simpara>
	  </listitem>
	</varlistentry>
      </variablelist>

      <para>The "position" attribute determines where a constructed widget
is positioned with respect to its siblings in the partially constructed
tree. If it is "top", the widget is prepended, otherwise it is
appended.</para>

    </refsect2>

    <refsect2>
      <title>UI Merging</title>

      <para>The most remarkable feature of <link
linkend="class-gtkuimanager"><classname>gtk.UIManager</classname></link> is
that it can overlay a set of menuitems and toolitems over another one, and
demerge them later.</para>

      <para>Merging is done based on the name of the XML elements. Each
element is identified by a path which consists of the names of its
ancestors, separated by slashes. For example, the menuitem named "Left" in
the example above has the path
<filename>/ui/menubar/JustifyMenu/Left</filename> and the toolitem with the
same name has path
<filename>/ui/toolbar1/JustifyToolItems/Left</filename>.</para>

    </refsect2>

    <refsect2>
      <title>Accelerators</title>

      <para>Every action has an accelerator path. Accelerators are installed
together with menuitem proxies, but they can also be explicitly added with
&lt;accelerator&gt; elements in the UI definition. This makes it possible to
have accelerators for actions even if they have no visible proxies.</para>

    </refsect2>

    <refsect2>
      <title>Smart Separators</title>

      <para>The separators created by <link
linkend="class-gtkuimanager"><classname>gtk.UIManager</classname></link> are
"smart", i.e. they do not show up in the UI unless they end up between two
visible menu or tool items. Separators which are located at the very
beginning or end of the menu or toolbar containing them, or multiple
separators next to each other, are hidden. This is a useful feature, since
the merging of UI elements from multiple sources can make it hard or
impossible to determine in advance whether a separator will end up in such
an unfortunate position.</para>

    </refsect2>

    <refsect2>
      <title>Empty Menus</title>

      <para>Submenus pose similar problems to separators in connection with
merging. It is impossible to know in advance whether they will end up empty
after merging. <link
linkend="class-gtkuimanager"><classname>gtk.UIManager</classname></link>
offers two ways to treat empty submenus:</para>

    <itemizedlist>
      <listitem>
	<simpara>make them disappear by hiding the menu item they're
	attached to</simpara>
      </listitem>
      <listitem>
	<simpara>add an insensitive "Empty" item</simpara>
      </listitem>
   </itemizedlist>

      <para>The behavior is chosen based on the "is_important" property of
the action to which the submenu is associated.</para>

    </refsect2>

  </refsect1>

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

    <programlisting><constructorsynopsis language="python">
	<methodname>gtk.UIManager</methodname>
	<methodparam></methodparam>
      </constructorsynopsis></programlisting>
    <variablelist>
      <varlistentry>
	<term><emphasis>Returns</emphasis>&nbsp;:</term>
	<listitem><simpara>a new ui manager object.</simpara></listitem>
      </varlistentry>
    </variablelist>

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

    <para>Creates a new <link
linkend="class-gtkuimanager"><classname>gtk.UIManager</classname></link>
object.</para>

  </refsect1>

  <refsect1>
    <title>Methods</title>

    <refsect2 id="method-gtkuimanager--set-add-tearoffs">
      <title>gtk.UIManager.set_add_tearoffs</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_add_tearoffs</methodname>
	  <methodparam><parameter role="keyword">add_tearoffs</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter
	  role="keyword">add_tearoffs</parameter>&nbsp;:</term>
	  <listitem><simpara><literal>True</literal> if tearoff menu items
	  are added to regular menus</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>add_tearoffs</methodname>() method sets the
"add_tearoffs" property to the value of
<parameter>add_tearoffs</parameter>. If <parameter>add_tearoffs</parameter>
is <literal>True</literal> regular menus generated by this <link
linkend="class-gtkuimanager"><classname>gtk.UIManager</classname></link>
will have tearoff menu items.</para>

      <para>Note that this only affects regular menus. Generated popup menus
never have tearoff menu items.</para>

    </refsect2>

    <refsect2 id="method-gtkuimanager--get-add-tearoffs">
      <title>gtk.UIManager.get_add_tearoffs</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_add_tearoffs</methodname>
	  <methodparam></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara><literal>True</literal> if tearoff menu items
	  are added</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>get_add_tearoffs</methodname>() method returns
the value of the "add-tearoffs" property. If "add-tearoffs" is
<literal>True</literal> regular menus generated will have tearoff menu
items.</para>

    </refsect2>

    <refsect2 id="method-gtkuimanager--insert-action-group">
      <title>gtk.UIManager.insert_action_group</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>insert_action_group</methodname>
	  <methodparam><parameter role="keyword">action_group</parameter></methodparam>
	  <methodparam><parameter role="keyword">pos</parameter><initializer>-1</initializer></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter
	  role="keyword">action_group</parameter>&nbsp;:</term>
	  <listitem><simpara>the action group to be
	  inserted</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">pos</parameter>&nbsp;:</term>
	  <listitem><simpara>the position at which the group will be
	  inserted. If <parameter>pos</parameter> is negative
	  <parameter>action_group</parameter> is inserted at the end of the
	  list.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <note>
	<para>This method is available in PyGTK 2.4 and above.</para>
	<para><parameter>pos</parameter> has default value since PyGTK 2.12.</para>
      </note>

      <para>The <methodname>insert_action_group</methodname>() method
inserts the <link
linkend="class-gtkactiongroup"><classname>gtk.ActionGroup</classname></link>
specified by <parameter>action_group</parameter> into the list of associated
action groups at the position specified by
<parameter>pos</parameter>. If <parameter>pos</parameter> is negative, new
action group is inserted at the end of the list. Actions in earlier groups
hide actions with the same name in later groups.</para>

    </refsect2>

    <refsect2 id="method-gtkuimanager--remove-action-group">
      <title>gtk.UIManager.remove_action_group</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>remove_action_group</methodname>
	  <methodparam><parameter role="keyword">action_group</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter
	  role="keyword">action_group</parameter>&nbsp;:</term>
	  <listitem><simpara>the action group to be
	  removed</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>remove_action_group</methodname>() method
removes the <link
linkend="class-gtkactiongroup"><classname>gtk.ActionGroup</classname></link>
specified by <parameter>action_group</parameter> from the list of
associated action groups.</para>

    </refsect2>

    <refsect2 id="method-gtkuimanager--get-action-groups">
      <title>gtk.UIManager.get_action_groups</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_action_groups</methodname>
	  <methodparam></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>a list of associated action
	  groups.</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>get_action_groups</methodname>() method returns
the list of associated <link
linkend="class-gtkactiongroup"><classname>gtk.ActionGroup</classname></link>
objects.</para>

    </refsect2>

    <refsect2 id="method-gtkuimanager--get-accel-group">
      <title>gtk.UIManager.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>.</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>get_accel_group</methodname>() method returns
the associated <link
linkend="class-gtkaccelgroup"><classname>gtk.AccelGroup</classname></link>.</para>

    </refsect2>

    <refsect2 id="method-gtkuimanager--get-widget">
      <title>gtk.UIManager.get_widget</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_widget</methodname>
	  <methodparam><parameter role="keyword">path</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">path</parameter>&nbsp;:</term>
	  <listitem><simpara>a path</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>the widget found by following the path, or
	  <literal>None</literal> if no widget was
	  found.</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>get_widget</methodname>() method looks up a
widget by following the path specified by <parameter>path</parameter>.  The
path consists of the names specified in the XML description of the UI.
separated by '/'. Elements that don't have a name or action attribute in
the XML (e.g. &lt;popup&gt;) can be addressed by their XML element name
(e.g. "popup"). The root element ("/ui") can be omitted in the path.</para>

    </refsect2>

    <refsect2 id="method-gtkuimanager--get-toplevels">
      <title>gtk.UIManager.get_toplevels</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_toplevels</methodname>
	  <methodparam><parameter role="keyword">types</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">types</parameter>&nbsp;:</term>
	  <listitem><simpara>specifies the types of toplevel widgets to
	  include. Allowed types are
	  <literal>gtk.UI_MANAGER_MENUBAR</literal>,
	  <literal>gtk.UI_MANAGER_TOOLBAR</literal> and
	  <literal>gtk.UI_MANAGER_POPUP</literal>.</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>a list of all toplevel widgets of the requested
	  types.</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>get_toplevels</methodname>() method returns a
list of all toplevel widgets of the types specified by
<parameter>types</parameter>.</para>

    </refsect2>

    <refsect2 id="method-gtkuimanager--get-action">
      <title>gtk.UIManager.get_action</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_action</methodname>
	  <methodparam><parameter role="keyword">path</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">path</parameter>&nbsp;:</term>
	  <listitem><simpara>a path</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>the action whose proxy widget is found by
	  following the path, or <literal>None</literal> if no widget was
	  found.</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>get_action</methodname>() method looks up a
<link linkend="class-gtkaction"><classname>gtk.Action</classname></link> by
following a path. See the <link
linkend="method-gtkuimanager--get-widget"><methodname>get_widget()</methodname></link>
method for more information about paths.</para>

    </refsect2>

    <refsect2 id="method-gtkuimanager--add-ui-from-string">
      <title>gtk.UIManager.add_ui_from_string</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>add_ui_from_string</methodname>
	  <methodparam><parameter role="keyword">buffer</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">buffer</parameter>&nbsp;:</term>
	  <listitem><simpara>the string to parse</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>The merge id for the merged UI. The merge id
	  can be used to unmerge the UI with the <link
	  linkend="method-gtkuimanager--remove-ui"><methodname>remove_ui()</methodname></link>
	  method.</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>add_ui_from_string</methodname>() method parses
the string specified by <parameter>buffer</parameter> that contains a <link
linkend="XML-UI">UI definition</link> and merges it with the current
contents of the ui manager. An enclosing &lt;ui&gt; element is added if it
is missing.</para>

      <para>This method raise the GError exception if an error occurs during
the parsing of the string.</para>

    </refsect2>

    <refsect2 id="method-gtkuimanager--add-ui-from-file">
      <title>gtk.UIManager.add_ui_from_file</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>add_ui_from_file</methodname>
	  <methodparam><parameter role="keyword">filename</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">filename</parameter>&nbsp;:</term>
	  <listitem><simpara>the name of the file to parse</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>The merge id for the merged UI. The merge id
	  can be used to unmerge the UI with the <link
	  linkend="method-gtkuimanager--remove-ui"><methodname>gtk.UIManager.remove_ui()</methodname></link>
	  method.</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>add_ui_from_file</methodname>() method parses
the file specified by <parameter>filename</parameter> that contains a <link
linkend="XML-UI">UI definition</link> and merges it with the current
contents of the ui manager.</para>

      <para>This method raise the GError exception if an error occurs during
the parsing of the file.</para>

    </refsect2>

    <refsect2 id="method-gtkuimanager--add-ui">
      <title>gtk.UIManager.add_ui</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>add_ui</methodname>
	  <methodparam><parameter role="keyword">merge_id</parameter></methodparam>
	  <methodparam><parameter role="keyword">path</parameter></methodparam>
	  <methodparam><parameter role="keyword">name</parameter></methodparam>
	  <methodparam><parameter role="keyword">action</parameter></methodparam>
	  <methodparam><parameter role="keyword">type</parameter></methodparam>
	  <methodparam><parameter role="keyword">top</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">merge_id</parameter>&nbsp;:</term>
	  <listitem><simpara>the merge id for the merged UI, see <link
	  linkend="method-gtkuimanager--new-merge-id"><methodname>new_merge_id()</methodname></link></simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">path</parameter>&nbsp;:</term>
	  <listitem><simpara>a path where the element should be
	  added</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">name</parameter>&nbsp;:</term>
	  <listitem><simpara>the name for the added UI
	  element</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">action</parameter>&nbsp;:</term>
	  <listitem><simpara>the name of the action to be proxied, or
	  <literal>None</literal> to add a separator</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">type</parameter>&nbsp;:</term>
	  <listitem><simpara>the type of UI element to
	  add.</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">top</parameter>&nbsp;:</term>
	  <listitem><simpara>if <literal>True</literal>, the UI element is
	  added before its siblings, otherwise it is added after its
	  siblings.</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>add_ui</methodname>() method adds a UI element
of the type specified by <parameter>type</parameter> to the current contents
of the ui manager at the location specified by
<parameter>path</parameter>. Note that path must not start with "/ui" though
"ui" is acceptable. For example "/menubar" or "ui/menubar" is acceptable but
"/ui/menubar" is not. <parameter>type</parameter> must be one of:</para>

      <variablelist>
	<varlistentry>
	  <term><literal>gtk.UI_MANAGER_AUTO</literal></term>
	  <listitem>
	    <simpara>The type of the UI element (menuitem, toolitem or
separator) is set according to the context.</simpara>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><literal>gtk.UI_MANAGER_MENUBAR</literal></term>
	  <listitem>
	    <simpara>A menubar. </simpara>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><literal>gtk.UI_MANAGER_MENU</literal></term>
	  <listitem>
	    <simpara>A menu.</simpara>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><literal>gtk.UI_MANAGER_TOOLBAR</literal></term>
	  <listitem>
	    <simpara>A toolbar.</simpara>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><literal>gtk.UI_MANAGER_PLACEHOLDER</literal></term>
	  <listitem>
	    <simpara>A placeholder.</simpara>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><literal>gtk.UI_MANAGER_POPUP</literal></term>
	  <listitem>
	    <simpara>A popup menu.</simpara>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><literal>gtk.UI_MANAGER_MENUITEM</literal></term>
	  <listitem>
	    <simpara>A menuitem.</simpara>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><literal>gtk.UI_MANAGER_TOOLITEM</literal></term>
	  <listitem>
	    <simpara>A toolitem.</simpara>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><literal>gtk.UI_MANAGER_SEPARATOR</literal></term>
	  <listitem>
	    <simpara>A separator.</simpara>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><literal>gtk.UI_MANAGER_ACCELERATOR</literal></term>
	  <listitem>
	    <simpara>An accelerator.</simpara>
	  </listitem>
	</varlistentry>
      </variablelist>

      <para></para>

    </refsect2>

    <refsect2 id="method-gtkuimanager--remove-ui">
      <title>gtk.UIManager.remove_ui</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>remove_ui</methodname>
	  <methodparam><parameter role="keyword">merge_id</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">merge_id</parameter>&nbsp;:</term>
	  <listitem><simpara>a merge id</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>remove_ui</methodname>() method unmerges the
part of the ui manager content identified by
<parameter>merge_id</parameter>.</para>

    </refsect2>

    <refsect2 id="method-gtkuimanager--get-ui">
      <title>gtk.UIManager.get_ui</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_ui</methodname>
	  <methodparam></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>A string containing an XML representation of
	  the merged UI.</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>get_ui</methodname>() method creates a <link
linkend="XML-UI">UI definition</link> of the merged UI.</para>

    </refsect2>

    <refsect2 id="method-gtkuimanager--ensure-update">
      <title>gtk.UIManager.ensure_update</title>

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

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

      <para>The <methodname>ensure_update</methodname>() method makes sure
that all pending updates to the UI have been completed. This may
occasionally be necessary, since <link
linkend="class-gtkuimanager"><classname>gtk.UIManager</classname></link>
updates the UI in an idle function. A typical example where this method is
useful is to enforce that the menubar and toolbar have been added to the
main window before showing it:</para>

      <informalexample>
	<programlisting>
  window.add(vbox) 
  merge.connect("add_widget", add_widget, vbox)
  merge.add_ui_from_file("my-menus")
  merge.add_ui_from_file("my-toolbars")
  merge.ensure_update()  
  window.show()
</programlisting>
      </informalexample>

    </refsect2>

    <refsect2 id="method-gtkuimanager--new-merge-id">
      <title>gtk.UIManager.new_merge_id</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>new_merge_id</methodname>
	  <methodparam></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>an unused merge id.</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>new_merge_id</methodname>() method returns an
unused merge id, suitable for use with the <link
linkend="method-gtkuimanager--add-ui"><methodname>add_ui()</methodname></link>
method. The returned merge ids are monotonically increasing integer
values.</para>

    </refsect2>

  </refsect1>

  <refsect1>
    <title>Signals</title>

    <refsect2 id="signal-gtkuimanager--actions-changed">
      <title>The "actions-changed" gtk.UIManager Signal</title>

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

      <variablelist>
	<varlistentry>
	  <term><parameter>uimanager</parameter>&nbsp;:</term>
	  <listitem><simpara>the uimanager that received the
signal</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.4 and above.</para>
      </note>

      <para>The "actions-changed" signal is emitted when the set of actions
changes.</para>

    </refsect2>

    <refsect2 id="signal-gtkuimanager--add-widget">
      <title>The "add-widget" gtk.UIManager Signal</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>callback</methodname>
	  <methodparam><parameter>uimanager</parameter></methodparam>
	  <methodparam><parameter>widget</parameter></methodparam>
	  <methodparam><parameter>user_param1</parameter></methodparam>
	  <methodparam><parameter>...</parameter></methodparam>
	</methodsynopsis></programlisting>

      <variablelist>
	<varlistentry>
	  <term><parameter>uimanager</parameter>&nbsp;:</term>
	  <listitem><simpara>the uimanager that received the
signal</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>widget</parameter>&nbsp;:</term>
	  <listitem><simpara>the added widget</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.4 and above.</para>
      </note>

      <para>The "add-widget" signal is emitted for each generated menubar
and toolbar. The added widget is specified by
<parameter>widget</parameter>. It is not emitted for generated popup menus,
which can be retrieved by the <link
linkend="method-gtkuimanager--get-widget"><methodname>get_widget</methodname>()</link>
method.</para>

    </refsect2>

    <refsect2 id="signal-gtkuimanager--connect-proxy">
      <title>The "connect-proxy" gtk.UIManager Signal</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>callback</methodname>
	  <methodparam><parameter>uimanager</parameter></methodparam>
	  <methodparam><parameter>action</parameter></methodparam>
	  <methodparam><parameter>widget</parameter></methodparam>
	  <methodparam><parameter>user_param1</parameter></methodparam>
	  <methodparam><parameter>...</parameter></methodparam>
	</methodsynopsis></programlisting>

      <variablelist>
	<varlistentry>
	  <term><parameter>uimanager</parameter>&nbsp;:</term>
	  <listitem><simpara>the uimanager that received the
signal</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>action</parameter>&nbsp;:</term>
	  <listitem><simpara>the action</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>widget</parameter>&nbsp;:</term>
	  <listitem><simpara>the proxy widget</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.4 and above.</para>
      </note>

      <para>The "connect-proxy" signal is emitted after connecting the proxy
widget specified by <parameter>widget</parameter> to the <link
linkend="class-gtkaction"><classname>gtk.Action</classname></link> specified
by <parameter>action</parameter> in the group. This is intended for simple
customizations for which a custom action class would be too clumsy,
e.g. showing tooltips for menuitems in the statusbar.</para>

    </refsect2>

    <refsect2 id="signal-gtkuimanager--disconnect-proxy">
      <title>The "disconnect-proxy" gtk.UIManager Signal</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>callback</methodname>
	  <methodparam><parameter>uimanager</parameter></methodparam>
	  <methodparam><parameter>action</parameter></methodparam>
	  <methodparam><parameter>widget</parameter></methodparam>
	  <methodparam><parameter>user_param1</parameter></methodparam>
	  <methodparam><parameter>...</parameter></methodparam>
	</methodsynopsis></programlisting>

      <variablelist>
	<varlistentry>
	  <term><parameter>uimanager</parameter>&nbsp;:</term>
	  <listitem><simpara>the uimanager that received the
signal</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>action</parameter>&nbsp;:</term>
	  <listitem><simpara>the action</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>widget</parameter>&nbsp;:</term>
	  <listitem><simpara>the proxy widget</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.4 and above.</para>
      </note>

      <para>The "disconnect-proxy" signal is emitted when
<parameter>widget</parameter> is disconnected from
<parameter>action</parameter>.</para>

    </refsect2>

    <refsect2 id="signal-gtkuimanager--post-activate">
      <title>The "post-activate" gtk.UIManager Signal</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>callback</methodname>
	  <methodparam><parameter>uimanager</parameter></methodparam>
	  <methodparam><parameter>action</parameter></methodparam>
	  <methodparam><parameter>user_param1</parameter></methodparam>
	  <methodparam><parameter>...</parameter></methodparam>
	</methodsynopsis></programlisting>

      <variablelist>
	<varlistentry>
	  <term><parameter>uimanager</parameter>&nbsp;:</term>
	  <listitem><simpara>the uimanager that received the
signal</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>action</parameter>&nbsp;:</term>
	  <listitem><simpara>the action</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.4 and above.</para>
      </note>

      <para>The "post-activate" signal is emitted after
<parameter>action</parameter> is activated. This signal is intended for
applications to get notification after any action is activated.</para>

    </refsect2>

    <refsect2 id="signal-gtkuimanager--pre-activate">
      <title>The "pre-activate" gtk.UIManager Signal</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>callback</methodname>
	  <methodparam><parameter>uimanager</parameter></methodparam>
	  <methodparam><parameter>action</parameter></methodparam>
	  <methodparam><parameter>user_param1</parameter></methodparam>
	  <methodparam><parameter>...</parameter></methodparam>
	</methodsynopsis></programlisting>

      <variablelist>
	<varlistentry>
	  <term><parameter>uimanager</parameter>&nbsp;:</term>
	  <listitem><simpara>the uimanager that received the
signal</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>action</parameter>&nbsp;:</term>
	  <listitem><simpara>the action</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.4 and above.</para>
      </note>

      <para>The "pre-activate" signal is emitted before
<parameter>action</parameter> is activated.  This signal is intended for
applications to get notification before any action is activated.</para>

    </refsect2>

  </refsect1>

</refentry>
