diff options
| -rw-r--r-- | docs/reference/pygio-appinfo.xml | 115 | ||||
| -rw-r--r-- | docs/reference/pygio-icon.xml | 99 | ||||
| -rw-r--r-- | 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> |