[pygobject] Update the docs with new 2.20 API
- From: Gian Mario Tagliaretti <gianmt src gnome org>
- To: svn-commits-list gnome org
- Subject: [pygobject] Update the docs with new 2.20 API
- Date: Mon, 25 May 2009 14:21:09 -0400 (EDT)
commit 76e9dc74ac706a9207f9d31f887d6e38df2a678f
Author: Gian Mario Tagliaretti <gianmt gnome org>
Date: Mon May 25 20:20:38 2009 +0200
Update the docs with new 2.20 API
---
docs/reference/pygio-appinfo.xml | 115 ++++++++++++++++++++++++++++
docs/reference/pygio-icon.xml | 99 +++++++++++++++++++++++-
docs/reference/pygio-mount.xml | 156 ++++++++++++++++++++++++++++++++++++++
3 files changed, 367 insertions(+), 3 deletions(-)
diff --git a/docs/reference/pygio-appinfo.xml b/docs/reference/pygio-appinfo.xml
index 1e0ea95..eaeb060 100644
--- a/docs/reference/pygio-appinfo.xml
+++ b/docs/reference/pygio-appinfo.xml
@@ -27,10 +27,18 @@
<methodparam><parameter role="keyword">content_type</parameter></methodparam>
</methodsynopsis>
<methodsynopsis language="python">
+ <methodname><link linkend="method-gioappinfo--can-delete">can_delete</link></methodname>
+ <methodparam></methodparam>
+ </methodsynopsis>
+ <methodsynopsis language="python">
<methodname><link linkend="method-gioappinfo--can-remove-supports-type">can_remove_supports_type</link></methodname>
<methodparam></methodparam>
</methodsynopsis>
<methodsynopsis language="python">
+ <methodname><link linkend="method-gioappinfo--delete">delete</link></methodname>
+ <methodparam></methodparam>
+ </methodsynopsis>
+ <methodsynopsis language="python">
<methodname><link linkend="method-gioappinfo--dup">dup</link></methodname>
<methodparam></methodparam>
</methodsynopsis>
@@ -39,6 +47,10 @@
<methodparam><parameter role="keyword">appinfo2</parameter></methodparam>
</methodsynopsis>
<methodsynopsis language="python">
+ <methodname><link linkend="method-gioappinfo--get-commandline">get_commandline</link></methodname>
+ <methodparam></methodparam>
+ </methodsynopsis>
+ <methodsynopsis language="python">
<methodname><link linkend="method-gioappinfo--get-description">get_description</link></methodname>
<methodparam></methodparam>
</methodsynopsis>
@@ -111,6 +123,9 @@
</methodsynopsis><methodsynopsis language="python">
<methodname><link linkend="function-gio--app-info-get-default-for-uri-scheme">gio.app_info_get_default_for_uri_scheme</link></methodname>
<methodparam><parameter role="keyword">uri_scheme</parameter></methodparam>
+</methodsynopsis><methodsynopsis language="python">
+ <methodname><link linkend="function-gio--app-info-reset-type-association">gio.app_info_reset_type_association</link></methodname>
+ <methodparam><parameter role="keyword">content_type</parameter></methodparam>
</methodsynopsis></programlisting>
</refsect1>
@@ -233,6 +248,30 @@
</para>
</refsect2>
+ <refsect2 id="method-gioappinfo--can-delete">
+ <title>gio.AppInfo.can_delete</title>
+
+ <programlisting><methodsynopsis language="python">
+ <methodname>can_delete</methodname>
+ <methodparam></methodparam>
+ </methodsynopsis></programlisting>
+
+ <variablelist>
+ <varlistentry>
+ <term><emphasis>Returns</emphasis> :</term>
+ <listitem><simpara><literal>True</literal> if appinfo can be deleted.
+ </simpara></listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ The <methodname>can_delete</methodname>() method obtains the information
+ whether the <link linkend="class-gioappinfo"><classname>gio.AppInfo</classname></link>
+ can be deleted. See
+ <methodname><link linkend="method-gioappinfo--delete">gio.AppInfo.delete</link></methodname>().
+ </para>
+ </refsect2>
+
<refsect2 id="method-gioappinfo--can-remove-supports-type">
<title>gio.AppInfo.can_remove_supports_type</title>
@@ -256,6 +295,34 @@
</para>
</refsect2>
+ <refsect2 id="method-gioappinfo--delete">
+ <title>gio.AppInfo.delete</title>
+
+ <programlisting><methodsynopsis language="python">
+ <methodname>delete</methodname>
+ <methodparam></methodparam>
+ </methodsynopsis></programlisting>
+
+ <variablelist>
+ <varlistentry>
+ <term><emphasis>Returns</emphasis> :</term>
+ <listitem><simpara><literal>True</literal> if appinfo has been deleted.
+ </simpara></listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ The <methodname>delete</methodname>() method tries to delete an
+ <link linkend="class-gioappinfo"><classname>gio.AppInfo</classname></link>.
+ </para>
+ <para>
+ On some platforms, there may be a difference between user-defined
+ <link linkend="class-gioappinfo"><classname>gio.AppInfo</classname></link>s
+ which can be deleted, and system-wide ones which cannot. See
+ <methodname><link linkend="method-gioappinfo--can-delete">gio.AppInfo.can_delete</link></methodname>().
+ </para>
+ </refsect2>
+
<refsect2 id="method-gioappinfo--dup">
<title>gio.AppInfo.dup</title>
@@ -305,6 +372,29 @@
</para>
</refsect2>
+ <refsect2 id="method-gioappinfo--get-commandline">
+ <title>gio.AppInfo.get_commandline</title>
+
+ <programlisting><methodsynopsis language="python">
+ <methodname>get_commandline</methodname>
+ <methodparam></methodparam>
+ </methodsynopsis></programlisting>
+
+ <variablelist>
+ <varlistentry>
+ <term><emphasis>Returns</emphasis> :</term>
+ <listitem><simpara>a string containing the appinfo's commandline, or
+ <literal>None</literal> if this information is not available.
+ </simpara></listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ The <methodname>get_commandline</methodname>() method gets the
+ commandline with which the application will be started.
+ </para>
+ </refsect2>
+
<refsect2 id="method-gioappinfo--get-description">
<title>gio.AppInfo.get_description</title>
@@ -775,5 +865,30 @@
':', e.g. "http", "ftp" or "sip".
</para>
</refsect2>
+
+ <refsect2 id="function-gio--app-info-reset-type-association">
+ <title>gio.app_info_reset_type_association</title>
+
+ <programlisting><methodsynopsis language="python">
+ <methodname>app_info_reset_type_association</methodname>
+ <methodparam><parameter role="keyword">content_type</parameter></methodparam>
+ </methodsynopsis></programlisting>
+
+ <variablelist>
+ <varlistentry>
+ <term><parameter>content_type</parameter> :</term>
+ <listitem><simpara>a content type</simpara></listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ The <methodname>app_info_reset_type_association</methodname>() function
+ removes all changes to the type associations done by
+ <methodname><link linkend="method-gioappinfo--set-as-default-for-type">set_as_default_for_type</link></methodname>(),
+ <methodname><link linkend="method-gioappinfo--set-as-default-for-extension">set_as_default_for_extension</link></methodname>(),
+ <methodname><link linkend="method-gioappinfo--add-supports-type">add_supports_type</link></methodname>() or
+ <methodname><link linkend="method-gioappinfo--remove-supports-type">remove_supports_type</link></methodname>().
+ </para>
+ </refsect2>
</refsect1>
</refentry>
diff --git a/docs/reference/pygio-icon.xml b/docs/reference/pygio-icon.xml
index 2e3c285..5a32d28 100644
--- a/docs/reference/pygio-icon.xml
+++ b/docs/reference/pygio-icon.xml
@@ -19,9 +19,21 @@
<methodname><link linkend="method-gioicon--equal">equal</link></methodname>
<methodparam><parameter role="keyword">icon2</parameter></methodparam>
</methodsynopsis>
+ <methodsynopsis language="python">
+ <methodname><link linkend="method-gioicon--to-string">to_string</link></methodname>
+ <methodparam></methodparam>
+ </methodsynopsis>
</classsynopsis>
+<programlisting>
+<emphasis role="bold">Functions</emphasis>
+
+<methodsynopsis language="python">
+ <methodname><link linkend="function-gio--icon-new-from-string">gio.icon_new_from_string</link></methodname>
+ <methodparam></methodparam>
+</methodsynopsis></programlisting>
+
</refsect1>
<refsect1>
@@ -80,7 +92,6 @@
To check if two GIcons are equal, see
<methodname><link linkend="method-gioicon--equal">gio.Icon.equal</link></methodname>().
</para>
- <!--
<para>
For serializing a <link linkend="class-gioicon"><classname>gio.Icon</classname></link>,
use <methodname><link linkend="method-gioicon- -to-string">gio.Icon.to_string</link></methodname>() and
@@ -91,9 +102,8 @@
<link linkend="class-gioicon"><classname>gio.Icon</classname></link>
implementations you need to ensure that each GType is registered
with the type system prior to calling
- <methodname><link linkend="method-gioicon- -new-from-string">gio.Icon.new_from_string</link></methodname>().
+ <methodname><link linkend="function-gioicon--new-from-string">gio.icon_new_from_string</link></methodname>().
</para>
- -->
</refsect1>
<refsect1>
@@ -120,5 +130,88 @@
The <methodname>equal</methodname>() method checks if two icons are equal.
</para>
</refsect2>
+
+ <refsect2 id="method-gioicon--to-string">
+ <title>gio.Icon.to_string</title>
+
+ <programlisting><methodsynopsis language="python">
+ <methodname>to_string</methodname>
+ <methodparam></methodparam>
+ </methodsynopsis></programlisting>
+
+ <variablelist>
+ <varlistentry>
+ <term><emphasis>Returns</emphasis> :</term>
+ <listitem><simpara>An UTF8 string or <literal>None</literal>
+ if icon can't be serialized.
+ </simpara></listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ The <methodname>to_string</methodname>() method generates a textual
+ representation of icon that can be used for serialization such as when
+ passing icon to a different process or saving it to persistent storage. Use
+ <methodname><link linkend="function-gio--icon-new-from-string">gio.icon_new_from_string</link></methodname>()
+ to get icon back from the returned string.
+ </para>
+ <para>
+ The encoding of the returned string is proprietary to GIcon except in the following two cases
+ </para>
+ <para>
+ If icon is a <link linkend="class-giofileicon"><classname>gio.FileIcon</classname></link>,
+ the returned string is a native path (such as /path/to/my icon.png) without escaping
+ if the <link linkend="class-giofile"><classname>gio.File</classname></link>
+ for icon is a native file. If the file is not native, the returned string is the result of
+ <methodname><link linkend="method-giofile--get-uri">gio.File.get_uri</link></methodname>()
+ (such as sftp://path/to/my%20icon.png).
+ </para>
+ <para>
+ If icon is a <link linkend="class-giothemedicon"><classname>gio.ThemedIcon</classname></link>
+ with exactly one name, the encoding is simply the name (such as network-server).
+ </para>
+ </refsect2>
+ </refsect1>
+
+ <refsect1>
+ <title>Functions</title>
+
+ <refsect2 id="function-gio--icon-new-from-string">
+ <title>gio.icon_new_from_string</title>
+
+ <programlisting><methodsynopsis language="python">
+ <methodname>icon_new_from_string</methodname>
+ <methodparam><parameter role="keyword">str</parameter></methodparam>
+ </methodsynopsis></programlisting>
+
+ <variablelist>
+ <varlistentry>
+ <term><parameter>str</parameter> :</term>
+ <listitem><simpara>A string obtained via
+ <methodname><link linkend="method-gioicon--to-string">gio.Icon.to_string</link></methodname>().
+ </simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><emphasis>Returns</emphasis> :</term>
+ <listitem><simpara>An object implementing the
+ <link linkend="class-gioicon"><classname>gio.Icon</classname></link>
+ interface or <literal>None</literal> if error is set.
+ </simpara></listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ The <methodname>icon_new_from_string</methodname>() function generate a
+ <link linkend="class-gioicon"><classname>gio.Icon</classname></link>
+ instance from str. This function can fail if str is not valid - see
+ <methodname><link linkend="method-gioicon--to-string">gio.Icon.to_string</link></methodname>()
+ for discussion.
+ </para>
+ <para>
+ If your application or library provides one or more GIcon implementations you need
+ to ensure that each GType is registered with the type system prior to calling
+ <methodname><link linkend="function-gio--icon-new-from-string">gio.icon_new_from_string</link></methodname>().
+ </para>
+ </refsect2>
</refsect1>
</refentry>
diff --git a/docs/reference/pygio-mount.xml b/docs/reference/pygio-mount.xml
index f5688c5..f4b1c99 100644
--- a/docs/reference/pygio-mount.xml
+++ b/docs/reference/pygio-mount.xml
@@ -74,6 +74,10 @@
<methodparam><parameter role="keyword">cancellable</parameter><initializer><literal>None</literal></initializer></methodparam>
</methodsynopsis>
<methodsynopsis language="python">
+ <methodname><link linkend="method-giomount--is-shadowed">is_shadowed</link></methodname>
+ <methodparam></methodparam>
+ </methodsynopsis>
+ <methodsynopsis language="python">
<methodname><link linkend="method-giomount--remount">remount</link></methodname>
<methodparam><parameter role="keyword">callback</parameter></methodparam>
<methodparam><parameter role="keyword">flags</parameter><initializer><literal>gio.MOUNT_UNMOUNT_NONE</literal></initializer></methodparam>
@@ -86,6 +90,10 @@
<methodparam><parameter role="keyword">result</parameter></methodparam>
</methodsynopsis>
<methodsynopsis language="python">
+ <methodname><link linkend="method-giomount--shadow">shadow</link></methodname>
+ <methodparam></methodparam>
+ </methodsynopsis>
+ <methodsynopsis language="python">
<methodname><link linkend="method-giomount--unmount">unmount</link></methodname>
<methodparam><parameter role="keyword">callback</parameter></methodparam>
<methodparam><parameter role="keyword">flags</parameter><initializer><literal>gio.MOUNT_UNMOUNT_NONE</literal></initializer></methodparam>
@@ -96,6 +104,10 @@
<methodname><link linkend="method-giomount--unmount-finish">unmount_finish</link></methodname>
<methodparam><parameter role="keyword">result</parameter></methodparam>
</methodsynopsis>
+ <methodsynopsis language="python">
+ <methodname><link linkend="method-giomount--unshadow">unshadow</link></methodname>
+ <methodparam></methodparam>
+ </methodsynopsis>
</classsynopsis>
@@ -125,6 +137,16 @@
<variablelist>
<varlistentry>
+ <term><link linkend="signal-giomount--aborted">"aborted"</link></term>
+ <listitem>
+ <methodsynopsis language="python"><methodname>callback</methodname>
+ <methodparam><parameter>mount</parameter></methodparam>
+ <methodparam><parameter>user_param1</parameter></methodparam>
+ <methodparam><parameter>...</parameter></methodparam>
+ </methodsynopsis>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
<term><link linkend="signal-giomount--changed">"changed"</link></term>
<listitem>
<methodsynopsis language="python"><methodname>callback</methodname>
@@ -565,6 +587,58 @@
for the asynchronous version.
</para>
</refsect2>
+
+ <refsect2 id="method-giomount--is-shadowed">
+ <title>gio.Mount.is_shadowed</title>
+
+ <programlisting><methodsynopsis language="python">
+ <methodname>is_shadowed</methodname>
+ <methodparam></methodparam>
+ </methodsynopsis></programlisting>
+
+ <variablelist>
+ <varlistentry>
+ <term><emphasis>Returns</emphasis> :</term>
+ <listitem><simpara><literal>True</literal> if mount is shadowed.
+ </simpara></listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ The <methodname>is_shadowed</methodname>() method determines if mount
+ is shadowed. Applications or libraries should avoid displaying mount
+ in the user interface if it is shadowed.
+ </para>
+ <para>
+ A mount is said to be shadowed if there exists one or more user visible
+ objects (currently
+ <link linkend="class-giomount"><classname>gio.Mount</classname></link>
+ objects) with a root that is inside the root of mount.
+ </para>
+ <para>
+ One application of shadow mounts is when exposing a single file system
+ that is used to address several logical volumes. In this situation, a
+ <link linkend="class-giovolumemonitor"><classname>gio.VolumeMonitor</classname></link>
+ implementation would create two
+ <link linkend="class-giovolume"><classname>gio.Volume</classname></link>
+ objects (for example, one for the camera functionality of the device
+ and one for a SD card reader on the device) with activation URIs
+ gphoto2://[usb:001,002]/store1/ and gphoto2://[usb:001,002]/store2/.
+ When the underlying mount (with root gphoto2://[usb:001,002]/) is
+ mounted, said
+ <link linkend="class-giovolumemonitor"><classname>gio.VolumeMonitor</classname></link>
+ implementation would create two
+ <link linkend="class-giomount"><classname>gio.Mount</classname></link>
+ objects (each with their root matching the corresponding volume
+ activation root) that would shadow the original mount.
+ </para>
+ <para>
+ The proxy monitor in GVfs 2.26 and later, automatically creates and
+ manage shadow mounts (and shadows the underlying mount) if the activation
+ root on a <link linkend="class-giovolume"><classname>gio.Volume</classname></link>
+ is set.
+ </para>
+ </refsect2>
<refsect2 id="method-giomount--remount">
<title>gio.Mount.remount</title>
@@ -651,6 +725,29 @@
The <methodname>remount_finish</methodname>() method finishes remounting a mount.
</para>
</refsect2>
+
+ <refsect2 id="method-giomount--shadow">
+ <title>gio.Mount.shadow</title>
+
+ <programlisting><methodsynopsis language="python">
+ <methodname>shadow</methodname>
+ <methodparam></methodparam>
+ </methodsynopsis></programlisting>
+
+ <variablelist>
+ </variablelist>
+
+ <para>
+ The <methodname>shadow</methodname>() method increments the shadow
+ count on mount. Usually used by
+ <link linkend="class-giovolumemonitor"><classname>gio.VolumeMonitor</classname></link>
+ implementations when creating a shadow mount for mount, see
+ <methodname><link linkend="method-giomount--is-shadowed">gio.Mount.is_shadowed</link></methodname>()
+ for more information. The caller will need to emit the "changed"
+ signal on mount manually.
+ </para>
+
+ </refsect2>
<refsect2 id="method-giomount--unmount">
<title>gio.Mount.unmount</title>
@@ -730,11 +827,70 @@
The <methodname>unmount_finish</methodname>() method finishes unmounting a mount.
</para>
</refsect2>
+
+ <refsect2 id="method-giomount--unshadow">
+ <title>gio.Mount.unshadow</title>
+
+ <programlisting><methodsynopsis language="python">
+ <methodname>unshadow</methodname>
+ <methodparam></methodparam>
+ </methodsynopsis></programlisting>
+
+ <variablelist>
+ </variablelist>
+
+ <para>
+ The <methodname>unshadow</methodname>() method decrements the shadow
+ count on mount. Usually used by
+ <link linkend="class-giovolumemonitor"><classname>gio.VolumeMonitor</classname></link>
+ implementations when destroying a shadow mount for mount, see
+ <methodname><link linkend="method-giomount--is-shadowed">gio.Mount.is_shadowed</link></methodname>()
+ for more information. The caller will need to emit the "changed"
+ signal on mount manually.
+ </para>
+
+ </refsect2>
</refsect1>
<refsect1>
<title>Signals</title>
+ <refsect2 id="signal-giomount--aborted">
+ <title>The "aborted" gio.Mount Signal</title>
+
+ <programlisting><methodsynopsis language="python"><methodname>callback</methodname>
+ <methodparam><parameter>mount</parameter></methodparam>
+ <methodparam><parameter>user_param1</parameter></methodparam>
+ <methodparam><parameter>...</parameter></methodparam>
+ </methodsynopsis></programlisting>
+
+ <variablelist>
+ <varlistentry>
+ <term><parameter>mount</parameter> :</term>
+ <listitem><simpara>the mount</simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>user_param1</parameter> :</term>
+ <listitem><simpara>the first user parameter (if any) specified
+ with the <link
+ linkend="method-gobject--connect"><methodname>connect</methodname>()</link>
+ method</simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>...</parameter> :</term>
+ <listitem><simpara>additional user parameters (if any)</simpara></listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ Emitted by the backend when e.g. a device becomes unavailable while a
+ mount operation is in progress.
+ </para>
+ <para>
+ Implementations of <link linkend="class-giomountoperation"><classname>gio.MountOperation</classname></link>
+ should handle this signal by dismissing open password dialogs.
+ </para>
+ </refsect2>
<refsect2 id="signal-giomount--changed">
<title>The "changed" gio.Mount Signal</title>
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
