Merge from 2.16 branch:

2008-12-24  Paul Pogonyshev  <pogonyshev@gmx.net>

	Bug 547119 – gobject.timeout_add_seconds() not found in docs

	* docs/reference/pyglib-functions.xml (glib.timeout_add_seconds):
	Describe.

svn path=/trunk/; revision=983

1 files changed, 64 insertions, 0 deletions

diff --git a/docs/reference/pyglib-functions.xml b/docs/reference/pyglib-functions.xml
index 3464a80f..59a590dc 100644
--- a/docs/reference/pyglib-functions.xml
+++ b/docs/reference/pyglib-functions.xml
@@ -25,6 +25,12 @@ linkend="function-glib--timeout-add">glib.timeout_add</link></methodname>
 	<methodparam><parameter>...</parameter></methodparam>
   </methodsynopsis><methodsynopsis language="python">
 	<methodname><link
+linkend="function-glib--timeout-add-seconds">glib.timeout_add_seconds</link></methodname>
+	<methodparam><parameter>interval</parameter></methodparam>
+	<methodparam><parameter>callback</parameter></methodparam>
+	<methodparam><parameter>...</parameter></methodparam>
+  </methodsynopsis><methodsynopsis language="python">
+	<methodname><link
 linkend="function-glib--io-add-watch">glib.io_add_watch</link></methodname>
 	<methodparam><parameter>fd</parameter></methodparam>
 	<methodparam><parameter>condition</parameter></methodparam>
@@ -186,6 +192,64 @@ in delays).</para>
 
     </refsect2>
 
+    <refsect2 id="function-glib--timeout-add-seconds">
+      <title>glib.timeout_add_seconds</title>
+
+      <programlisting><methodsynopsis language="python">
+	  <methodname>glib.timeout_add_seconds</methodname>
+	  <methodparam><parameter>interval</parameter></methodparam>
+	  <methodparam><parameter>callback</parameter></methodparam>
+	  <methodparam><parameter>...</parameter></methodparam>
+	</methodsynopsis></programlisting>
+      <variablelist>
+	<varlistentry>
+	  <term><parameter>interval</parameter>&nbsp;:</term>
+	  <listitem><simpara>the time between calls to the function, in
+seconds </simpara></listitem>
+	</varlistentry>
+	<varlistentry>
+	  <term><parameter>callback</parameter>&nbsp;:</term>
+	  <listitem><simpara>the function to call</simpara></listitem>
+	</varlistentry>
+	<varlistentry>
+	  <term><parameter>...</parameter>&nbsp;:</term>
+	  <listitem><simpara>zero or more arguments that will be passed to
+<parameter>callback</parameter></simpara></listitem>
+	</varlistentry>
+	<varlistentry>
+	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
+	  <listitem><simpara>an integer ID of the event
+source</simpara></listitem>
+	</varlistentry>
+      </variablelist>
+
+      <para>The <function>glib.timeout_add_seconds</function>() is similar to
+	<function>glib.timeout_add</function>() except
+	that <parameter>interval</parameter> must be specified in seconds, not
+	milliseconds, and the function should cause less CPU wakeups, which is important
+	for laptops' batteries.</para>
+
+      <para>Unlike <function>glib.timeout_add</function>(), this function operates at
+	whole second granularity.  The initial starting point of the timer is determined
+	by the implementation and the implementation is expected to group multiple timers
+	together so that they fire all at the same time.  To allow this grouping, the
+	interval to the first timer is rounded and can deviate up to one second from the
+	specified interval.  Subsequent timer iterations will generally run at the
+	specified interval.</para>
+
+      <para>Note that timeout functions may be delayed, due to the processing of other
+	event sources.  Thus they should not be relied on for precise timing.  After each
+	call to the timeout function, the time of the next timeout is recalculated based
+	on the current time and the given interval.</para>
+
+      <para>The grouping of timers to fire at the same time results in a more power and
+	CPU efficient behavior so if your timer is in multiples of seconds and you don't
+	require the first timer exactly one second from now, the use of
+	<function>glib.timeout_add_seconds</function>() is preferred
+	over <function>glib.timeout_add</function>().</para>
+
+    </refsect2>
+
     <refsect2 id="function-glib--io-add-watch">
       <title>glib.io_add_watch</title>