Update docs for gobject functions.

	* docs/reference/pygobject-functions.xml: Update docs for
	gobject functions.

2 files changed, 296 insertions, 1 deletions

diff --git a/ChangeLog b/ChangeLog
index 65e8fe8..ce85e85 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,8 @@
+2006-08-16  John Finlay  <finlay@moeraki.com>
+
+	* docs/reference/pygobject-functions.xml: Update docs for
+	gobject functions.
+
 2006-08-15  Murray Cumming  <murrayc@murrayc.com>
 
 	* gobject/pygobject-private.h:
diff --git a/docs/reference/pygobject-functions.xml b/docs/reference/pygobject-functions.xml
index 6a18676..c0c6234 100644
--- a/docs/reference/pygobject-functions.xml
+++ b/docs/reference/pygobject-functions.xml
@@ -138,6 +138,41 @@ linkend="function-gobject--get-current-time">gobject.get_current_time</link></me
       </methodsynopsis><methodsynopsis language="python">
 	<methodname><link
 linkend="function-gobject--main-depth">gobject.main_depth</link></methodname>
+      </methodsynopsis><methodsynopsis language="python">
+	<methodname><link
+linkend="function-gobject--threads-init">gobject.threads_init</link></methodname>
+      </methodsynopsis><methodsynopsis language="python">
+	<methodname><link
+linkend="function-gobject--signal-accumulator-true-handled">gobject.signal_accumulator_true_handled</link></methodname>
+      </methodsynopsis><methodsynopsis language="python">
+	<methodname><link
+linkend="function-gobject--add-emission-hook">gobject.add_emission_hook</link></methodname>
+ 	<methodparam><parameter>type</parameter></methodparam>
+ 	<methodparam><parameter>name</parameter></methodparam>
+ 	<methodparam><parameter>callback</parameter></methodparam>
+ 	<methodparam><parameter>...</parameter></methodparam>
+      </methodsynopsis><methodsynopsis language="python">
+	<methodname><link
+linkend="function-gobject--remove-emission-hook">gobject.remove_emission_hook</link></methodname>
+ 	<methodparam><parameter>type</parameter></methodparam>
+ 	<methodparam><parameter>name</parameter></methodparam>
+ 	<methodparam><parameter>hook_id</parameter></methodparam>
+      </methodsynopsis><methodsynopsis language="python">
+	<methodname><link
+linkend="function-gobject---install-metaclass">gobject._install_metaclass</link></methodname>
+ 	<methodparam><parameter>metaclass</parameter></methodparam>
+      </methodsynopsis><methodsynopsis language="python">
+	<methodname><link
+linkend="function-gobject--filename-display-name">gobject.filename_display_name</link></methodname>
+ 	<methodparam><parameter>filename</parameter></methodparam>
+      </methodsynopsis><methodsynopsis language="python">
+	<methodname><link
+linkend="function-gobject--filename-display-basename">gobject.filename_display_basename</link></methodname>
+ 	<methodparam><parameter>filename</parameter></methodparam>
+      </methodsynopsis><methodsynopsis language="python">
+	<methodname><link
+linkend="function-gobject--filename-from-utf8">gobject.filename_from_utf8</link></methodname>
+ 	<methodparam><parameter>utf8string</parameter></methodparam>
       </methodsynopsis></programlisting>
 
   </refsect1>
@@ -1347,7 +1382,7 @@ from the epoch.</para>
       <variablelist role="params">
         <varlistentry>
           <term><emphasis>Returns</emphasis>&nbsp;:</term>
-          <listitem><simpara>he depth of the stack of calls to the main
+          <listitem><simpara>the depth of the stack of calls to the main
 context.</simpara></listitem>
         </varlistentry>
       </variablelist>
@@ -1368,6 +1403,261 @@ method), it returns 2. And so forth.</para>
 
     </refsect2>
 
+    <refsect2 id="function-gobject--threads-init">
+      <title>gobject.threads_init</title>
+      
+      <programlisting><methodsynopsis language="python">
+        <methodname>gobject.threads_init</methodname>
+        <methodparam><parameter></parameter></methodparam>
+	</methodsynopsis></programlisting>
+      <variablelist role="params">
+        <varlistentry>
+          <term><emphasis>Returns</emphasis>&nbsp;:</term>
+          <listitem><simpara></simpara></listitem>
+        </varlistentry>
+      </variablelist>
+      <note>
+        <para>This function is available in PyGTK 2.4 and above.</para>
+      </note>
+
+      <para>The <function>threads_init</function>() function initializes the
+      the use of Python threading in the gobject module. This function is
+      different than the <link
+      linkend="function-gdk--threads-init"><function>gtk.gdk.threads_init</function>()</link>
+      function as that function also initializes the gdk threads.</para>
+
+    </refsect2>
+
+    <refsect2 id="function-gobject--signal-accumulator-true-handled">
+      <title>gobject.signal_accumulator_true_handled</title>
+      
+      <programlisting><methodsynopsis language="python">
+        <methodname>gobject.signal_accumulator_true_handled</methodname>
+	</methodsynopsis></programlisting>
+
+      <note>
+        <para>This function is available in PyGTK 2.8 and above.</para>
+      </note>
+
+      <para>The <function>signal_accumulator_true_handled</function>()
+      function is only used as accumulator argument when registering
+      signals.</para>
+
+    </refsect2>
+
+    <refsect2 id="function-gobject--add-emission-hook">
+      <title>gobject.add_emission_hook</title>
+      
+      <programlisting><methodsynopsis language="python">
+        <methodname>gobject.add_emission_hook</methodname>
+ 	<methodparam><parameter>type</parameter></methodparam>
+ 	<methodparam><parameter>name</parameter></methodparam>
+ 	<methodparam><parameter>callback</parameter></methodparam>
+ 	<methodparam><parameter>...</parameter></methodparam>
+	</methodsynopsis></programlisting>
+      <variablelist role="params">
+        <varlistentry>
+          <term><emphasis>type</emphasis>&nbsp;:</term>
+          <listitem><simpara>a Python GObject instance or
+          type</simpara></listitem>
+        </varlistentry>
+        <varlistentry>
+          <term><emphasis>name</emphasis>&nbsp;:</term>
+          <listitem><simpara>a signal name</simpara></listitem>
+        </varlistentry>
+        <varlistentry>
+          <term><emphasis>callback</emphasis>&nbsp;:</term>
+          <listitem><simpara>a function</simpara></listitem>
+        </varlistentry>
+        <varlistentry>
+          <term><emphasis>...</emphasis>&nbsp;:</term>
+          <listitem><simpara>zero or more extra arguments that will be
+          passed to callback.</simpara></listitem>
+        </varlistentry>
+        <varlistentry>
+          <term><emphasis>Returns</emphasis>&nbsp;:</term>
+          <listitem><simpara>the hook id, for later use with <link
+          linkend="function-gobject--signal-remove-emission-hook"><function>gobject.signal_remove_emission_hook</function>()</link>.</simpara></listitem>
+        </varlistentry>
+      </variablelist>
+      <note>
+        <para>This function is available in PyGTK 2.8 and above.</para>
+      </note>
+
+      <para>The <function>add_emission_hook</function>() function adds an
+      emission hook for the signal specified by <parameter>name</parameter>,
+      which will get called for any emission of that signal, independent of
+      the instance. This is possible only for signals which don't have the
+      <literal>gobject.SIGNAL_NO_HOOKS</literal> flag set.</para>
+
+    </refsect2>
+
+    <refsect2 id="function-gobject--remove-emission-hook">
+      <title>gobject.remove_emission_hook</title>
+      
+      <programlisting><methodsynopsis language="python">
+        <methodname>gobject.remove_emission_hook</methodname>
+ 	<methodparam><parameter>type</parameter></methodparam>
+ 	<methodparam><parameter>name</parameter></methodparam>
+ 	<methodparam><parameter>hook_id</parameter></methodparam>
+	</methodsynopsis></programlisting>
+      <variablelist role="params">
+        <varlistentry>
+          <term><emphasis>type</emphasis>&nbsp;:</term>
+          <listitem><simpara>a Python GObject instance or
+          type</simpara></listitem>
+        </varlistentry>
+        <varlistentry>
+          <term><emphasis>name</emphasis>&nbsp;:</term>
+          <listitem><simpara>a signal name</simpara></listitem>
+        </varlistentry>
+        <varlistentry>
+          <term><emphasis>hook_id</emphasis>&nbsp;:</term>
+          <listitem><simpara>the id of the emission hook as returned by the
+          <link
+          linkend="function-gobject--add-emission-hook"><function>gobject.add_emission_hook</function>()</link>)
+          function.</simpara></listitem>
+        </varlistentry>
+        <varlistentry>
+          <term><emphasis>Returns</emphasis>&nbsp;:</term>
+          <listitem><simpara></simpara></listitem>
+        </varlistentry>
+      </variablelist>
+      <note>
+        <para>This function is available in PyGTK 2.8 and above.</para>
+      </note>
+
+      <para>The <function>remove_emission_hook</function>() function deletes
+      an emission hook.</para>
+
+    </refsect2>
+
+    <refsect2 id="function-gobject---install-metaclass">
+      <title>gobject._install_metaclass</title>
+      
+      <programlisting><methodsynopsis language="python">
+        <methodname>gobject._install_metaclass</methodname>
+ 	<methodparam><parameter>metaclass</parameter></methodparam>
+	</methodsynopsis></programlisting>
+      <variablelist role="params">
+        <varlistentry>
+          <term><emphasis>metaclass</emphasis>&nbsp;:</term>
+          <listitem><simpara></simpara></listitem>
+        </varlistentry>
+      </variablelist>
+      <note>
+        <para>This function is available in PyGTK 2.10 and above.</para>
+      </note>
+
+      <para>The <function>_install_metaclass</function>() function installs
+      the metaclass specified by <parameter>metaclass</parameter>.</para>
+
+    </refsect2>
+
+    <refsect2 id="function-gobject--filename-display-name">
+      <title>gobject.filename_display_name</title>
+      
+      <programlisting><methodsynopsis language="python">
+        <methodname>gobject.filename_display_name</methodname>
+        <methodparam><parameter>filename</parameter></methodparam>
+	</methodsynopsis></programlisting>
+      <variablelist role="params">
+        <varlistentry>
+          <term><emphasis>filename</emphasis>&nbsp;:</term>
+          <listitem><simpara>a pathname in the file name
+          encoding</simpara></listitem>
+        </varlistentry>
+        <varlistentry>
+          <term><emphasis>Returns</emphasis>&nbsp;:</term>
+          <listitem><simpara>an UTF8 rendition of
+          <parameter>filename</parameter>.</simpara></listitem>
+        </varlistentry>
+      </variablelist>
+      <note>
+        <para>This function is available in PyGTK 2.10 and above.</para>
+      </note>
+
+      <para>The <function>filename_display_name</function>() function
+      converts a filename into a valid UTF-8 string. The conversion is not
+      necessarily reversible, so you should keep the original around and use
+      the return value of this function only for display purposes. Unlike
+      g_filename_to_utf8(), the result is guaranteed to be non-None even if
+      the filename actually isn't in the file name encoding.</para>
+
+      <para>If you know the whole pathname of the file you should use the
+      <link
+      linkend="function-gobject--filename-display-basename"><function>gobject.filename_display_basename</function>()</link>
+      function, since that allows location-based translation of
+      filenames.</para>
+
+    </refsect2>
+
+    <refsect2 id="function-gobject--filename-display-basename">
+      <title>gobject.filename_display_basename</title>
+      
+      <programlisting><methodsynopsis language="python">
+        <methodname>gobject.filename_display_basename</methodname>
+        <methodparam><parameter>filename</parameter></methodparam>
+	</methodsynopsis></programlisting>
+      <variablelist role="params">
+        <varlistentry>
+          <term><emphasis>filename</emphasis>&nbsp;:</term>
+          <listitem><simpara>an absolute pathname in the file name
+          encoding</simpara></listitem>
+        </varlistentry>
+        <varlistentry>
+          <term><emphasis>Returns</emphasis>&nbsp;:</term>
+          <listitem><simpara>an UTF8 rendition of
+          <parameter>filename</parameter>.</simpara></listitem>
+        </varlistentry>
+      </variablelist>
+      <note>
+        <para>This function is available in PyGTK 2.10 and above.</para>
+      </note>
+
+      <para>The <function>filename_display_basename</function>() function
+      returns the display basename for the particular filename, guaranteed
+      to be valid UTF-8. The display name might not be identical to the
+      filename, for instance there might be problems converting it to UTF-8,
+      and some files can be translated in the display.</para>
+
+      <para>You must pass the whole absolute pathname to this functions so
+      that translation of well known locations can be done.</para>
+
+      <para>This function is preferred over the <link
+      linkend="function-gobject--filename-display-name"><function>gobject.filename_display_name</function>()</link>
+      function if you know the whole path, as it allows translation.</para>
+
+    </refsect2>
+
+    <refsect2 id="function-gobject--filename-from-utf8">
+      <title>gobject.filename_from_utf8</title>
+      
+      <programlisting><methodsynopsis language="python">
+        <methodname>gobject.filename_from_utf8</methodname>
+ 	<methodparam><parameter>utf8string</parameter></methodparam>
+	</methodsynopsis></programlisting>
+      <variablelist role="params">
+        <varlistentry>
+          <term><emphasis>utf8string</emphasis>&nbsp;:</term>
+          <listitem><simpara>a UTF-8 encoded string.</simpara></listitem>
+        </varlistentry>
+        <varlistentry>
+          <term><emphasis>Returns</emphasis>&nbsp;:</term>
+          <listitem><simpara>a filename encoded in the GLib filename
+          encoding.</simpara></listitem>
+        </varlistentry>
+      </variablelist>
+      <note>
+        <para>This function is available in PyGTK 2.10 and above.</para>
+      </note>
+
+      <para>The <function>filename_from_utf8</function>() function converts
+      a string from UTF-8 to the encoding GLib uses for filenames. Note that
+      on Windows GLib uses UTF-8 for filenames.</para>
+
+    </refsect2>
+
   </refsect1>
 
 </refentry>