<?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-gtkactivatable">
    <refnamediv>
        <refname>gtk.Activatable</refname>
        <refpurpose>An interface for activatable widgets.</refpurpose>
    </refnamediv>

    <refsect1>
        <title>Synopsis</title>

    <classsynopsis language="python">
        <ooclass><classname>gtk.Activatable</classname></ooclass>
        <ooclass><classname><link linkend="class-ginterface">gobject.GInterface</link></classname></ooclass>
    
    <methodsynopsis language="python">
        <methodname><link linkend="method-gtkactivatable--do-set-related-action">do_set_related_action</link></methodname>
        <methodparam><parameter role="keyword">action</parameter></methodparam>
    </methodsynopsis>
    <methodsynopsis language="python">
        <methodname><link linkend="method-gtkactivatable--get-related-action">get_related_action</link></methodname>
        <methodparam></methodparam>
    </methodsynopsis>
    <methodsynopsis language="python">
        <methodname><link linkend="method-gtkactivatable--get-use-action-appearence">get_use_action_appearence</link></methodname>
        <methodparam></methodparam>
    </methodsynopsis>
    <methodsynopsis language="python">
        <methodname><link linkend="method-gtkactivatable--set-related-action">set_related_action</link></methodname>
        <methodparam><parameter role="keyword">action</parameter></methodparam>
    </methodsynopsis>
    <methodsynopsis language="python">
        <methodname><link linkend="method-gtkactivatable--set-use-action-appearence">set_use_action_appearence</link></methodname>
        <methodparam><parameter role="keyword">use_appearence</parameter></methodparam>
    </methodsynopsis>
    <methodsynopsis language="python">
        <methodname><link linkend="method-gtkactivatable--sync-action-properties">sync_action_properties</link></methodname>
        <methodparam><parameter role="keyword">action</parameter></methodparam>
    </methodsynopsis>
    
    </classsynopsis>
    </refsect1>

    <refsect1>
        <title>Ancestry</title>

<synopsis>+-- <link linkend="class-ginterface">gobject.GInterface</link>
  +-- <link linkend="class-gtkactivatable">gtk.Activatable</link>
</synopsis>

    </refsect1>

    <refsect1 id="properties-gtkactivatable">
        <title>gtk.Activatable 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="3.5in"/>
                    <tbody>
                        <row valign="top">
                            <entry>"related-action"</entry>
                            <entry>Read/Write</entry>
                            <entry>
                                The action that this activatable will activate and receive updates from for various states and possibly appearance.
                                Note: <link linkend="class-gtkactivatable"><classname>gtk.Activatable</classname></link>
                                implementors need to handle the "related-action" property and call
                                <methodname><link linkend="method-gtkactivatable--do-set-related-action">gtk.Activatable.do_set_related_action</link></methodname>()
                                when it changes. This property is available in GTK+ 2.16 and above.
                            </entry>
                        </row>
                        <row valign="top">
                            <entry>"use-action-appearance"</entry>
                            <entry>Read/Write</entry>
                            <entry>
                                Whether this activatable should reset its layout and appearance when setting the related
                                action or when the action changes appearance.
                                See the <link linkend="class-gtkaction"><classname>gtk.Action</classname></link> documentation
                                directly to find which properties should be ignored by the
                                <link linkend="class-gtkactivatable"><classname>gtk.Activatable</classname></link>
                                when this property is <literal>False</literal>.
                                Note: <link linkend="class-gtkactivatable"><classname>gtk.Activatable</classname></link>
                                implementors need to handle the "related-action" property and call
                                <methodname><link linkend="method-gtkactivatable--do-set-related-action">gtk.Activatable.do_set_related_action</link></methodname>()
                                when it changes. Default value: <literal>True</literal>. This property is available in GTK+ 2.16 and above.
                            </entry>
                        </row>
                    </tbody>
                </tgroup>
            </informaltable>
        </blockquote>
    </refsect1>

    <refsect1>
        <title>Known Implementation</title>
        <para>
            <link linkend="class-gtkactivatable"><classname>gtk.Activatable</classname></link>
            is implementated by
            <link linkend="class-gtktearoffmenuitem"><classname>gtk.TearoffMenuItem</classname></link>,
            <link linkend="class-gtkoptionmenu"><classname>gtk.OptionMenu</classname></link>,
            <link linkend="class-gtklinkbutton"><classname>gtk.LinkButton</classname></link>,
            <link linkend="class-gtkradiobutton"><classname>gtk.RadioButton</classname></link>,
            <link linkend="class-gtkradiotoolbutton"><classname>gtk.RadioToolButton</classname></link>,
            <link linkend="class-gtktogglebutton"><classname>gtk.ToggleButton</classname></link>,
            <link linkend="class-gtkseparatormenuitem"><classname>gtk.SeparatorMenuItem</classname></link>,
            <link linkend="class-gtkimagemenuitem"><classname>gtk.ImageMenuItem</classname></link>,
            <link linkend="class-gtkcheckbutton"><classname>gtk.CheckButton</classname></link>,
            <link linkend="class-gtkradiomenuitem"><classname>gtk.RadioMenuItem</classname></link>,
            <link linkend="class-gtkbutton"><classname>gtk.Button</classname></link>,
            <link linkend="class-gtkmenutoolbutton"><classname>gtk.MenuToolButton</classname></link>,
            <link linkend="class-gtkmenuitem"><classname>gtk.MenuItem</classname></link>,
            <link linkend="class-gtkrecentchoosermenu"><classname>gtk.RecentChooserMenu</classname></link>,
            <link linkend="class-gtktoolitem"><classname>gtk.ToolItem</classname></link>,
            <link linkend="class-gtkseparatortoolitem"><classname>gtk.SeparatorToolItem</classname></link>,
            <link linkend="class-gtkcheckmenuitem"><classname>gtk.CheckMenuItem</classname></link>,
            <link linkend="class-gtktoolbutton"><classname>gtk.ToolButton</classname></link>,
            <link linkend="class-gtkfontbutton"><classname>gtkFontButton.</classname></link>,
            <link linkend="class-gtkscalebutton"><classname>gtk.ScaleButton</classname></link>,
            <link linkend="class-gtktoggletoolbutton"><classname>gtk.ToggleToolButton</classname></link>,
            <link linkend="class-gtkvolumebutton"><classname>gtk.VolumeButton</classname></link>,
            <link linkend="class-gtkcolorbutton"><classname>gtk.ColorButton</classname></link>.
        </para>
    </refsect1>

    <refsect1>
        <title>Description</title>

        <para>
            Activatable widgets can be connected to a
            <link linkend="class-gtkaction"><classname>gtk.Action</classname></link>
            and reflects the state of its action. A GtkActivatable can also provide
            feedback through its action, as they are responsible for activating their related actions. 
        </para>
        <para>
            When extending a class that is already <link linkend="class-gtkactivatable"><classname>gtk.Activatable</classname></link>
            it is only necessary to implement the
            <methodname><link linkend="method-gtkactivatable--do-sync-action-properties">gtk.Activatable.do_sync_action_properties</link></methodname> and
            <methodname><link linkend="method-gtkactivatable--do-update">gtk.Activatable.do_update</link></methodname>()
            class methods and chain up to the parent implementation, however when introducing a new
            <link linkend="class-gtkactivatable"><classname>gtk.Activatable</classname></link>
            class the "related-action" and "use-action-appearance" properties need to be handled by the implementor.
            Handling these properties is mostly a matter of installing the action pointer and boolean flag on your instance,
            and calling
            <methodname><link linkend="method-gtkactivatable--do-set-related-action">gtk.Activatable.do_set_related_action</link></methodname>() and
            <methodname><link linkend="method-gtkactivatable--sync-action-properties">gtk.Activatable.sync_action_properties</link></methodname>()
            at the appropriate times. 
        </para>
    </refsect1>

    <refsect1>
        <title>Methods</title>

        <refsect2 id="method-gtkactivatable--do-set-related-action">
            <title>gtk.Activatable.do_set_related_action</title>

            <programlisting><methodsynopsis language="python">
                <methodname>do_set_related_action</methodname>
                <methodparam><parameter>action</parameter></methodparam>
            </methodsynopsis></programlisting>
            
            <variablelist>
                <varlistentry>
                    <term><parameter role="keyword">action</parameter>&nbsp;:</term>
                        <listitem><simpara>
                            the <link linkend="class-gtkaction"><classname>gtk.Action</classname></link> to set.
                        </simpara></listitem>
                </varlistentry>
            </variablelist>
    
            <note>
                <para>This method is available in PyGTK 2.16 and above.</para>
            </note>

            <para>
                The <methodname>do_set_related_action</methodname>() method is an
                utility function for
                <link linkend="class-gtkactivatable"><classname>gtk.Activatable</classname></link>
                implementors. 
            </para>
            <para>
                When implementing <link linkend="class-gtkactivatable"><classname>gtk.Activatable</classname></link>
                you must call this when handling changes of the "related-action", and you must also
                use this to break references in GObject->dispose(). 
            </para>
            <para>
                This function adds a reference to the currently set related action for you,
                it also makes sure the GtkActivatable->update() method is called when the related
                <link linkend="class-gtkaction"><classname>gtk.Action</classname></link>
                properties change and registers to the action's proxy list. 
            </para>
            <note>
                Be careful to call this before setting the local copy of the
                <link linkend="class-gtkaction"><classname>gtk.Action</classname></link>
                property, since this function uses
                <methodname><link linkend="method-gtkactivatable--get-related-action">gtk.Activatable.get_related_action</link></methodname>()
                to retrieve the previous action
            </note>
        </refsect2>

        <refsect2 id="method-gtkactivatable--get-related-action">
            <title>gtk.Activatable.get_related_action</title>

            <programlisting><methodsynopsis language="python">
                <methodname>get_related_action</methodname>
                <methodparam></methodparam>
            </methodsynopsis></programlisting>
            
            <variablelist>
                <varlistentry>
                    <term><emphasis>Returns</emphasis>&nbsp;:</term>
                        <listitem><simpara>the related <link linkend="class-gtkaction"><classname>gtk.Action</classname></link>
                        if one is set. </simpara></listitem>
                </varlistentry>
            </variablelist>

            <note>
                <para>This method is available in PyGTK 2.16 and above.</para>
            </note>
    
            <para>
                The <methodname>get_related_action</methodname>() method gets the related
                <link linkend="class-gtkaction"><classname>gtk.Action</classname></link> for activatable.
            </para>
        </refsect2>

        <refsect2 id="method-gtkactivatable--get-use-action-appearence">
            <title>gtk.Activatable.get_use_action_appearence</title>

            <programlisting><methodsynopsis language="python">
                <methodname>get_use_action_appearence</methodname>
                <methodparam></methodparam>
            </methodsynopsis></programlisting>
            
            <variablelist>
                <varlistentry>
                    <term><emphasis>Returns</emphasis>&nbsp;:</term>
                        <listitem><simpara>whether activatable uses its actions appearance.
                        </simpara></listitem>
                </varlistentry>
            </variablelist>

            <note>
                <para>This method is available in PyGTK 2.16 and above.</para>
            </note>
    
            <para>
                The <methodname>get_use_action_appearence</methodname>() method gets whether
                this activatable should reset its layout and appearance when setting the
                related action or when the action changes appearance.
            </para>
        </refsect2>

        <refsect2 id="method-gtkactivatable--set-related-action">
            <title>gtk.Activatable.set_related_action</title>

            <programlisting><methodsynopsis language="python">
                <methodname>set_related_action</methodname>
                <methodparam><parameter>action</parameter></methodparam>
            </methodsynopsis></programlisting>
            
            <variablelist>
                <varlistentry>
                    <term><parameter role="keyword">action</parameter>&nbsp;:</term>
                        <listitem><simpara>the <link linkend="class-gtkaction"><classname>gtk.Action</classname></link> to set.
                        </simpara></listitem>
                </varlistentry>
            </variablelist>

            <note>
                <para>This method is available in PyGTK 2.16 and above.</para>
            </note>
            
            <note>
                <link linkend="class-gtkactivatable"><classname>gtk.Activatable</classname></link>
                implementors need to handle the "related-action" property and call
                <methodname><link linkend="method-gtkactivatable--do-set-related-action">gtk.Activatable.do_set_related_action</link></methodname>()
                when it changes.
            </note>

            <para>
                The <methodname>set_related_action</methodname>() method sets the related action on the activatable object. 
            </para>
        </refsect2>

        <refsect2 id="method-gtkactivatable--set-use-action-appearence">
            <title>gtk.Activatable.set_use_action_appearence</title>

            <programlisting><methodsynopsis language="python">
                <methodname>set_use_action_appearence</methodname>
                <methodparam><parameter>use_appearence</parameter></methodparam>
            </methodsynopsis></programlisting>
            
            <variablelist>
                <varlistentry>
                    <term><parameter role="keyword">use_appearence</parameter>&nbsp;:</term>
                        <listitem><simpara>whether to use the actions appearance.
                        </simpara></listitem>
                </varlistentry>
            </variablelist>

            <note>
                <para>This method is available in PyGTK 2.16 and above.</para>
            </note>
            
            <note>
                <link linkend="class-gtkactivatable"><classname>gtk.Activatable</classname></link>
                implementors need to handle the "related-action" property and call
                <methodname><link linkend="method-gtkactivatable--do-set-related-action">gtk.Activatable.do_set_related_action</link></methodname>()
                when it changes.
            </note>

            <para>
                The <methodname>set_use_action_appearence</methodname>() method sets whether
                this activatable should reset its layout and appearance when setting the
                related action or when the action changes appearance 
            </para>
        </refsect2>

        <refsect2 id="method-gtkactivatable--sync-action-properties">
            <title>gtk.Activatable.sync_action_properties</title>

            <programlisting><methodsynopsis language="python">
                <methodname>sync_action_properties</methodname>
                <methodparam><parameter>action</parameter></methodparam>
            </methodsynopsis></programlisting>
            
            <variablelist>
                <varlistentry>
                    <term><parameter role="keyword">action</parameter>&nbsp;:</term>
                        <listitem><simpara>the related <link linkend="class-gtkaction"><classname>gtk.Action</classname></link>
                        or <literal>None</literal> 
                        </simpara></listitem>
                </varlistentry>
            </variablelist>

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

            <para>
                The <methodname>set_use_action_appearence</methodname>() method is called to
                update the activatable completely, this is called internally when the "related-action"
                property is set or unset and by the implementing class when "use-action-appearance" changes.
            </para>
        </refsect2>
    </refsect1>
</refentry>
