Add docs for gtk.RecentAction.

svn path=/trunk/; revision=2988

4 files changed, 251 insertions, 0 deletions

diff --git a/docs/Makefile.am b/docs/Makefile.am
index 4b332adb..2fe40ec7 100644
--- a/docs/Makefile.am
+++ b/docs/Makefile.am
@@ -184,6 +184,7 @@ XMLFILES = 						\
 	reference/pygtk-gtkradiotoolbutton.xml		\
 	reference/pygtk-gtkrange.xml			\
 	reference/pygtk-gtkrcstyle.xml			\
+	reference/pygtk-gtkrecentaction.xml		\
 	reference/pygtk-gtkrecentchooserdialog.xml	\
 	reference/pygtk-gtkrecentchoosermenu.xml	\
 	reference/pygtk-gtkrecentchooserwidget.xml	\
@@ -460,6 +461,7 @@ HTML_FILES =						\
 	html/class-gtkradiotoolbutton.html		\
 	html/class-gtkrange.html			\
 	html/class-gtkrcstyle.html			\
+	html/class-gtkrecentaction.html			\
 	html/class-gtkrecentchooserdialog.html		\
 	html/class-gtkrecentchooser.html		\
 	html/class-gtkrecentchoosermenu.html		\
diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog
index 6c770d62..1a06f493 100644
--- a/docs/reference/ChangeLog
+++ b/docs/reference/ChangeLog
@@ -1,5 +1,11 @@
 2008-06-06  Gian Mario Tagliaretti  <gianmt@gnome.org>
 
+	* Makefile.am:
+	* pygtk-gtk-classes.xml:
+	* pygtk-gtkrecentaction.xml: Add docs for gtk.RecentAction.
+
+2008-06-06  Gian Mario Tagliaretti  <gianmt@gnome.org>
+
 	* pygtk-gdkwindow.xml: Add docs for get_type_hint, fixes #536906.
 
 2008-05-02  Gian Mario Tagliaretti  <gianmt@gnome.org>
diff --git a/docs/reference/pygtk-gtk-classes.xml b/docs/reference/pygtk-gtk-classes.xml
index ead51a5d..b80e666e 100644
--- a/docs/reference/pygtk-gtk-classes.xml
+++ b/docs/reference/pygtk-gtk-classes.xml
@@ -121,6 +121,7 @@
   <xi:include href="pygtk-gtkradiotoolbutton.xml"/>
   <xi:include href="pygtk-gtkrange.xml"/>
   <xi:include href="pygtk-gtkrcstyle.xml"/>
+  <xi:include href="pygtk-gtkrecentaction.xml"/>
   <xi:include href="pygtk-gtkrecentchooserdialog.xml"/>
   <xi:include href="pygtk-gtkrecentchoosermenu.xml"/>
   <xi:include href="pygtk-gtkrecentchooserwidget.xml"/>
diff --git a/docs/reference/pygtk-gtkrecentaction.xml b/docs/reference/pygtk-gtkrecentaction.xml
new file mode 100644
index 00000000..ddbe142c
--- /dev/null
+++ b/docs/reference/pygtk-gtkrecentaction.xml
@@ -0,0 +1,242 @@
+<?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>
+        <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>