<?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-gtkrecentaction">
    <refnamediv>
        <refname>gtk.RecentAction</refname>
        <refpurpose>An action of which represents a list of recently used files (new in PyGTK 2.12)</refpurpose>
    </refnamediv>

    <refsect1>
        <title>Synopsis</title>

    <classsynopsis language="python">
        <ooclass><classname>gtk.RecentAction</classname></ooclass>
        <ooclass><classname><link linkend="class-gtkaction">gtk.Action</link></classname></ooclass>
    
        <constructorsynopsis language="python">
            <methodname><link linkend="constructor-gtkrecentaction">gtk.RecentAction</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-gtkrecentaction--get-show-numbers">get_show_numbers</link></methodname>
            <methodparam></methodparam>
        </methodsynopsis>
        <methodsynopsis language="python">
            <methodname><link linkend="method-gtkrecentaction--set-show-numbers">set_show_numbers</link></methodname>
            <methodparam><parameter role="keyword">show_numbers</parameter></methodparam>
        </methodsynopsis>

    </classsynopsis>

<programlisting>
<emphasis role="bold">Functions</emphasis>
 
<methodsynopsis language="python">
    <methodname><link linkend="function-gtk--recent-action-new-for-manager">gtk.recent_action_new_for_manager</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">manager</parameter></methodparam>
  </methodsynopsis></programlisting>

    </refsect1>

    <refsect1>
        <title>Ancestry</title>

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

    </refsect1>

    <refsect1 id="properties-gtkrecentaction">
      <title>gtk.RecentAction Properties</title>

      <para><link linkend="properties-gtkaction">gtk.Action 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>"show-numbers"</entry>
                <entry>Read-Write</entry>
                <entry>Whether the items should be displayed with a number.
                Default value: <literal>False</literal></entry>
              </row>
            </tbody>
          </tgroup>
        </informaltable>
      </blockquote>

    </refsect1>

    <refsect1>
        <title>Description</title>
            <para>
                A <link linkend="class-gtkrecentaction">gtk.RecentAction</link> represents a list
                of recently used files, which can be shown by widgets such as
                <link linkend="class-gtkrecentchooserdialog">gtk.RecentChooserDialog</link> or
                <link linkend="class-gtkrecentchoosermenu">gtk.RecentChooserMenu</link>. 
            </para>
            <para>
                To construct a submenu showing recently used files, use a
                <link linkend="class-gtkrecentaction">gtk.RecentAction</link>
                as the action for a &#60;menuitem&#62;. To construct a menu toolbutton showing
                the recently used files in the popup menu, use a
                <link linkend="class-gtkrecentaction">gtk.RecentAction</link>
                as the action for a &#60;toolitem&#62; element. 
            </para>
    </refsect1>

    <refsect1>
        <title>Constructor</title>

        <refsect2 id="constructor-gtkrecentaction">
            <title>gtk.RecentAction</title>

            <programlisting><constructorsynopsis language="python">
                <methodname>gtk.RecentAction</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 action </simpara></listitem>
                </varlistentry>
                <varlistentry>
                    <term><parameter role="keyword">label</parameter>&nbsp;:</term>
                        <listitem><simpara>the label displayed in menu items and on buttons, or <literal>None</literal>.</simpara></listitem>
                </varlistentry>
                <varlistentry>
                    <term><parameter role="keyword">tooltip</parameter>&nbsp;:</term>
                        <listitem><simpara>a tooltip for the action, or <literal>None</literal>.</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, or <literal>None</literal>.</simpara></listitem>
                </varlistentry>
                <varlistentry>
                <term><emphasis>Returns</emphasis>&nbsp;:</term>
                <listitem><simpara>a new
                    <link linkend="class-gtkrecentaction"><classname>gtk.RecentAction</classname></link>
                    </simpara></listitem>
              </varlistentry>
            </variablelist>

            <note>
              <para>This constructor is available in PyGTK 2.12 and above.</para>
            </note>
      
            <para>
                Creates a new
                <link linkend="class-gtkrecentaction"><classname>gtk.RecentAction</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
                <methodname><link linkend="method-gtkactiongroup--add-action-with-accel">gtk.ActionGroup.add_action_with_accel</link></methodname>().
            </para>

        </refsect2>
    </refsect1>

    <refsect1>
        <title>Methods</title>

        <refsect2 id="method-gtkrecentaction--get-show-numbers">
            <title>gtk.RecentAction.get_show_numbers</title>

            <programlisting><methodsynopsis language="python">
                <methodname>get_show_numbers</methodname>
                <methodparam></methodparam>
            </methodsynopsis></programlisting>
            
            <variablelist>
                <varlistentry>
                    <term><emphasis>Returns</emphasis>&nbsp;:</term>
                        <listitem><simpara><literal>True</literal> if numbers should be shown.</simpara></listitem>
                </varlistentry>
            </variablelist>

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

            <para>
                The <methodname>get_show_numbers</methodname>() method returns the value set by
                <methodname><link linkend="method-gtkrecentaction--set-show-numbers">gtk.RecentAction.set_show_numbers</link></methodname>().
            </para>
        </refsect2>

        <refsect2 id="method-gtkrecentaction--set-show-numbers">
            <title>gtk.RecentAction.set_show_numbers</title>

            <programlisting><methodsynopsis language="python">
                <methodname>set_show_numbers</methodname>
                <methodparam><parameter>show_numbers</parameter></methodparam>
            </methodsynopsis></programlisting>
            
            <variablelist>
                <varlistentry>
                    <term><parameter role="keyword">show_numbers</parameter>&nbsp;:</term>
                        <listitem><simpara><literal>True</literal> if the shown items should be numbered.</simpara></listitem>
                </varlistentry>
            </variablelist>

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

            <para>
                The <methodname>set_show_numbers</methodname>() method sets whether a number
                should be added to the items shown by the widgets representing action.
                The numbers are shown to provide a unique character for a mnemonic to be
                used inside the menu item's label. Only the first ten items get a number to avoid clashes.
            </para>
        </refsect2>
    </refsect1>
    
    <refsect1>
        <title>Functions</title>

        <refsect2 id="function-gtk--recent-action-new-for-manager">
            <title>gtk.recent_action_new_for_manager</title>

            <programlisting><methodsynopsis language="python">
                <methodname>recent_action_new_for_manager</methodname>
                <methodparam><parameter>name</parameter></methodparam>
                <methodparam><parameter>label</parameter></methodparam>
                <methodparam><parameter>tooltip</parameter></methodparam>
                <methodparam><parameter>stock_id</parameter></methodparam>
                <methodparam><parameter>manager</parameter></methodparam>
            </methodsynopsis></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, or <literal>None</literal>.</simpara></listitem>
                </varlistentry>
                <varlistentry>
                    <term><parameter role="keyword">tooltip</parameter>&nbsp;:</term>
                        <listitem><simpara>a tooltip for the action, or <literal>None</literal>.</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, or <literal>None</literal>.</simpara></listitem>
                </varlistentry>
                <varlistentry>
                    <term><parameter role="keyword">manager</parameter>&nbsp;:</term>
                        <listitem><simpara>a <link linkend="class-gtkrecentmanager">gtk.RecentManager</link>, or
                        <literal>None</literal> for using the default
                        <link linkend="class-gtkrecentmanager">gtk.RecentManager</link></simpara></listitem>
                </varlistentry>
            </variablelist>

            <note>
                <para>This function is available in PyGTK 2.12 and above.</para>
            </note>

            <para>
                The <methodname>recent_action_new_for_manager</methodname>() function creates a new
                <link linkend="class-gtkrecentaction">gtk.RecentAction</link> object. To add the action to a
                <link linkend="class-gtkactiongroup">gtk.ActionGroup</link> and set the accelerator for the action, call
                <methodname><link linkend="method-gtkactiongroup--add-action-with-accel">gtk.ActionGroup.add_action_with_accel</link></methodname>().
            </para>
        </refsect2>
    </refsect1>
</refentry>
