path: root/docs/reference/pygtk-gtkradioaction.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-gtkradioaction">
  <refnamediv>
    <refname>gtk.RadioAction</refname>

    <refpurpose>an action that can be grouped so that only one can be
    active (new in PyGTK 2.4)</refpurpose>
  </refnamediv>

  <refsect1>
    <title>Synopsis</title>

    <classsynopsis language="python">
      <ooclass><classname>gtk.RadioAction</classname></ooclass>
      <ooclass><classname><link linkend="class-gtktoggleaction">gtk.ToggleAction</link></classname></ooclass>
      <constructorsynopsis language="python">
	<methodname><link linkend="constructor-gtkradioaction">gtk.RadioAction</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>
	<methodparam><parameter role="keyword">value</parameter></methodparam>
      </constructorsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtkradioaction--set-group">set_group</link></methodname>
	<methodparam><parameter role="keyword">group</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtkradioaction--get-group">get_group</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtkradioaction--set-current-value">set_current_value</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link linkend="method-gtkradioaction--get-current-value">get_current_value</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
    </classsynopsis>

  </refsect1>

  <refsect1>
    <title>Ancestry</title>

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

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


  <refsect1 id="properties-gtkradioaction">
    <title>gtk.RadioAction Properties</title>

    <para><link linkend="properties-gtkaction">gtk.Action Properties</link></para>
    <para><link linkend="properties-gtktoggleaction">gtk.ToggleAction 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>"current-value"</entry>
          <entry>Read-Write</entry>
          <entry>The value property of the currently active member of the
          group to which this action belongs.  This property is available in
          GTK+ 2.10 and above.</entry>
        </row>

	    <row valign="top">
	      <entry>"group"</entry>
	      <entry>Write</entry>
	      <entry>Sets a new group for a radio action. This property is
	      available in GTK+ 2.4 and above</entry>
	    </row>

	    <row valign="top">
	      <entry>"value"</entry>
	      <entry>Read-Write</entry>

	      <entry>The value is an arbitrary integer which can be used as
	      a convenient way to determine which action in the group is
	      currently active in an "activate" or "changed" signal
	      handler. See the <link
	      linkend="method-gtkradioaction--get-current-value"><methodname>get_current_value</methodname>()</link>
	      and the <link
	      linkend="method-gtkactiongroup--add-radio-actions"><methodname>gtk.ActionGroup.add_radio_actions</methodname>()</link>
	      methods for convenient ways to get and set this property. This
	      property is available in GTK+ 2.4 and above</entry>
	    </row>

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

  </refsect1>

  <refsect1 id="signal-prototypes-gtkradioaction">
    <title>gtk.RadioAction Signal Prototypes</title>

    <para><link linkend="signal-prototypes-gobject">gobject.GObject Signal Prototypes</link></para>
    <para><link linkend="signal-prototypes-gtkaction">gtk.Action Signal Prototypes</link></para>
    <para><link linkend="signal-prototypes-gtktoggleaction">gtk.ToggleAction Signal Prototypes</link></para>

    <variablelist>
      <varlistentry>
        <term>"<link linkend="signal-gtkradioaction--changed">changed</link>"</term>
        <listitem>
          <methodsynopsis language="python"><methodname>callback</methodname>
            <methodparam><parameter>radioaction</parameter></methodparam>
            <methodparam><parameter>current</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-gtkradioaction"><classname>gtk.RadioAction</classname></link>
is a subclass of <link
linkend="class-gtktoggleaction"><classname>gtk.ToggleAction</classname></link>
and similar to <link
linkend="class-gtkradiomenuitem"><classname>gtk.RadioMenuItem</classname></link>.
A number of radio actions can be linked together so that only one may be
active at any one time.</para>

  </refsect1>

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

    <programlisting><constructorsynopsis language="python">
	<methodname>gtk.RadioAction</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>
	<methodparam><parameter role="keyword">value</parameter></methodparam>
      </constructorsynopsis></programlisting>
    <variablelist>
      <varlistentry>
	<term><parameter role="keyword">name</parameter>&nbsp;:</term>
	<listitem><simpara>A unique name for the action</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 this action</simpara></listitem>
      </varlistentry>
      <varlistentry>
	<term><parameter role="keyword">stock_id</parameter>&nbsp;:</term>
	<listitem><simpara>The stock icon to display in widgets representing
	this action</simpara></listitem>
      </varlistentry>
      <varlistentry>
	<term><parameter role="keyword">value</parameter>&nbsp;:</term>
	<listitem><simpara>A unique integer value that <link
	linkend="method-gtkradioaction--get-current-value"><methodname>get_current_value()</methodname></link>
	should return if this action is selected.</simpara></listitem>
      </varlistentry>
      <varlistentry>
	<term><emphasis>Returns</emphasis>&nbsp;:</term>
	<listitem><simpara>a new <link
	linkend="class-gtkradioaction"><classname>gtk.RadioAction</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-gtkradioaction"><classname>gtk.RadioAction</classname></link>
object suing the properties specified by: <parameter>name</parameter>,
<parameter>label</parameter>, <parameter>tooltip</parameter>,
<parameter>stock_id</parameter> and <parameter>value</parameter>. 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-gtkradioaction--set-group">
      <title>gtk.RadioAction.set_group</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_group</methodname>
	  <methodparam><parameter role="keyword">group</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">group</parameter>&nbsp;:</term>
	  <listitem><simpara>another <link
	  linkend="class-gtkradioaction"><classname>gtk.RadioAction</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_group</methodname>() method sets the radio
group for the radio action to the same group as the <link
linkend="class-gtkradioaction"><classname>gtk.RadioAction</classname></link>
specified by <parameter>group</parameter> i.e. the radio action joins the
group.</para>

      <para>In PyGTK 2.6.2 and above, if <parameter>group</parameter> is
<literal>None</literal> the radio action is removed from its current
group.</para>

    </refsect2>

    <refsect2 id="method-gtkradioaction--get-group">
      <title>gtk.RadioAction.get_group</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_group</methodname>
	  <methodparam></methodparam>  </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>a list containing the radio actions in the
	  group or <parameter>None</parameter></simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>get_group</methodname>() method returns a list
containing the group that the radio action belongs to or
<literal>None</literal> if the radio action is not part of a group.</para>

    </refsect2>

    <refsect2 id="method-gtkradioaction--set-current-value">
      <title>gtk.RadioAction.set_current_value</title>

      <programlisting><methodsynopsis language="python">
        <methodname>set_current_value</methodname>
        <methodparam></methodparam>
      </methodsynopsis></programlisting>
      <variablelist>
        <varlistentry>
          <term><parameter role="keyword">current_value</parameter>&nbsp;:</term>
          <listitem><simpara>the new value.</simpara></listitem>
        </varlistentry>
      </variablelist>

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

      <para>The <methodname>get_current_value</methodname>() method sets the currently
      active group member to the member with value property current_value.</para>

    </refsect2>

    <refsect2 id="method-gtkradioaction--get-current-value">
      <title>gtk.RadioAction.get_current_value</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_current_value</methodname>
	  <methodparam></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>The value of the currently active group
	  member</simpara></listitem>
	</varlistentry>
      </variablelist>

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

      <para>The <methodname>get_current_value</methodname>() method returns
the "value" property of the the currently active member of the group that
the radio action belongs to.</para>

    </refsect2>

  </refsect1>

  <refsect1>
    <title>Signals</title>

    <refsect2 id="signal-gtkradioaction--changed">
      <title>The "changed" gtk.RadioAction Signal</title>

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

      <variablelist>
	<varlistentry>
	  <term><parameter>radioaction</parameter>&nbsp;:</term>
	  <listitem><simpara>the radioaction that received the
signal</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>current</parameter>&nbsp;:</term>
	  <listitem><simpara>the currently active <link
	  linkend="class-gtkradioaction"><classname>gtk.RadioAction</classname></link>
	  in the group</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 "changed" signal is emitted on every member of a radio group
when the active member is changed. The signal gets emitted after the
"activate" signals for the previous and current active members.</para>

    </refsect2>

  </refsect1>

</refentry>