Skip to content

Commit

Permalink
Update docs for gobject functions.
Browse files Browse the repository at this point in the history 
	* docs/reference/pygobject-functions.xml: Update docs for
	gobject functions.
  • Loading branch information
John Finlay committed Aug 17, 2006
1 parent a181cb3 commit 18bab9e
Show file tree
Hide file tree
Showing 2 changed files with 296 additions and 1 deletion.
5 changes: 5 additions & 0 deletions ChangeLog
View file
@@ -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:
Expand Down
292 changes: 291 additions & 1 deletion docs/reference/pygobject-functions.xml
View file
Expand Up @@ -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>
Expand Down Expand Up @@ -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>
Expand All @@ -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>

0 comments on commit 18bab9e

Please sign in to comment.