path: root/docs/reference/pygtk-gtkaction.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-gtkaction">
  <refnamediv>
    <refname>gtk.Action</refname>
    <refpurpose>an action which can be triggered by a menu or toolbar
item (new in PyGTK 2.4)</refpurpose>
  </refnamediv>

  <refsect1>
    <title>Synopsis</title>

    <classsynopsis language="python">
      <ooclass><classname>gtk.Action</classname></ooclass>
      <ooclass><classname><link linkend="class-gobject">gobject.GObject</link></classname></ooclass>
      <constructorsynopsis language="python">
	<methodname><link linkend="constructor-gtkaction">gtk.Action</link></methodname>
	<methodparam><parameter role="keyword">name</parameter></methodparam>
	<methodparam><parameter role="keyword">label</parameter></methodparam>
	<methodparam><parameter role="keyword">tooltip</parameter></methodparam>
	<methodparam><parameter role="keyword">stock_id</parameter></methodparam>
      </constructorsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtkaction--get-name">get_name</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtkaction--is-sensitive">is_sensitive</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtkaction--get-sensitive">get_sensitive</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtkaction--is-visible">is_visible</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtkaction--get-visible">get_visible</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtkaction--activate">activate</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtkaction--create-icon">create_icon</link></methodname>
	<methodparam><parameter role="keyword">icon_size</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtkaction--create-menu-item">create_menu_item</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtkaction--create-tool-item">create_tool_item</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtkaction--connect-proxy">connect_proxy</link></methodname>
	<methodparam><parameter role="keyword">proxy</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtkaction--disconnect-proxy">disconnect_proxy</link></methodname>
	<methodparam><parameter role="keyword">proxy</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtkaction--get-proxies">get_proxies</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtkaction--connect-accelerator">connect_accelerator</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtkaction--disconnect-accelerator">disconnect_accelerator</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtkaction--block-activate-from">block_activate_from</link></methodname>
	<methodparam><parameter role="keyword">proxy</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtkaction--unblock-activate-from">unblock_activate_from</link></methodname>
	<methodparam><parameter role="keyword">proxy</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtkaction--get-accel-path">get_accel_path</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtkaction--set-accel-path">set_accel_path</link></methodname>
	<methodparam><parameter role="keyword">accel_path</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtkaction--set-accel-group">set_accel_group</link></methodname>
	<methodparam><parameter role="keyword">accel_group</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtkaction--set-sensitive">set_sensitive</link></methodname>
	<methodparam><parameter role="keyword">sensitive</parameter></methodparam>
      </methodsynopsis>
       <methodsynopsis language="python">
	<methodname><link linkend="method-gtkaction--set-visible">set_visible</link></methodname>
	<methodparam><parameter role="keyword">visible</parameter></methodparam>
      </methodsynopsis>
       <methodsynopsis language="python">
	<methodname><link linkend="method-gtkaction--set-menu-item-type">set_menu_item_type</link></methodname>
	<methodparam><parameter role="keyword">visible</parameter></methodparam>
      </methodsynopsis>
       <methodsynopsis language="python">
	<methodname><link linkend="method-gtkaction--set-tool-item-type">set_tool_item_type</link></methodname>
	<methodparam><parameter role="keyword">visible</parameter></methodparam>
      </methodsynopsis>
   </classsynopsis>

  </refsect1>

  <refsect1>
    <title>Ancestry</title>

<synopsis>+-- <link linkend="class-gobject">gobject.GObject</link>
  +-- <link linkend="class-gtkaction">gtk.Action</link>
</synopsis>

  </refsect1>

  <refsect1 id="properties-gtkaction">
    <title>gtk.Action 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>"action-group"</entry>
	      <entry>Read-Write</entry>

	      <entry>The <link
linkend="class-gtkactiongroup"><classname>gtk.ActionGroup</classname></link>
this <link
linkend="class-gtkaction"><classname>gtk.Action</classname></link> is
associated with, or <literal>None</literal> (for internal use).</entry>
	    </row>

	    <row valign="top">
	      <entry>"hide-if-empty"</entry>
	      <entry>Read-Write</entry>
	      <entry>If <literal>TRUE</literal>, empty menu proxies for this
action are hidden.</entry>
	    </row>

	    <row valign="top">
	      <entry>"is-important"</entry>
	      <entry>Read-Write</entry>
	      <entry>If <literal>TRUE</literal>, <link
linkend="class-gtktoolitem"><classname>gtk.ToolItem</classname></link>
proxies for this action show text in
<literal>gtk.TOOLBAR_BOTH_HORIZ</literal> mode.</entry>
	    </row>

	    <row valign="top">
	      <entry>"label"</entry>
	      <entry>Read-Write</entry>
	      <entry>The label used for menu items and buttons that activate
this action.</entry>
	    </row>

	    <row valign="top">
	      <entry>"name"</entry>
	      <entry>Read-Write-Construct Only</entry>
	      <entry>A unique name for the action.</entry>
	    </row>

	    <row valign="top">
	      <entry>"sensitive"</entry>
	      <entry>Read-Write</entry>
	      <entry>If <literal>TRUE</literal>, the action is
enabled.</entry>
	    </row>

	    <row valign="top">
	      <entry>"short-label"</entry>
	      <entry>Read-Write</entry>
	      <entry>A shorter label that may be used on toolbar
buttons.</entry>
	    </row>

	    <row valign="top">
	      <entry>"stock-id"</entry>
	      <entry>Read-Write</entry>
	      <entry>The stock icon displayed in widgets representing this
action.</entry>
	    </row>

	    <row valign="top">
	      <entry>"tooltip"</entry>
	      <entry>Read-Write</entry>
	      <entry>A tooltip for this action.</entry>
	    </row>

	    <row valign="top">
	      <entry>"visible"</entry>
	      <entry>Read-Write</entry>
	      <entry>If <literal>TRUE</literal>, the action is
visible.</entry>
	    </row>

	    <row valign="top">
	      <entry>"visible-horizontal"</entry>
	      <entry>Read-Write</entry>
	      <entry>If <literal>TRUE</literal>, the toolbar item is
visible when the toolbar is in a horizontal orientation.</entry>
	    </row>

	    <row valign="top">
	      <entry>"visible-vertical"</entry>
	      <entry>Read-Write</entry>
	      <entry>If <literal>TRUE</literal>, the toolbar item is 
visible when the toolbar is in a vertical orientation.</entry>
	    </row>

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

  </refsect1>

  <refsect1 id="signal-prototypes-gtkaction">
    <title>gtk.Action Signal Prototypes</title>

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

    <variablelist>
      <varlistentry>
        <term>"<link linkend="signal-gtkaction--activate">activate</link>"</term>
        <listitem>
          <methodsynopsis language="python"><methodname>callback</methodname>
            <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 widget is available in PyGTK 2.4 and above.</para>
    </note>

    <para>A <link
linkend="class-gtkaction"><classname>gtk.Action</classname></link>
represents operations that the user can perform, along with some information
how it should be presented in the interface. Each <link
linkend="class-gtkaction"><classname>gtk.Action</classname></link> provides
methods to create icons, menu items and toolbar items representing
itself.</para>

    <para>As well as the callback that is called when the action gets
activated, the following also gets associated with the action:</para>

    <itemizedlist>
      <listitem>
	<simpara>a name (not translated, for path lookup)</simpara>
      </listitem>
      <listitem>
	<simpara>a label (translated, for display)</simpara>
      </listitem>
      <listitem>
	<simpara>an accelerator</simpara>
      </listitem>
      <listitem>
	<simpara>whether the label indicates a stock id</simpara>
      </listitem>
      <listitem>
	<simpara>a tooltip (optional, translated)</simpara>
      </listitem>
      <listitem>
	<simpara>a toolbar label (optional, shorter than label)</simpara>
      </listitem>
   </itemizedlist>

    <para>The action will also have some state information:</para>

    <itemizedlist>
      <listitem>
	<simpara>visible (shown/hidden)</simpara>
      </listitem>
      <listitem>
	<simpara>sensitive (enabled/disabled)</simpara>
      </listitem>
   </itemizedlist>

    <para>Apart from regular actions, there are toggle actions, which can be
toggled between two states and radio actions, where only one in a group
can be in the "active" state. Other actions can be implemented as <link
linkend="class-gtkaction"><classname>gtk.Action</classname></link>
subclasses.</para>

    <para>Each <link
linkend="class-gtkaction"><classname>gtk.Action</classname></link> can have
one or more proxy menu items, toolbar buttons or other proxy
widgets. Proxies mirror the state of the action (text label, tooltip, icon,
visible, sensitive, etc), and should change when the action's state
changes. When the proxy is activated, it should activate its action. </para>

  </refsect1>

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

    <programlisting><constructorsynopsis language="python">
	<methodname>gtk.Action</methodname>
	<methodparam><parameter role="keyword">name</parameter></methodparam>
	<methodparam><parameter role="keyword">label</parameter></methodparam>
	<methodparam><parameter role="keyword">tooltip</parameter></methodparam>
	<methodparam><parameter role="keyword">stock_id</parameter></methodparam>
      </constructorsynopsis></programlisting>
    <variablelist>
      <varlistentry>
	<term><parameter role="keyword">name</parameter>&nbsp;:</term>
	<listitem><simpara>a unique name for the <link
linkend="class-gtkaction"><classname>gtk.Action</classname></link></simpara></listitem>
      </varlistentry>
      <varlistentry>
	<term><parameter role="keyword">label</parameter>&nbsp;:</term>
	<listitem><simpara>the label displayed in menu items and on
buttons</simpara></listitem>
      </varlistentry>
      <varlistentry>
	<term><parameter role="keyword">tooltip</parameter>&nbsp;:</term>
	<listitem><simpara>a tooltip for the action</simpara></listitem>
      </varlistentry>
      <varlistentry>
	<term><parameter role="keyword">stock_id</parameter>&nbsp;:</term>
	<listitem><simpara>the stock icon to display in widgets
representing the action</simpara></listitem>
      </varlistentry>
      <varlistentry>
	<term><emphasis>Returns</emphasis>&nbsp;:</term>
	<listitem><simpara>a new <link
linkend="class-gtkaction"><classname>gtk.Action</classname></link></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-gtkaction"><classname>gtk.Action</classname></link>
object. To add the action to a <link
linkend="class-gtkactiongroup"><classname>gtk.ActionGroup</classname></link>
and set the accelerator for the action, call the <link
linkend="method-gtkactiongroup--add-action-with-accel"><methodname>gtk.ActionGroup.add_action_with_accel()</methodname></link>.</para>

  </refsect1>

  <refsect1>
    <title>Methods</title>

    <refsect2 id="method-gtkaction--get-name">
      <title>gtk.Action.get_name</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_name</methodname>
	  <methodparam></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>the name of the action.</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>get_name</methodname>() method returns the value
of the "name" property containing the name of the action.</para>

    </refsect2>

    <refsect2 id="method-gtkaction--is-sensitive">
      <title>gtk.Action.is_sensitive</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>is_sensitive</methodname>
	  <methodparam></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara><literal>TRUE</literal> if the action and its
associated action group are both sensitive.</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>is_sensitive</methodname>() method returns
<literal>TRUE</literal> if the action is effectively sensitive i.e. both the
<link linkend="class-gtkaction"><classname>gtk.Action</classname></link> and
its associated <link
linkend="class-gtkactiongroup"><classname>gtk.ActionGroup</classname></link>
are sensitive.</para>

    </refsect2>

    <refsect2 id="method-gtkaction--get-sensitive">
      <title>gtk.Action.get_sensitive</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_sensitive</methodname>
	  <methodparam></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara><literal>TRUE</literal> if the action itself
is sensitive.</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>get_sensitive</methodname>() method returns the
value of the "sensitive" property. If "sensitive" is <literal>TRUE</literal>
the action itself is sensitive. Note that this doesn't necessarily mean
effective sensitivity. See the <link
linkend="method-gtkaction--is-sensitive"><methodname>is_sensitive()</methodname></link>
method for more information.</para>

    </refsect2>

    <refsect2 id="method-gtkaction--is-visible">
      <title>gtk.Action.is_visible</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>is_visible</methodname>
	  <methodparam></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara><literal>TRUE</literal> if the action and
its associated action group are both visible.</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>is_visible</methodname>() method returns
<literal>TRUE</literal> if the action is effectively visible i.e. both the
<link linkend="class-gtkaction"><classname>gtk.Action</classname></link> and
its associated <link
linkend="class-gtkactiongroup"><classname>gtk.ActionGroup</classname></link>
as visible.</para>

    </refsect2>

    <refsect2 id="method-gtkaction--get-visible">
      <title>gtk.Action.get_visible</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_visible</methodname>
	  <methodparam></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara><literal>TRUE</literal> if the action itself
is visible.</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>get_visible</methodname>() method returns the
value of the "visible" property. If "visible" is <literal>TRUE</literal> the
<link linkend="class-gtkaction"><classname>gtk.Action</classname></link>
itself is visible. Note that this doesn't necessarily mean effective
visibility. See the <link
linkend="method-gtkaction--is-visible"><methodname>is_visible()</methodname></link>
method for more information.</para>

    </refsect2>

    <refsect2 id="method-gtkaction--activate">
      <title>gtk.Action.activate</title>

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

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

      <para>The <methodname>activate</methodname>() method emits the
"activate" signal on the <link
linkend="class-gtkaction"><classname>gtk.Action</classname></link>, if it
isn't insensitive. This gets called by the proxy widgets when they get
activated. It can also be used to manually activate an action.</para>

    </refsect2>

    <refsect2 id="method-gtkaction--create-icon">
      <title>gtk.Action.create_icon</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>create_icon</methodname>
	  <methodparam><parameter role="keyword">icon_size</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">icon_size</parameter>&nbsp;:</term>
	  <listitem><simpara>the size of the icon that should be
created.</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>a widget that displays the icon for this
action.</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>create_icon</methodname>() method creates and
returns a <link
linkend="class-gtkimage"><classname>gtk.Image</classname></link> with the
size specified by <parameter>size</parameter> from the icon contained in the
"stock-id" property if it exists. The value of <parameter>size</parameter>
must be one of:</para>

    <itemizedlist>
      <listitem>
	  <simpara><literal>gtk.ICON_SIZE_MENU</literal></simpara>
      </listitem>
      <listitem>
	  <simpara><literal>gtk.ICON_SIZE_SMALL_TOOLBAR</literal></simpara>
      </listitem>
      <listitem>
	  <simpara><literal>gtk.ICON_SIZE_LARGE_TOOLBAR</literal></simpara>
      </listitem>
      <listitem>
	  <simpara><literal>gtk.ICON_SIZE_BUTTON</literal></simpara>
      </listitem>
      <listitem>
	  <simpara><literal>gtk.ICON_SIZE_DND</literal></simpara>
      </listitem>
      <listitem>
	  <simpara><literal>gtk.ICON_SIZE_DIALOG</literal></simpara>
      </listitem>
   </itemizedlist>

      <para>This method is intended for use by <link
linkend="class-gtkaction"><classname>gtk.Action</classname></link>
implementations to create icons displayed in the proxy widgets.</para>

    </refsect2>

    <refsect2 id="method-gtkaction--create-menu-item">
      <title>gtk.Action.create_menu_item</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>create_menu_item</methodname>
	  <methodparam></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>a menu item connected to the
action.</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>create_menu_item</methodname>() method creates
and returns a menu item widget that proxies for the <link
linkend="class-gtkaction"><classname>gtk.Action</classname></link>.</para>

    </refsect2>

    <refsect2 id="method-gtkaction--create-tool-item">
      <title>gtk.Action.create_tool_item</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>create_tool_item</methodname>
	  <methodparam></methodparam>  </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>a tool item connected to the
action.</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>create_tool_item</methodname>() method creates
and returns a tool item widget that proxies for the <link
linkend="class-gtkaction"><classname>gtk.Action</classname></link>.</para>

    </refsect2>

    <refsect2 id="method-gtkaction--connect-proxy">
      <title>gtk.Action.connect_proxy</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>connect_proxy</methodname>
	  <methodparam><parameter role="keyword">proxy</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">proxy</parameter>&nbsp;:</term>
	  <listitem><simpara>the proxy widget</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>connect_proxy</methodname>() method connects the
widget specified by <parameter>proxy</parameter> to the <link
linkend="class-gtkaction"><classname>gtk.Action</classname></link> object as
a proxy. This method synchronizes various properties of the <link
linkend="class-gtkaction"><classname>gtk.Action</classname></link> with the
widget (such as label text, icon, tooltip, etc), and attaches a callback so
that the <link
linkend="class-gtkaction"><classname>gtk.Action</classname></link> is
activated when <parameter>proxy</parameter> is.</para>

      <para>If <parameter>proxy</parameter> is already connected to another
<link linkend="class-gtkaction"><classname>gtk.Action</classname></link>, it
is disconnected first. The <link
linkend="class-gtkaction"><classname>gtk.Action</classname></link> should be
added to a <link
linkend="class-gtkactiongroup"><classname>gtk.ActionGroup</classname></link>
before calling this method.</para>

    </refsect2>

    <refsect2 id="method-gtkaction--disconnect-proxy">
      <title>gtk.Action.disconnect_proxy</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>disconnect_proxy</methodname>
	  <methodparam><parameter role="keyword">proxy</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">proxy</parameter>&nbsp;:</term>
	  <listitem><simpara>the proxy widget</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>disconnect_proxy</methodname>() method
disconnects the widget specified by <parameter>proxy</parameter> from the
<link
linkend="class-gtkaction"><classname>gtk.Action</classname></link>. This
method does <emphasis>not</emphasis> destroy the widget. The <link
linkend="class-gtkaction"><classname>gtk.Action</classname></link> should be
added to a <link
linkend="class-gtkactiongroup"><classname>gtk.ActionGroup</classname></link>
before calling this method.</para>

    </refsect2>

    <refsect2 id="method-gtkaction--get-proxies">
      <title>gtk.Action.get_proxies</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_proxies</methodname>
	  <methodparam></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>a list of proxy widgets.</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>get_proxies</methodname>() method returns a list
containing the proxy widgets associated with the <link
linkend="class-gtkaction"><classname>gtk.Action</classname></link>.</para>

    </refsect2>

    <refsect2 id="method-gtkaction--connect-accelerator">
      <title>gtk.Action.connect_accelerator</title>

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

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

      <para>The <methodname>connect_accelerator</methodname>() method
installs the accelerator for the <link
linkend="class-gtkaction"><classname>gtk.Action</classname></link> if it has
an associated accel path and <link
linkend="class-gtkaccelgroup"><classname>gtk.AccelGroup</classname></link>. See
the <link
linkend="method-gtkaction--set-accel-path"><methodname>set_accel_path()</methodname></link>
and the <link
linkend="method-gtkaction--set-accel-group"><methodname>set_accel_group()</methodname></link>
methods.</para>

      <para>Since multiple proxies may independently trigger the
installation of the accelerator, the <link
linkend="class-gtkaction"><classname>gtk.Action</classname></link> counts
the number of times this method has been called and doesn't remove the
accelerator until <link
linkend="method-gtkaction--disconnect-accelerator"><methodname>disconnect_accelerator()</methodname></link>
has been called as many times.</para>

    </refsect2>

    <refsect2 id="method-gtkaction--disconnect-accelerator">
      <title>gtk.Action.disconnect_accelerator</title>

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

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

      <para>The <methodname>disconnect_accelerator</methodname>() method
undoes the effect of one call to the <link
linkend="method-gtkaction--connect-accelerator"><methodname>connect_accelerator()</methodname></link>
method.</para>

    </refsect2>

    <refsect2 id="method-gtkaction--block-activate-from">
      <title>gtk.Action.block_activate_from</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>block_activate_from</methodname>
	  <methodparam><parameter role="keyword">proxy</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">proxy</parameter>&nbsp;:</term>
	  <listitem><simpara>a proxy widget</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>block_activate_from</methodname>() method
disables calls to the <link
linkend="method-gtkaction--activate"><methodname>activate()</methodname></link>
method by signals on the widget specified by
<parameter>proxy</parameter>. This is used to break notification loops for
things like check or radio actions.</para>

      <para>This method is intended for use by <link
linkend="class-gtkaction"><classname>gtk.Action</classname></link>
implementations.</para>

    </refsect2>

    <refsect2 id="method-gtkaction--unblock-activate-from">
      <title>gtk.Action.unblock_activate_from</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>unblock_activate_from</methodname>
	  <methodparam><parameter role="keyword">proxy</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">proxy</parameter>&nbsp;:</term>
	  <listitem><simpara>a proxy widget</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>unblock_activate_from</methodname>() method
re-enables calls to the <link
linkend="method-gtkaction--activate"><methodname>activate()</methodname></link>
method by signals on the widget specified by <parameter>proxy</parameter>.
This undoes the blocking done by the <link
linkend="method-gtkaction--block-activate-from"><methodname>block_activate_from()</methodname></link>
method.</para>

      <para>This method is intended for use by <link
linkend="class-gtkaction"><classname>gtk.Action</classname></link>
implementations.</para>

    </refsect2>

    <refsect2 id="method-gtkaction--get-accel-path">
      <title>gtk.Action.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 associated with the action
or <literal>None</literal></simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>get_accel_path</methodname>() method returns the
accel path for the action or <literal>None</literal> if no accel path is
set.</para>

    </refsect2>

    <refsect2 id="method-gtkaction--set-accel-path">
      <title>gtk.Action.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>the accelerator path</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>set_accel_path</methodname>() method sets the
accel path for the action to the value of
<parameter>accel_path</parameter>. All proxy widgets associated with the
action will have this accel path, so that their accelerators are
consistent.</para>

    </refsect2>

    <refsect2 id="method-gtkaction--set-accel-group">
      <title>gtk.Action.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> or <literal>None</literal></simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>set_accel_group</methodname>() method sets the
<link
linkend="class-gtkaccelgroup"><classname>gtk.AccelGroup</classname></link>
specified by <parameter>accel_group</parameter> as the accelerator group for
the <link
linkend="class-gtkaction"><classname>gtk.Action</classname></link>.</para>

    </refsect2>

    <refsect2 id="method-gtkaction--set-sensitive">
      <title>gtk.Action.set_sensitive</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_sensitive</methodname>
	  <methodparam><parameter role="keyword">sensitive</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">sensitive</parameter>&nbsp;:</term>
	  <listitem><simpara>if <literal>TRUE</literal> make the action
sensitive</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>set_sensitive</methodname>() method sets the
"sensitive" property to the value of <parameter>sensitive</parameter>. Note
that this doesn't necessarily set the effective sensitivity. See the <link
linkend="method-gtkaction--is-sensitive"><methodname>is_sensitive</methodname>()</link>
method for more information.</para>

    </refsect2>

    <refsect2 id="method-gtkaction--set-visible">
      <title>gtk.Action.set_visible</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_visible</methodname>
	  <methodparam><parameter role="keyword">visible</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">visible</parameter>&nbsp;:</term>
	  <listitem><simpara>if <literal>TRUE</literal> make the action
visible</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>set_visible</methodname>() method sets the
"visible" property to the value of <parameter>visible</parameter>. Note that
this doesn't necessarily set the effective visibility. See the <link
linkend="method-gtkaction--is-visible"><methodname>is_visible</methodname>()</link>
method for more information.</para>

    </refsect2>

    <refsect2 id="method-gtkaction--set-menu-item-type">
      <title>gtk.Action.set_menu_item_type</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_menu_item_type</methodname>
	  <methodparam><parameter role="keyword">visible</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">type</parameter>&nbsp;:</term>
	  <listitem><simpara>the type of menuitem to be created for the
	  action</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>set_menu_item_type</methodname>() method is a
      classmethod that sets the type of menuitem to be created for the
      action to that specified by <parameter>type</parameter>. This is
      useful when using the <link
      linkend="class-gtkuimanager"><classname>gtk.UIManager</classname></link>
      and you would like to use something other than a <link
      linkend="class-gtkimagemenuitem"><classname>gtk.ImageMenuItem</classname></link>
      (<link
      linkend="class-gtkaction"><classname>gtk.Action</classname></link>) or
      a <link
      linkend="class-gtkcheckmenuitem"><classname>gtk.CheckMenuItem</classname></link>
      (<link
      linkend="class-gtktoogleaction"><classname>gtk.ToogleAction</classname></link>
      or <link
      linkend="class-gtkradioaction"><classname>gtk.RadioAction</classname></link>).</para>

    </refsect2>

    <refsect2 id="method-gtkaction--set-tool-item-type">
      <title>gtk.Action.set_tool_item_type</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_tool_item_type</methodname>
	  <methodparam><parameter role="keyword">visible</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">type</parameter>&nbsp;:</term>
	  <listitem><simpara>the type of toolitem to be created for the
	  action</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>set_tool_item_type</methodname>() method is a
      classmethod that sets the type of toolitem to be created for the
      action to that specified by <parameter>type</parameter>. This is
      useful when using the <link
      linkend="class-gtkuimanager"><classname>gtk.UIManager</classname></link>
      and you would like to use something other than a <link
      linkend="class-gtktoolbutton"><classname>gtk.ToolButton</classname></link>
      (<link
      linkend="class-gtkaction"><classname>gtk.Action</classname></link>) or
      a <link
      linkend="class-gtktoggletoolbutton"><classname>gtk.ToggleToolButton</classname></link>
      (<link
      linkend="class-gtktoogleaction"><classname>gtk.ToogleAction</classname></link>
      or <link
      linkend="class-gtkradioaction"><classname>gtk.RadioAction</classname></link>).</para>

      <para>For example, to use a <link
      linkend="class-gtkmenutoolbutton"><classname>gtk.MenuToolButton</classname></link>
      in a toolbar you would subclass <link
      linkend="class-gtkaction"><classname>gtk.Action</classname></link>:</para>

      <programlisting>
    class MenuToolAction(gtk.Action):
        __gtype_name__ = "MenuToolAction"

    gobject.type_register(MenuToolAction)
      </programlisting>

      <para>and then call <link
      linkend="method-gtkaction--set-tool-item-type"><methodname>set_tool_item_type</methodname>()</link>:</para>

      <programlisting>
    MenuToolAction.set_tool_item_type(gtk.MenuToolButton)
      </programlisting>

      <para>You have to create, name and add an instance of
      <parameter>MenuToolAction</parameter> to your <link
      linkend="class-gtkactiongroup"><classname>gtk.ActionGroup</classname></link>:</para>

      <programlisting>
    actiongroup.add_action(MenuToolAction("my_menutoolaction", "_MTB_label",
                                          "do something", None))
      </programlisting>

      <para>The ui description should reference the
      <parameter>MenuToolAction</parameter> like:</para>

      <programlisting>
    &lt;toolitem action="my_menutoolaction"/&gt;
      </programlisting>

      <para>After the <link
      linkend="class-gtkuimanager"><classname>gtk.UIManager</classname></link>
      creates the toolbar including the <link
      linkend="class-gtkmenutoolbutton"><classname>gtk.MenuToolButton</classname></link>
      proxy for the <parameter>MenuToolAction</parameter>, you would have to
      create and add a menu to the <link
      linkend="class-gtkmenutoolbutton"><classname>gtk.MenuToolButton</classname></link>
      instance.</para>

      <para>This technique can be extended by subclassing <link
      linkend="class-gtktoolitem"><classname>gtk.ToolItem</classname></link>
      and adding custom widgets to it.</para>

    </refsect2>

  </refsect1>

  <refsect1>
    <title>Signals</title>

    <refsect2 id="signal-gtkaction--activate">
      <title>The "activate" gtk.Action Signal</title>

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

      <variablelist>
	<varlistentry>
	  <term><parameter>action</parameter>&nbsp;:</term>
	  <listitem><simpara>the <link
linkend="class-gtkaction"><classname>gtk.Action</classname></link> 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 PyGTK 2.4 and above.</para>
      </note>

      <para>The "activate" signal is emitted when
<parameter>action</parameter> is activated.</para>

    </refsect2>

  </refsect1>

</refentry>